diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md index fc4589a..2deb9f9 100644 --- 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,7 +111,7 @@ 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: @@ -98,19 +119,19 @@ You will find the built documentation in `docs/_build/html`. """ ``` - 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/