📝 Add an illustrative explanation of change notes

This change places a `README.rst` document under `changelog.d/` dir in
order for GitHub to render it when users navigate to this location via
the web UI.

It also includes that into the dev guide in Sphinx docs.

changelog.d/2395.doc.2.rst

+Added an illustrative explanation about the change notes to fragments dir -- by :user:`webknjaz`

changelog.d/README.rst

+.. _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?
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+``setuptools`` uses `towncrier <https://pypi.org/project/towncrier/>`_
+for changelog management.
+To submit a change note about your PR, add a text file into the
+``changelog.d/`` 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 ``change``,
+``doc``, ``misc`` 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:
+
+- ``change``: Any backwards compatible code change
+- ``breaking``: Any backwards-compatibility breaking change
+- ``doc``: A change to the documentation
+- ``misc``: Changes internal to the repo like CI, test and build changes
+- ``deprecation``: For deprecations of an existing feature or behavior
+
+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:`changelog.d/2395.doc.1.rst`:
+
+.. code-block:: rst
+
+    Added a ``:user:`` role to Sphinx config -- by :user:`webknjaz`
+
+File :file:`changelog.d/1354.misc.rst`:
+
+.. code-block:: rst
+
+    Added ``towncrier`` for changelog managment -- by :user:`pganssle`
+
+File :file:`changelog.d/2355.change.rst`:
+
+.. code-block:: rst
+
+    When pip is imported as part of a build, leave :py:mod:`distutils`
+    patched -- by :user:`jaraco`
+
+.. tip::
+
+   See :file:`pyproject.toml` for all available categories
+   (``tool.towncrier.type``).
+
+.. _Towncrier philosophy:
+   https://towncrier.readthedocs.io/en/actual-freaking-docs/#philosophy

docs/developer-guide.rst

@@ -61,33 +61,14 @@ jump to the in-depth discussion about any subject referenced.
 Making a pull request
 ---------------------
 
-When making a pull request, please include a short summary of the changes
-and a reference to any issue tickets that the PR is intended to solve.
-All PRs with code changes should include tests. All changes should include a
-changelog entry.
-
-``setuptools`` uses `towncrier <https://pypi.org/project/towncrier/>`_
-for changelog management, so when making a PR, please add a news fragment in the
-``changelog.d/`` folder. Changelog files are written in reStructuredText and
-should be a 1 or 2 sentence description of the substantive changes in the PR.
-They should be named ``<pr_number>.<category>.rst``, where the categories are:
-
-- ``change``: Any backwards compatible code change
-- ``breaking``: Any backwards-compatibility breaking change
-- ``doc``: A change to the documentation
-- ``misc``: Changes internal to the repo like CI, test and build changes
-- ``deprecation``: For deprecations of an existing feature or behavior
-
-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. See the following for an example news fragment:
-
-.. code-block:: shell-session
-
-    $ cat changelog.d/1288.change.rst
-    Add support for maintainer in PKG-INFO
+When making a pull request, please 
+:ref:`include a short summary of the changes <Adding change notes
+with your PRs>` and a reference to any issue tickets that the PR is
+intended to solve.
+All PRs with code changes should include tests. All changes should
+include a changelog entry.
+
+.. include:: ../changelog.d/README.rst
 
 -------------------
 Auto-Merge Requests