From 5da10abee7b9479df15a5d8ac022e7646430e428 Mon Sep 17 00:00:00 2001 From: Sviatoslav Sydorenko Date: Thu, 14 Dec 2023 04:42:24 +0100 Subject: [PATCH] =?UTF-8?q?=F0=9F=93=9D=20Add=20change=20note=20guidelines?= =?UTF-8?q?=20to=20docs?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- CHANGES/README.rst | 109 +++++++++++++++++++++++++++++++ docs/contributing/guidelines.rst | 28 ++++++++ docs/index.rst | 6 ++ 3 files changed, 143 insertions(+) create mode 100644 CHANGES/README.rst create mode 100644 docs/contributing/guidelines.rst diff --git a/CHANGES/README.rst b/CHANGES/README.rst new file mode 100644 index 00000000..be4c7c92 --- /dev/null +++ b/CHANGES/README.rst @@ -0,0 +1,109 @@ +.. _Adding change notes with your PRs: + +Adding change notes with your PRs +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +It is very important to maintain a log for news of how +updating to the new version of the software will affect +end-users. This is why we enforce collection of the change +fragment files in pull requests as per `Towncrier philosophy`_. + +The idea is that when somebody makes a change, they must record +the bits that would affect end-users only including information +that would be useful to them. Then, when the maintainers publish +a new release, they'll automatically use these records to compose +a change log for the respective version. It is important to +understand that including unnecessary low-level implementation +related details generates noise that is not particularly useful +to the end-users most of the time. And so such details should be +recorded in the Git history rather than a changelog. + +Alright! So how to add a news fragment? +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +``frozenlist`` uses `towncrier `_ +for changelog management. +To submit a change note about your PR, add a text file into the +``CHANGES/`` folder. It should contain an +explanation of what applying this PR will change in the way +end-users interact with the project. One sentence is usually +enough but feel free to add as many details as you feel necessary +for the users to understand what it means. + +**Use the past tense** for the text in your fragment because, +combined with others, it will be a part of the "news digest" +telling the readers **what changed** in a specific version of +the library *since the previous version*. You should also use +reStructuredText syntax for highlighting code (inline or block), +linking parts of the docs or external sites. +If you wish to sign your change, feel free to add ``-- by +:user:`github-username``` at the end (replace ``github-username`` +with your own!). + +Finally, name your file following the convention that Towncrier +understands: it should start with the number of an issue or a +PR followed by a dot, then add a patch type, like ``feature``, +``doc``, ``contrib`` etc., and add ``.rst`` as a suffix. If you +need to add more than one fragment, you may add an optional +sequence number (delimited with another period) between the type +and the suffix. + +In general the name will follow ``..rst`` pattern, +where the categories are: + +- ``bugfix``: A bug fix for something we deemed an improper undesired + behavior that got corrected in the release to match pre-agreed + expectations. +- ``feature``: A new behavior, public APIs. That sort of stuff. +- ``deprecation``: A declaration of future API removals and breaking + changes in behavior. +- ``breaking``: When something public gets removed in a breaking way. + Could be deprecated in an earlier release. +- ``doc``: Notable updates to the documentation structure or build + process. +- ``packaging``: Notes for downstreams about unobvious side effects + and tooling. Changes in the test invocation considerations and + runtime assumptions. +- ``contrib``: Stuff that affects the contributor experience. e.g. + Running tests, building the docs, setting up the development + environment. +- ``misc``: Changes that are hard to assign to any of the above + categories. + +A pull request may have more than one of these components, for example +a code change may introduce a new feature that deprecates an old +feature, in which case two fragments should be added. It is not +necessary to make a separate documentation fragment for documentation +changes accompanying the relevant code changes. + +Examples for adding changelog entries to your Pull Requests +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +File :file:`CHANGES/603.removal.1.rst`: + +.. code-block:: rst + + Dropped Python 3.5 support; Python 3.6 is the minimal supported Python + version -- by :user:`webknjaz`. + +File :file:`CHANGES/550.bugfix.rst`: + +.. code-block:: rst + + Started shipping Windows wheels for the x86 architecture + -- by :user:`Dreamsorcerer`. + +File :file:`CHANGES/553.feature.rst`: + +.. code-block:: rst + + Added support for ``GenericAliases`` (``MultiDict[str]``) under Python 3.9 + and higher -- by :user:`mjpieters`. + +.. tip:: + + See :file:`towncrier.toml` for all available categories + (``tool.towncrier.type``). + +.. _Towncrier philosophy: + https://towncrier.readthedocs.io/en/actual-freaking-docs/#philosophy diff --git a/docs/contributing/guidelines.rst b/docs/contributing/guidelines.rst new file mode 100644 index 00000000..f0413b8d --- /dev/null +++ b/docs/contributing/guidelines.rst @@ -0,0 +1,28 @@ +----------------- +Contributing docs +----------------- + +We use Sphinx_ to generate our docs website. You can trigger +the process locally by executing: + + .. code-block:: shell-session + + $ make doc + +It is also integrated with `Read The Docs`_ that builds and +publishes each commit to the main branch and generates live +docs previews for each pull request. + +The sources of the Sphinx_ documents use reStructuredText as a +de-facto standard. But in order to make contributing docs more +beginner-friendly, we've integrated `MyST parser`_ allowing us +to also accept new documents written in an extended version of +Markdown that supports using Sphinx directives and roles. `Read +the docs `_ to learn more on how to use it. + +.. _MyST docs: https://myst-parser.readthedocs.io/en/latest/using/intro.html#writing-myst-in-sphinx +.. _MyST parser: https://pypi.org/project/myst-parser/ +.. _Read The Docs: https://readthedocs.org +.. _Sphinx: https://www.sphinx-doc.org + +.. include:: ../../CHANGES/README.rst diff --git a/docs/index.rst b/docs/index.rst index 8f4effb4..c1945b15 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -91,6 +91,12 @@ Feel free to improve this package and send a pull request to GitHub_. changes +.. toctree:: + :caption: Contributing + + contributing/guidelines + + Indices and tables ==================