docs: update contributing

.github/CONTRIBUTING.md

@@ -1,4 +1,4 @@
-# Contributing Guide
+# How To Contribute
 
 > [!IMPORTANT]
 > This document is mainly to help you to get started by codifying tribal knowledge and expectations and make it more accessible to everyone.
@@ -10,26 +10,39 @@
 > [!WARNING]
 > Before starting to work on **feature** pull requests, **please** discuss your idea with us on the [Ideas board](https://github.com/hynek/svcs/discussions/categories/ideas) to save you time and effort!
 
-First off, thank you for considering contributing!
-It's people like *you* who make it is such a great tool for everyone.
+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.
+
 - *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/svcs/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 [*tox*].
-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 [*tox*](https://tox.wiki/).
+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.
 
@@ -46,23 +59,28 @@ test -d .venv || uv venv --python python$(cat .python-version-default)
 . .venv/bin/activate
 ```
 
-Next, **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`.
+> [!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]  # or `uv pip install -e .[dev]`
 ```
 
-This will also install [*tox*] for you.
+This will also install *tox* for you.
+If you use *uv* and want to make the *tox* runs faster, you can also additionally install the [*tox-uv*](https://github.com/tox-dev/tox-uv) plugin using `uv pip install tox-uv`.
 
 Now you can run the test suite:
 
 ```console
 $ python -Im pytest
 ```
 
-For documentation, you can use:
+When working on the documentation, use:
 
 ```console
 $ tox run -e docs-watch
@@ -81,8 +99,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:
@@ -94,27 +112,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 [*tox*] 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()
@@ -123,18 +141,20 @@ You will find the built documentation in `docs/_build/html`.
   assert "foo" == x._a_private_attribute
   ```
 
-- You can run  the test suite runs with all (optional) dependencies against all Python versions just as it will in our CI by running `tox`.
+- 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 and reStructuredText files (files ending in `.md` and `.rst`):
+- 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:
@@ -155,9 +175,9 @@ You will find the built documentation in `docs/_build/html`.
 
 ### Changelog
 
-If your change is interesting to end-users, there needs to be an entry in our [changelog], so they can learn about it.
+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.
+- 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`.
 
@@ -168,6 +188,9 @@ If your change is interesting to end-users, there needs to be an entry in our [c
 
 - 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, `svcs.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:
@@ -201,23 +224,9 @@ If your change is interesting to end-users, there needs to be an entry in our [c
 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].
+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] in any way you find appropriate.
+Please report any harm to [Hynek Schlawack](https://hynek.me/about/) in any way you find appropriate.
 
 
-[ci]: https://github.com/hynek/svcs/actions
-[backwards-compatibility]: https://github.com/hynek/svcs/blob/main/.github/SECURITY.md
-[changelog]: https://github.com/hynek/svcs/blob/main/CHANGELOG.md
-[*tox*]: https://tox.wiki/
 [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
-[Napoleon]: https://www.sphinx-doc.org/en/master/usage/extensions/napoleon.html
-[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/svcs/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/