Merge branch 'main' into feature/local-schemesfeature/local-schemes

11 files changed, 111 insertions, 0 deletions

diff --git a/changelog.d/.gitignore b/changelog.d/.gitignore
new file mode 100644
index 00000000..e69de29b
--- /dev/null
+++ b/changelog.d/.gitignore
diff --git a/changelog.d/2227.doc.1.rst b/changelog.d/2227.doc.1.rst
new file mode 100644
index 00000000..ba7acb7f
--- /dev/null
+++ b/changelog.d/2227.doc.1.rst
@@ -0,0 +1,2 @@
+Added new setuptools logo, including editable files and artwork documentation
+-- by :user:`abravalheri`
diff --git a/changelog.d/2227.doc.2.rst b/changelog.d/2227.doc.2.rst
new file mode 100644
index 00000000..ebae3155
--- /dev/null
+++ b/changelog.d/2227.doc.2.rst
@@ -0,0 +1,2 @@
+Added sphinx theme customisations to display the new logo in the sidebar and
+use its colours as "accent" in the documentation -- by :user:`abravalheri`
diff --git a/changelog.d/2698.change.rst b/changelog.d/2698.change.rst
new file mode 100644
index 00000000..138629a2
--- /dev/null
+++ b/changelog.d/2698.change.rst
@@ -0,0 +1 @@
+Exposed exception classes from ``distutils.errors`` via ``setuptools.errors``.
diff --git a/changelog.d/2698.doc.1.rst b/changelog.d/2698.doc.1.rst
new file mode 100644
index 00000000..1e4dde38
--- /dev/null
+++ b/changelog.d/2698.doc.1.rst
@@ -0,0 +1,2 @@
+Added mentions to ``setuptools.errors`` as a way of handling custom command
+errors.
diff --git a/changelog.d/2698.doc.2.rst b/changelog.d/2698.doc.2.rst
new file mode 100644
index 00000000..784dbf2e
--- /dev/null
+++ b/changelog.d/2698.doc.2.rst
@@ -0,0 +1,2 @@
+Added instructions to migrate from ``distutils.commands`` and
+``distutils.errors`` in the porting guide.
diff --git a/changelog.d/2856.deprecation.rst b/changelog.d/2856.deprecation.rst
new file mode 100644
index 00000000..fe4144b4
--- /dev/null
+++ b/changelog.d/2856.deprecation.rst
@@ -0,0 +1,2 @@
+Support for custom commands that inherit directly from ``distutils`` is
+**deprecated**. Users should extend classes provided by setuptools instead.
diff --git a/changelog.d/2866.change.rst b/changelog.d/2866.change.rst
new file mode 100644
index 00000000..c6929d86
--- /dev/null
+++ b/changelog.d/2866.change.rst
@@ -0,0 +1 @@
+Incorporate changes from pypa/distutils@f1b0a2b.
diff --git a/changelog.d/2870.breaking.rst b/changelog.d/2870.breaking.rst
new file mode 100644
index 00000000..1d17ede6
--- /dev/null
+++ b/changelog.d/2870.breaking.rst
@@ -0,0 +1 @@
+Started failing on invalid inline description with line breaks :class:`ValueError` -- by :user:`webknjaz`
diff --git a/changelog.d/2871.doc.rst b/changelog.d/2871.doc.rst
new file mode 100644
index 00000000..2a099d0d
--- /dev/null
+++ b/changelog.d/2871.doc.rst
@@ -0,0 +1,4 @@
+Added a note to the docs that it is possible to install
+``setup.py``-less projects in editable mode with :doc:`pip v21.1+
+<pip:index>`, only having ``setup.cfg`` and ``pyproject.toml`` in
+project root -- by :user:`webknjaz`
diff --git a/changelog.d/README.rst b/changelog.d/README.rst
new file mode 100644
index 00000000..49b4d563
--- /dev/null
+++ b/changelog.d/README.rst
@@ -0,0 +1,94 @@
+.. _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 management -- 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