docs: update contributing

hynek · Jul 18, 2024 · 65719d7 · 65719d7
1 parent 0a3bb8a
commit 65719d7
Showing 1 changed file with 98 additions and 54 deletions.
diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md
@@ -1,31 +1,48 @@
 # How To Contribute
 
-First off, thank you for considering contributing!
-It's people like *you* who make it is such a great tool for everyone.
-
-This document is mainly to help you to get started by codifying tribal knowledge and expectations and make it more accessible to everyone.
-But don't be afraid to open half-finished PRs and ask questions if something is unclear!
+> [!IMPORTANT]
+> This document is mainly to help you to get started by codifying tribal knowledge and expectations and make it more accessible to everyone.
+> But don't be afraid to open half-finished PRs and ask questions if something is unclear!
 
 
 ## Workflow
 
+> [!WARNING]
+> Before starting to work on **feature** pull requests, **please** discuss your idea with us on the [Ideas board](https://github.com/hynek/stamina/discussions/categories/ideas) to save you time and effort!
+
+First off, thank you for considering to contribute!
+It's people like *you* who make this project such a great tool for everyone.
+
 - No contribution is too small!
   Please submit as many fixes for typos and grammar bloopers as you can!
+
 - Try to limit each pull request to *one* change only.
-- Since we squash on merge, it's up to you how you handle updates to the main branch.
-  Whether you prefer to rebase on main or merge `main` into your branch, do whatever is more comfortable for you.
+
+- Since we squash on merge, it's up to you how you handle updates to the `main` branch.
+  Whether you prefer to rebase on `main` or merge `main` into your branch, do whatever is more comfortable for you.
+
 - *Always* add tests and docs for your code.
   This is a hard rule; patches with missing tests or documentation won't be merged.
-- Consider updating [CHANGELOG.md][changelog] to reflect the changes as observed by people using this library.
-- Make sure your changes pass our [CI].
+
+- Consider updating [`CHANGELOG.md`](../CHANGELOG.md) to reflect the changes as observed by people using this library.
+
+- Make sure your changes pass our [CI](https://github.com/hynek/stamina/actions).
   You won't get any feedback until it's green unless you ask for it.
-- Don’t break [backwards-compatibility].
+  For the CI to pass, the coverage must be 100%.
+  If you have problems to test something, open anyway and ask for advice.
+  In some situations, we may agree to add an `# pragma: no cover`.
+
+- Once you've addressed review feedback, make sure to bump the pull request with a short note, so we know you're done.
+
+- Don't break [backwards-compatibility](SECURITY.md).
 
 
 ## Local Development Environment
 
-You can (and should) run our test suite using [Nox].
-However, you’ll probably want a more traditional environment as well.
+First, **fork** the repository on GitHub and **clone** it using one of the alternatives that you can copy-paste by pressing the big green button labeled `<> Code`.
+
+You can (and should) run our test suite using [Nox](https://nox.thea.codes/).
+However, you'll probably want a more traditional environment as well.
 
 We recommend using the Python version from the `.python-version-default` file in the project's root directory, because that's the one that is used in the CI by default, too.
 
@@ -42,29 +59,33 @@ test -d .venv || uv venv --python python$(cat .python-version-default)
 . .venv/bin/activate
 ```
 
----
+> [!WARNING]
+> - **Before** you start working on a new pull request, use the "*Sync fork*" button in GitHub's web UI to ensure your fork is up to date.
+> - **Always create a new branch off `main` for each new pull request.**
+>   Yes, you can work on `main` in your fork and submit pull requests.
+>   But this will *inevitably* lead to you not being able to synchronize your fork with upstream and having to start over.
 
-You can now install the package with its development dependencies into the virtual environment:
+Change into the newly created directory and after activating a virtual environment, install an editable version of this project along with its tests requirements:
 
 ```console
-$ pip install -e .[dev]
+$ pip install -e .[dev]  # or `uv pip install -e .[dev]`
 ```
 
-This will also install [Nox] for you.
+This will also install Nox for you.
 
 Now you can run the test suite:
 
 ```console
-$ python -m pytest
+$ python -Im pytest
 ```
 
-For documentation, you can use:
+When working on the documentation, use:
 
 ```console
 $ nox --session docs -- watch
 ```
 
-This will build the documentation, and then watch for changes and rebuild it whenever you save a file.
+This will build the documentation, watch for changes, and rebuild it whenever you save a file.
 
 To just build the documentation and run doctests, use:
 
@@ -77,8 +98,8 @@ You will find the built documentation in `docs/_build/html`.
 
 ## Code
 
-- Obey [PEP 8] and [PEP 257].
-  We use the `"""`-on-separate-lines style for docstrings with [Napoleon]-style API documentation:
+- Obey [PEP 8](https://peps.python.org/pep-0008/) and [PEP 257](https://peps.python.org/pep-0257/).
+  We use the `"""`-on-separate-lines style for docstrings with [Napoleon](https://www.sphinx-doc.org/en/master/usage/extensions/napoleon.html)-style API documentation:
 
   ```python
   def func(x: str, y: int) -> str:
@@ -90,27 +111,27 @@ You will find the built documentation in `docs/_build/html`.
 
           y:
             Another very important argument, but its description is so long
-            that it doesn't fit on one line. So we start the whole block on a
+            that it doesn't fit on one line. So, we start the whole block on a
             fresh new line to keep the block together.
 
       Returns:
           The result of doing something.
       """
   ```
 
-  Please note that unlike everything else, the API docstrings are still [reStructuredText].
+  Please note that unlike everything else, the API docstrings are still reStructuredText.
 
-- If you add or change public APIs, tag the docstring using `..  versionadded:: 23.1.0 WHAT` or `..  versionchanged:: 23.1.0 WHAT`.
-  We follow CalVer, so the next version will be the current with with the middle number incremented (e.g. `23.1.0` -> `23.2.0`).
+- If you add or change public APIs, tag the docstring using `..  versionadded:: 24.1.0 WHAT` or `..  versionchanged:: 24.1.0 WHAT`.
+  We follow CalVer, so the next version will be the current with with the middle number incremented (for example, `24.1.0` -> `24.2.0`).
 
-- We use [Ruff] to sort our imports, and we follow the [Black] code style with a line length of 79 characters.
-  As long as you run our full [Nox] suite before committing, or install our [*pre-commit*] hooks, you won't have to spend any time on formatting your code at all.
+- We use [Ruff](https://ruff.rs/) to sort our imports, and we follow the [Black](https://github.com/psf/black) code style with a line length of 79 characters.
+  As long as you run our full *tox* suite before committing, or install our [*pre-commit*](https://pre-commit.com/) hooks (ideally you'll do both -- see [*Local Development Environment*](#local-development-environment) above), you won't have to spend any time on formatting your code at all.
   If you don't, CI will catch it for you -- but that seems like a waste of your time!
 
 
 ## Tests
 
-- Write your asserts as `expected == actual` to line them up nicely and leave an empty line before them:
+- Write your asserts as `expected == actual` to line them up nicely, and leave an empty line before them:
 
   ```python
   x = f()
@@ -119,24 +140,27 @@ You will find the built documentation in `docs/_build/html`.
   assert "foo" == x._a_private_attribute
   ```
 
-- To run the test suite, all you need is a recent [Nox].
-  It will ensure the test suite runs with all dependencies against all Python versions just as it will in our CI.
+- You can run  the test suite runs with all (optional) dependencies against all supported Python versions just as it will in our CI by running `tox`.
 
-- Write [good test docstrings].
+- Write [good test docstrings](https://jml.io/test-docstrings/).
 
 
 ## Documentation
 
-- Use [semantic newlines] in Markdown files (files ending in `.md`):
+- Use [semantic newlines] in [reStructuredText](https://www.sphinx-doc.org/en/stable/usage/restructuredtext/basics.html) (`*.rst`) and [Markdown](https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax) (`*.md`) files:
 
   ```markdown
   This is a sentence.
   This is another sentence.
+
+  This is a new paragraph.
   ```
 
 - If you start a new section, add two blank lines before and one blank line after the header except if two headers follow immediately after each other:
 
   ```markdown
+  # Main Header
+
   Last line of previous section.
 
 
@@ -147,41 +171,61 @@ You will find the built documentation in `docs/_build/html`.
   First line of new section.
   ```
 
-- If your change is noteworthy, add an entry to the [changelog].
-  Use [semantic newlines], and add a link to your pull request:
+
+### Changelog
+
+If your change is interesting to end-users, there needs to be an entry in our `CHANGELOG.md`, so they can learn about it.
+
+- The changelog follows the [Keep a Changelog](https://keepachangelog.com/en/1.0.0/) standard.
+  Add the best-fitting section if it's missing for the current release.
+  We use the following order: `Security`, `Removed`, `Deprecated`, `Added`, `Changed`, `Fixed`.
+
+- As with other docs, please use [semantic newlines] in the changelog.
+
+- Make the last line a link to your pull request.
+  You probably have to open it first to know the number.
+
+- Leave an empty line between entries, so it doesn't look like a wall of text.
+
+- Refer to all symbols by their fully-qualified names.
+  For example, `stamina.Foo` -- not just `Foo`.
+
+- Wrap symbols like modules, functions, or classes into backticks, so they are rendered in a `monospace font`.
+
+- Wrap arguments into asterisks so they are *italicized* like in API documentation:
+  `Added new argument *an_argument*.`
+
+- If you mention functions or methods, add parentheses at the end of their names:
+  `stamina.func()` or `stamina.Class.method()`.
+  This makes the changelog a lot more readable.
+
+- Prefer simple past tense or constructions with "now".
+  In the `Added` section, you can leave out the "Added" prefix:
 
   ```markdown
-  - Added `stamina.func()` that does foo.
+  ### Added
+
+  - `stamina.func()` that does foo.
     It's pretty cool.
     [#1](https://github.com/hynek/stamina/pull/1)
 
+
+  ### Fixed
+
   - `stamina.func()` now doesn't crash the Large Hadron Collider anymore.
     That was a nasty bug!
     [#2](https://github.com/hynek/stamina/pull/2)
   ```
 
----
 
-Again, this list is mainly to help you to get started by codifying tribal knowledge and expectations.
-If something is unclear, feel free to ask for help!
+## See You on GitHub!
 
-Please note that this project is released with a Contributor [Code of Conduct].
-By participating in this project you agree to abide by its terms.
-Please report any harm to [Hynek Schlawack] in any way you find appropriate.
+Again, this whole file is mainly to help you to get started by codifying tribal knowledge and expectations to save you time and turnarounds.
+It is **not** meant to be a barrier to entry, so don't be afraid to open half-finished PRs and ask questions if something is unclear!
 
+Please note that this project is released with a Contributor [Code of Conduct](CODE_OF_CONDUCT.md).
+By participating in this project you agree to abide by its terms.
+Please report any harm to [Hynek Schlawack](https://hynek.me/about/) in any way you find appropriate.
 
 
-[ci]: https://github.com/hynek/stamina/actions
-[backwards-compatibility]: https://github.com/hynek/stamina/blob/main/.github/SECURITY.md
-[changelog]: https://github.com/hynek/stamina/blob/main/CHANGELOG.md
-[nox]: https://nox.thea.codes/
 [semantic newlines]: https://rhodesmill.org/brandon/2012/one-sentence-per-line/
-[Ruff]: https://github.com/astral-sh/ruff
-[*pre-commit*]: https://pre-commit.com/
-[Black]: https://github.com/psf/black
-[reStructuredText]: https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html
-[good test docstrings]: https://jml.io/test-docstrings/
-[code of conduct]: https://github.com/hynek/stamina/blob/main/.github/CODE_OF_CONDUCT.md
-[Hynek Schlawack]: https://hynek.me/about/
-[pep 257]: https://peps.python.org/pep-0257/
-[pep 8]: https://peps.python.org/pep-0008/