From 609592e59ba1e30c050fc22bc978f3079721690d Mon Sep 17 00:00:00 2001 From: Luca Zeuch Date: Sat, 12 Oct 2024 20:33:35 +0200 Subject: [PATCH] meta: refine contribution guide The contributing guide was partly outdated, mentioning to run Hugo for building / previewing the site and was generally confusingly written, exhibiting a non-linear style. Update it such that it can now be read linearly, outlining the new preview / build process, explaining the markdown features we want contributors to use. We also now have a quick rundown of the superficial repository structure, hopefully enabling contributors to find relevant files faster when they're viewing the source tree. Also refine the commit message rambling to be clearer about the why of various requirements, such as the 50 (72) character header limit (GitHub breaks them at 72). Give hints as to when one should better split up their changes and when to use the commit message body. Explain what we use a sign-off for and reiterate that it is not required. As was recently the case, also mention what happens when there is a larger batch of pull requests open and why we don't merge them immediately one-by-one. Signed-off-by: Luca Zeuch --- .github/CONTRIBUTING.md | 244 ++++++++++++++++++++++++---------------- 1 file changed, 149 insertions(+), 95 deletions(-) diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md index c2517a6..b72bd8e 100644 --- a/.github/CONTRIBUTING.md +++ b/.github/CONTRIBUTING.md @@ -1,151 +1,205 @@ # Contributing Guidelines -## Got a Question? +## Got a Question? -Please do not open issues for general support such as "how to do reaction roles" — use the -[support server](https://discord.gg/4udtcA5) for that. +We welcome suggestions for improving the documentation on our issue tracker—outdated information, missing items, typos, +or clarity issues are all relevant. -To keep this tracker clean, we will systematically close issues regarding general support and redirect to the -aforementioned support server. +General support queries and possible bugs in YAGPDB are **not** in scope and will be closed without comment; use the +[support server] instead. -## Found a Bug? +[support server]: https://discord.gg/4udtcA5 -Do **not** use this tracker to file maybe-bugs in YAGPDB. We have a dedicated channel on the support server for that, to -which you can post after it was confirmed to be one. -Should there be general issues with the documentation (grammatical structure, general flow, clarification needed), do -feel free to open an issue clearly outlining what is wrong about it and consider suggesting how to fix it. +## Submission Guide -## Submission Guidelines +Thanks for contributing to the YAGPDB documentation! Please take a moment to review this document in order to make the +contribution process easy and effective for everyone involved. ### Requirements -- An [editorconfig](https://editorconfig.org)-capable (text) editor. -- The latest extended release of [Hugo](https://gohugo.io). -- Optional: a webserver to serve a release build of the website. +Small changes can be authored directly using the GitHub web interface, though we highly recommend an +[EditorConfig]-capable editor like VSCode or Neovim for any extended work. + +To preview your changes locally, you will also need [Node.js], [NPM], and the latest **extended** release of [Hugo]. NPM +should come along with installing Node.js by default. + +[Node.js]: https://nodejs.org/en +[NPM]: https://www.npmjs.com/ +[Hugo]: https://gohugo.io/installation +[EditorConfig]: https://editorconfig.org/ ### Instructions -1. Search this repo's issues and pull requests tab for any open or closed PRs / issues that relate to your submission. - You wouldn't want to duplicate existing efforts. +The usual set of steps to contribute to anything hosted on GitHub applies: fork the repository, clone the fork, +cut a new branch from `master`, make and commit your changes, and submit a pull request. We've outlined key parts of +this process below. + +> [!TIP] +> Though you could work directly on the `master` branch, it is recommended to isolate your changes into a separate +> branch. This way, you can work on multiple contributions simultaneously without them interfering with each other. +> To create a new branch, simply run `git switch -c master` in the cloned repository. + +#### Preparing Your Environment -2. [Fork](https://github.com/botlabs-gg/yagpdb-docs-v2/fork) and then clone your fork. +In your local clone, install the required dependencies via NPM by running the following command: -3. In your cloned repository, make your changes on a new branch stemming from `master`: +```shellsession +$ npm install +``` - ```shell - git switch -c my-branch master - ``` +This will ensure that you can fully build the documentation site locally, including the custom syntax highlighting we +use. -4. Launch the Hugo development environment via `hugo server`. It'll watch your worktree for changes and reload the page - when changes are detected. +#### Making Your Changes -5. Make your changes, ensuring that the page still builds in release mode via `hugo`. You may need to run `hugo mod - vendor` prior to that. +##### Markdown Features -6. Commit your changes using a descriptive commit message following our [commit message conventions](#commit). As a nice - bonus, GitHub should automatically fill in the [pull request template](PULL_REQUEST_TEMPLATE.md) with your formatted - message, saving you some work. +The documentation is written in Markdown, with some additional shortcodes provided by the [Doks theme]; refer to its +documentation for a complete list of features. If you are writing or editing custom command-related code, please use the +`yag` language in fenced code blocks for accurate syntax highlighting: -7. Push your branch to GitHub: +````markdown +```yag +{{/* your YAGPDB custom command code here */}} +``` +```` - ```shell - git push origin my-branch - ``` +For consistency within the raw Markdown, please **do not** use the four-space indentation for code blocks, even if you +don't intend on highlighting them. -8. On GitHub, submit a pull request to `botlabs-gg:master` +Use headers if possible to structure your content more clearly. Hugo will generate a table of contents based on those +headers, displaying up to `h3` (`###`) headers on the right side of the page. Algolia indexes by section (which headers +introduce), so it's beneficial to have a clear structure to improve search results. -Lastly, if you are unsure where to place a potential new file, do not hesitate to ask either on the support server or -open an issue. +Ensure each header is unique in its respective file—if necessary, you can give them a custom ID to make them unique: -## Commit Message Format +```markdown +### non-unique header{#my-unique-id} +``` -Formatting commit messages according to a specification makes it easier to parse and read commit history. +This issue tends to especially arise on levels with a lower level of granularity, like `h4` (`####`) or `h5` (`#####`). +It helps to have a linter or similar tools that tell you when a header becomes ambiguous. -Each commit message consists of a header, a body, and a footer: +##### Repository Structure ```txt -
- - - -