📝 Add change note guidelines to docs

CHANGES/564.contrib.rst

@@ -0,0 +1,3 @@
+Detailed :doc:`Contributing Guidelines <contributing/guidelines>` on
+authoring the changelog fragments have been published in the
+documentation -- by :user:`webknjaz`.

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 <https://pypi.org/project/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 ``<pr_number>.<category>.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

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 <MyST 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

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
 ==================
 

docs/spelling_wordlist.txt

@@ -40,6 +40,7 @@ bugfix
 BytesIO
 cchardet
 cChardet
+changelog
 Changelog
 charset
 charsetdetect
@@ -220,6 +221,7 @@ refactor
 Refactor
 refactored
 refactoring
+reStructuredText
 regex
 regexps
 regexs