diff --git a/content/contributing/docs.md b/content/contributing/docs.md index 1663c52..bc867c9 100644 --- a/content/contributing/docs.md +++ b/content/contributing/docs.md @@ -85,6 +85,18 @@ consistent, it's ok that existing docs use alternate spellings. [American spelling]: https://www.oxfordinternationalenglish.com/differences-in-british-and-american-spelling/ [serial comma]: https://www.grammarly.com/blog/punctuation-capitalization/what-is-the-oxford-comma/ +## Docstrings and Code Comments + +Docstrings on public methods are for users: describe what the function does and +how to call it. Implementation rationale and historical context belong in code +comments (`#`) next to the relevant lines, where maintainers will see it. + +Do not include GitHub issue or PR numbers or links anywhere in the codebase: not +in docstrings, not in code comments, not in documentation files. Docs and +comments must stand on their own. The only place to reference issues or PRs is +in changelog entries. Links to external projects (like CPython) are acceptable +when the code works around a reported issue in that project. + ## Translating Docs Currently, the community is working on translating Flask's documentation. We may diff --git a/content/contributing/pr.md b/content/contributing/pr.md index 544d56f..d2fb8c0 100644 --- a/content/contributing/pr.md +++ b/content/contributing/pr.md @@ -14,6 +14,15 @@ set up your development environment and run tests. This guide assumes you've done that and used the GitHub CLI to fork and clone the repository and add the upstream remote. +## AI-Generated Contributions + +AI-generated PRs and issues are closed on sight, without review or discussion. +This applies regardless of code quality or correctness. + +AI-generated contributions must not be revived, cleaned up, or used as a base +for further work. Starting a new PR "on top of" a closed AI submission counts +as laundering and will be treated the same way. + ## Create a Branch To work on a bug or documentation fix, switch to the `stable` branch (if the @@ -93,6 +102,24 @@ $ git rebase --continue See [Help with Git](git.md) for more information about rebasing. +## PR Scope + +Keep PRs focused on a single fix or feature. Do not bundle unrelated refactors, +type annotation changes, or test reorganizations with a bug fix. If a PR touches +too many concerns at once, it becomes hard to review and will be sent back. + +Use consistent wording across the PR title, commit message, changelog entry, and +docstring `versionchanged` entry. They should all describe the same thing the +same way. + +Squash messy commit chains before merging, or use GitHub's squash-merge. Long +chains of fixup commits make `git blame` useless. + +Chaining PRs that depend on each other is acceptable, as long as each PR +explicitly states which PR it follows up on and which comes next. Maintainers +may request the reordering of the merge sequence based on review feedback. +Rebasing a chain to account for a reorder is expected rework, not a chore. + ## Create the Pull Request Use the GitHub CLI to start submitting your work as a pull request. Specify the @@ -149,3 +176,25 @@ Once the PR is merged, the corresponding issue will be closed as well. Both the issue and PR will be marked with a milestone indicating the future release that will contain it. You can watch a repository's releases to get notified when that happens. + +## Branch Protection + +No direct commits to `main` or `stable` are allowed. All changes must go +through a pull request so that other maintainers have a chance to review each +other's work. The only exception is release-related housekeeping: changelog +initialization, changelog consolidation, workflow fixes, tagging, and +`stable`/`main` syncs. + +## Reviving Closed or Inaccessible PRs + +When a human-contributed PR is no longer accessible (which can happen when the +original author deleted their fork), any maintainer may recreate it from scratch +or from the `.patch` URL. + +A maintainer who revives a closed PR must: + +- State clearly in the new PR body that the work originated from another PR, + and link to the original. +- Squash the original commits. +- Credit the original author with a `Co-Authored-By` trailer in the commit + metadata. diff --git a/content/contributing/tests.md b/content/contributing/tests.md index c548552..19d79a1 100644 --- a/content/contributing/tests.md +++ b/content/contributing/tests.md @@ -59,9 +59,17 @@ Tests are generally organized by topic in `test_{topic}.py` files, and within each file each test is a `test_{specific}` function. The test function name should be unique, somewhat descriptive without being too long. +Do not create a new test file for a single bug fix. Add a parametrization or a +new test function to an existing, related test file. + Each test should test one thing, using `assert` statements to check expected properties of that one thing. If you have multiple test cases, use the [`@pytest.mark.parametrize`][parametrize] decorator to run the same test with different arguments. +When a test covers many input combinations, prefer a flat parametrize list with +a simple test body over a complex test body with fewer parameters. A complex +test body tends to mirror the implementation logic it is supposed to verify, +which defeats the purpose. + [parametrize]: https://docs.pytest.org/en/stable/how-to/parametrize.html#pytest-mark-parametrize-parametrizing-test-functions