work on contributing guide

remove links to unfinished pages

content/contributing/docs.md

@@ -1,14 +1,98 @@
 # Contribute to Documentation
 
-We use [Sphinx][] and [ReStructuredText][] to write the documentation.
+We use [Sphinx] to build the documentation. Historically, this has used
+[reStructuredText] `.rst` as the syntax. You may see some pages written in
+[Markdown] `.md` if the `myst-parser` dependency has been added to
+the project. Docstrings in code must always use rST.
+
+[Sphinx]: https://sphinx-doc.org
+[reStructuredText]: https://docutils.sourceforge.io/rst.html
+[Markdown]: https://commonmark.org
+
+## Work on the `stable` Branch
+
+**If you are fixing or improving existing docs, or writing about existing
+features, you want to branch off of the `stable` branch, as well as target the
+`stable` branch in the PR.**
+
+If you use GitHub's UI to quickly edit a file, remember to select the `stable`
+branch from the dropdown first. Otherwise, you'll end up submitting the fix
+against `main`, and a maintainer will have to do extra work to retarget it.
+
+Changes to `stable` docs will show up within minutes of being merged. Changes to
+`main` will be unavailable until the next feature release. You'll rarely want to
+work off of `main` for docs, unless you're working on docs for a new unreleased
+feature.
+
+## Building Docs
 
 To build the docs locally, run `tox r -e docs`. To serve the docs locally, run
 `python -m http.server docs/_build/dirhtml`. Then go to <https://localhost:8000>
 in your browser to view the docs.
 
-Documentation is hosted by Read the Docs. They are built and deployed for any
-changes to the `main` and `A.B.x` feature branches. Each PR also generates a
-test build.
+Documentation is hosted by Read the Docs. It is deployed on every change to the
+`stable` branch. Each PR also generates a test build, which can be viewed by
+clicking the "readthedocs" build check in the PR.
 
-[Sphinx]: https://sphinx-doc.org
-[reStructuredText]: https://docutils.sourceforge.io/rst.html
+## Writing Docs
+
+Writing about how to write documentation is surprisingly hard! We generally like
+the ideas presented in [Diátaxis], which is a way of thinking about and doing
+documentation.
+
+[Diátaxis]: https://diataxis.fr
+
+It can be very hard to assess whether a change is _better_ rather than only
+_different_. Keep this in mind when deciding if you want to change something. If
+a sentence is clear and understandable, even if you would say it differently,
+then it should probably be left as-is.
+
+The most common type of docs contribution is a typo fix. Check if the typo
+happened in multiple places, and fix it everywhere. Don't submit typo fixes to
+code comments that aren't visible in the deployed docs, unless you're also
+working on that code. If you find multiple different typos, you can fix them in
+separate commits to one PR, rather than multiple PRs. Make sure the typo is
+really a typo, and not a correct sentence with a different meaning.
+
+The libraries' docs have been written by many people over more than a decade.
+This has introduced inconsistencies in style, focus, and technical level across
+different parts of documentation over time. We recognize that there are many
+ways in which documentation can be rewritten and improved. However, avoid huge
+rewrites unless you have already checked with maintainers. If you're changing
+more than a few sentences of text, and haven't received prior approval, you're
+probably doing too much at once. It is very hard to review such changes,
+especially from unknown users who we have not established trust with.
+
+### Style, Spelling, and Grammar
+
+Avoid referring to "you" or "we" outside of tutorials. State things directly;
+"to do X, use Y" rather than "if you want to do X, then you should use Y."
+
+Avoid phrases that might imply something is implicitly easy, such as "just do X"
+or "the reason is obviously Y". Users are coming to the docs because something
+wasn't obvious or easy for them at that moment.
+
+The documentation is in English. If you are not a native English speaker, that's
+OK, learners often catch issues that native speakers overlook. However, if a
+maintainer would have to alter a significant portion of your PR, that's not a
+great use of time. We also have a translation project, explained in the next
+section.
+
+Prefer [American spelling]. Use the [serial comma]; ("a, b, and c" rather than
+"a, b and c"). That said, do not create a PR that tries to make everything
+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/
+
+## Translating Docs
+
+Currently, the community is working on translating Flask's documentation. We may
+add other projects in the future.
+
+You can find the translation project and instructions on how to contribute here:
+<https://github.com/pallets-eco/flask-docs-translations>. We use [Weblate] to
+manage translations. You'll need an account there. Then you can use the UI to navigate
+to a language and find strings to translate.
+
+[Weblate]: https://weblate.org

content/contributing/features.md

@@ -1 +1,32 @@
 # Request a Feature
+
+If you feel that one of our libraries is missing something, you should request
+a new feature for it on the GitHub Issues tab. For example, Flask's is here:
+<https://github.com/pallets/flask/issues/>.
+
+The bar for accepting new features into many of our libraries is high. Our
+general philosophy is to provide a solid base framework that other libraries can
+extend, rather than blessing specific implementations in the core library. A
+feature request may be more successful if:
+
+-   If it's not possible to implement as an extension without changes to the
+    core.
+-   If there is one "correct" way to implement something.
+-   If the request is similar to or complements existing behavior.
+
+Before requesting a feature, try to determine if it has already been requested
+or implemented. Search existing issues and PRs, including closed issues and
+merged PRs. Requests that were previously rejected are likely to be rejected
+again unless (or even if) significant new reasoning is presented.
+
+Click the green "New issue" button at the top right to start. Include the
+following information in your post:
+
+-   Write a short, descriptive title.
+    -   Do not include prefixes such as "\[feature]"; maintainers will apply
+        real tags as needed.
+-   Describe what the feature should do.
+-   Include details such as links to relevant specs or previous discussions.
+-   Provide an example of a problem this feature would resolve. Consider if this
+    is problem solvable without changes to the library, such as by subclassing
+    or using an extension.

content/contributing/index.md

@@ -6,76 +6,87 @@ contribute to an open source project, see the next section for more ideas.
 If you would like to ask a question or open an issue or feature request, see
 these guides:
 
-1. [Ask a Question](questions.md)
-2. [Report an Issue](issues.md)
-    * [Report a **Security** Issue](../security.md)
-3. [Request a Feature](features.md)
+-   [Ask a Question](questions.md), which also covers how to contribute by
+    answering questions.
+-   [Report an Issue](issues.md)
+-   [Report a **Security** Issue](../security.md)
+-   [Request a Feature](features.md)
 
 If you would like to fix an issue or implement a feature, see these guides:
 
-1. [Start Here: Development Environment Setup](setup.md)
-2. [Create a Pull Request](pr.md)
-3. [Edit and Build Documentation](docs.md)
-4. [Write and Run Tests](tests.md)
+-   [Quick Reference](quick.md) If you're already familiar with contributing,
+    this provides an essential overview of the following guides.
+-   Start Here: Detailed Development Environment Setup - Coming Soon
+-   [Create a Pull Request](pr.md)
+-   Write and Run Tests - Coming Soon
+-   Static Type Checks - Coming Soon
+-   [Edit and Build Documentation](docs.md)
+-   Changelog Style - Coming Soon
+-   Linting and Formatting - Coming Soon
 
 If you're getting more involved as a community or team member, see these guides:
 
-* [Triaging Issues](triage.md) covers many of the things the team looks for in
-  good issue reports and requests.
-* [Environment](environment.md) gives an overview of the tools we use.
+-   [Triaging Issues](triage.md) covers many of the things the team looks for in
+    good issue reports and requests.
+-   Reviewing and Merging PRs - Coming Soon
+-   Project Layout - Coming Soon, explains our standard project structure, tools,
+    and configurations.
+-   Git Techniques - Coming Soon, talks about various git behaviors and commands.
+-   [Making a Release](release.md)
 
 You can also support us by [making a donation](../donate.md).
 
 ## What to Work On
 
 Anyone is welcome to work on any open ticket in any project's issue tracker,
-no need to ask first. Before starting, check if anyone else is assigned to the
+without asking first. Before starting, check if anyone else is assigned to the
 issue, or if there are any linked open pull requests. Look through the issue for
 that information as well as discussion and other linked issues for context.
 
-Besides the core Pallets projects, there is an entire [ecosystem][] of
-extensions built on top of them. We also have our own dependencies that we use
-for our [development environment][]. Improving the ecosystem we're part of is a
-great way to contribute to Pallets.
+Besides the core Pallets projects, there is an entire [ecosystem] of extensions
+built on top of them. We also have our own dependencies that we use for our
+[development environment]. Improving the ecosystem we're part of is a great way
+to contribute to Pallets.
 
 [ecosystem]: ../ecosystem.md
-[development environment]: environment.md
+[development environment]: layout
 
 Writing code is not the only way to contribute to an open source project. Other
 activities are just as helpful. Some ideas that are too broad for individual
 issues include:
 
-* Improve this contributing guide!
-* Improve documentation.
-    * Identify common and popular questions from Stack Overflow. We want users
-      to find official information from our documentation first. Perhaps we need
-      a new page for a topic, or need to mention a specific error message.
-    * Add or improve translations. We also want to improve the workflow around
-      updating and publishing translations.
-    * Our documentation is extensive, but it's been written over a long period
-      of time by many people. It could use the attention of people with
-      technical writing and editing skills.
-* Improve how tests are organized and written to use modern pytest idioms.
-    * Some files have grown very large, or tests are not grouped well, or still
-      use `unittest` idioms. Perhaps tests can be split into more files, or use
-      pytest's parametrization feature.
-    * Improve test coverage by adding tests for lines and branches that are
-      not covered.
-* Improve static type annotations. We target mypy primarily, but would also like
-  to improve compatibility with pyright. We also want to ensure we are using
-  types correctly, and add tests.
-* Answer questions on GitHub Discussions and our Discord chat server.
-  Referencing canonical sources and providing explanation beyond the immediate
-  answer creates resources for others to find later and enables them to answer
-  in turn.
+-   Improve this contributing guide!
+-   Improve documentation.
+    -   Identify common and popular questions from Stack Overflow. We want users
+        to find official information from our documentation first. Perhaps we
+        need a new page for a topic, or need to mention a specific error
+        message.
+    -   Add or improve translations. We also want to improve the workflow around
+        updating and publishing translations.
+    -   Our documentation is extensive, but it's been written over a long period
+        of time by many people. It could use the attention of people with
+        technical writing and editing skills.
+-   Improve how tests are organized and written to use modern pytest idioms.
+    -   Some files have grown very large, or tests are not grouped well, or
+        still use `unittest` idioms. Perhaps tests can be split into more files,
+        or use pytest's parametrization feature.
+    -   Improve test coverage by adding tests for lines and branches that are
+        not covered.
+-   Improve static type annotations. We target mypy primarily, but would also
+    like to improve compatibility with pyright. We also want to ensure we are
+    using types correctly, and add tests.
+-   Answer questions on GitHub Discussions and our Discord chat server.
+    Referencing canonical sources and providing explanation beyond the immediate
+    answer creates resources for others to find later and enables them to answer
+    in turn.
 
 ## Get Help Contributing
 
-If you need help with the contributing process, or want to discuss an issue or
-pull request you're working on, you can use the project-specific channels on
-our Discord chat server: https://discord.gg/pallets.
+If you need help with the contributing process beyond the guides here, or want
+to discuss an issue or pull request you're working on, use the `#contributing`
+channel on our Discord chat server: <https://discord.gg/pallets>.
 
-You can also use comments on the issue or pull request. After getting help or
+You can also write comments on the issue or pull request. After getting help or
 researching about an issue, it's helpful to leave a comment there in order to
 keep public notes or help the next contributor.
 

content/contributing/issues.md

@@ -1,12 +1,33 @@
 # Report an Issue
 
-Include the following information in your post:
+If you encounter an unexpected issue when using our libraries, you should report
+it on the GitHub Issues tab. For example, Flask's is here:
+<https://github.com/pallets/flask/issues/>.
 
-- Describe what you expected to happen.
-- Include a [minimal reproducible example][] to help us identify the issue. This
-  also helps check that the issue is not with your own code.
-- Describe what actually happened. Include the full traceback if there was an exception.
-- List the version of Python and the Pallets library you're using. Check if this
-  issue is already fixed in the latest release or the latest code in the repository.
+If you have questions about your own code or how to use the libraries, read
+[how to ask questions](questions.md). Don't use the issue tracker to ask
+questions.
 
-[minimal reproducible example]: https://stackoverflow.com/help/minimal-reproducible-example
+Before reporting an issue, try to determine if it has already been reported or
+fixed. Search existing issues and PRs, including closed issues and merged PRs.
+Search for similar phrases, code, and errors. Check that you're using the latest
+release.
+
+You don't need to report typos in documentation, unless you're unsure. Instead,
+submitting a PR would probably be faster. This is _only_ the case for typos, for
+everything else open an issue.
+
+Click the green "New issue" button at the top right to start. Include the
+following information in your post:
+
+-   Write a short, descriptive title.
+    -   Do not include prefixes such as "\[bug]" or "\[docs]"; maintainers will
+        apply real tags as needed.
+    -   Do not include a version number in the title.
+-   Describe what you expected to happen.
+-   Include a [minimal reproducible example] to help us identify the issue. This
+    also helps check that the issue is not with your own code.
+-   Describe what actually happened. Include the full traceback if there was an
+    exception.
+-   List the version of Python and the project you're using. Check if this issue
+    is already fixed in the latest release, or in `stable` or `main`.

content/contributing/environment.md → content/contributing/layout.md

@@ -3,10 +3,15 @@
 Every project uses the same project layout and tools. It is helpful to be aware
 of them and their documentation when contributing.
 
+Keeping every project consistent makes it easy for people to move between
+projects. The more a project begins to diverge, the more likely it is to
+cause an issue at an inopportune time. If something here is changed in one
+project, it should be applied to all others as well.
+
 ## Requirements Files
 
-Each development environment uses a requirements file and the [pip-tools][] and
-[pip-compile-multi][] tools to pin versions. This ensures that tests and builds
+Each development environment uses a requirements file and the [pip-tools] and
+[pip-compile-multi] tools to pin versions. This ensures that tests and builds
 are reproducible when setting up a new environment or looking at previous tags.
 
 The `requirements` folder contains `.in` files that list the direct, unpinned
@@ -20,16 +25,16 @@ We do not use Dependabot to update these files as it is too noisy.
 
 ## Tests
 
-[pytest][] is used to run the tests, found in the `tests` folder.
+[pytest] is used to run the tests, found in the `tests` folder.
 
-[tox][] is used to run different test environments, including Python versions,
+[tox] is used to run different test environments, including Python versions,
 style checks, documentation, and typing. The `tox.ini` file configures this.
 
-We do not currently run [coverage][]. While our test suite is fairly robust,
+We do not currently run [coverage]. While our test suite is fairly robust,
 we don't have consistent enough coverage to make the reports useful at this
 time. We found that it does not impact our release quality.
 
-[mypy][] is used for static type checking. Other tools may not give the same
+[mypy] is used for static type checking. Other tools may not give the same
 results.
 
 See [here](tests.md) for information about writing, running, and improving
@@ -42,12 +47,12 @@ tests and test coverage.
 
 ## Documentation
 
-[Sphinx][] is used to build the documentation. The `docs` folder contains `.rst`
-files, which are [ReStructuredText][].
+[Sphinx] is used to build the documentation. The `docs` folder contains `.rst`
+files, which are [ReStructuredText].
 
-[Pallets-Sphinx-Themes][] contains the designs and extensions the projects use.
+[Pallets-Sphinx-Themes] contains the designs and extensions the projects use.
 
-The docs are built and hosted on [Read the Docs][]. It will also check that the
+The docs are built and hosted on [Read the Docs]. It will also check that the
 docs build for pull requests.
 
 See [here](docs.md) for information about writing and building documentation.
@@ -58,21 +63,21 @@ See [here](docs.md) for information about writing and building documentation.
 
 ## Code Style
 
-Code style tools are run automatically on each commit using [pre-commit][].
+Code style tools are run automatically on each commit using [pre-commit].
 The `.pre-commit-config.yaml` file pins the versions of each tool.
-[pre-commit.ci][] runs these checks and commits fixes automatically on pull
+[pre-commit.ci] runs these checks and commits fixes automatically on pull
 requests. It will also make PRs to update the pinned versions each month.
 
 See [setup](setup.md) for how to enable pre-commit.
 
-[black][] enforces code formatting.
+[black] enforces code formatting.
 
-[flake8][] enforces style "lint" rules. [flake8-bugbear][] catches more
+[flake8] enforces style "lint" rules. [flake8-bugbear] catches more
 opinionated rules.
 
-[pyupgrade][] enforces using modern syntax for the Python versions we support.
+[pyupgrade] enforces using modern syntax for the Python versions we support.
 
-[reorder_python_imports][] enforces a standard format and order for all imports
+[reorder_python_imports] enforces a standard format and order for all imports
 at the top of files.
 
 [pre-commit]: https://pre-commit.com