Merge pull request #1354 from pganssle/towncrier

Add configuration for towncrier

4 files changed, 94 insertions, 0 deletions

diff --git a/changelog.d/1354.misc.rst b/changelog.d/1354.misc.rst
new file mode 100644
index 00000000..7f9b80c9
--- /dev/null
+++ b/changelog.d/1354.misc.rst
@@ -0,0 +1 @@
+Added ``towncrier`` for changelog managment.
diff --git a/docs/developer-guide.txt b/docs/developer-guide.txt
index 25aaeaab..ea1034ab 100644
--- a/docs/developer-guide.txt
+++ b/docs/developer-guide.txt
@@ -57,6 +57,38 @@ Setuptools makes extensive use of hyperlinks to tickets in the changelog so
 that system integrators and other users can get a quick summary, but then
 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://town-crier.readthedocs.io/en/latest/>`_
+for changelog managment, so when making a PR, please add a news fragment in the
+``changelog.d/`` folder. Changelog files are written in Restructured Text 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 of 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:: bash
+
+    $ cat changelog.d/1288.change.rst
+    Add support for maintainer in PKG-INFO
+
 -----------
 Source Code
 -----------
diff --git a/pyproject.toml b/pyproject.toml
new file mode 100644
index 00000000..cffd0e9a
--- /dev/null
+++ b/pyproject.toml
@@ -0,0 +1,34 @@
+[tool.towncrier]
+    package = "setuptools"
+    package_dir = "setuptools"
+    filename = "CHANGES.rst"
+    directory = "changelog.d"
+    title_format = "v{version}"
+    issue_format = "#{issue}"
+    template = "towncrier_template.rst"
+    underlines = ["-"]
+
+    [[tool.towncrier.type]]
+        directory = "deprecation"
+        name = "Deprecations"
+        showcontent = true
+
+    [[tool.towncrier.type]]
+        directory = "breaking"
+        name = "Breaking Changes"
+        showcontent = true
+
+    [[tool.towncrier.type]]
+        directory = "change"
+        name = "Changes"
+        showcontent = true
+
+    [[tool.towncrier.type]]
+        directory = "doc"
+        name = "Documentation changes"
+        showcontent = true
+
+    [[tool.towncrier.type]]
+        directory = "misc"
+        name = "Misc"
+        showcontent = true
diff --git a/towncrier_template.rst b/towncrier_template.rst
new file mode 100644
index 00000000..02b2882b
--- /dev/null
+++ b/towncrier_template.rst
@@ -0,0 +1,27 @@
+{% for section, _ in sections.items() %}
+{% set underline = underlines[0] %}{% if section %}{{section}}
+{{ underline * section|length }}
+{% endif %}
+{% if sections[section] %}
+{% for category, val in definitions.items() if category in sections[section]%}
+{% if definitions[category]['showcontent'] %}
+{% for text, values in sections[section][category].items() %}
+* {{ values|join(', ') }}: {{ text }}
+{% endfor %}
+
+{% else %}
+*  {{ sections[section][category]['']|join(', ') }}
+
+{% endif %}
+{% if sections[section][category]|length == 0 %}
+No significant changes.
+{% else %}
+{% endif %}
+{% endfor %}
+
+{% else %}
+No significant changes.
+
+
+{% endif %}
+{% endfor %}