Adopt towncrier for the changelog (#718)

* Add towncrier and changes since 3.2.0

* Generate example changelog

* Remove releases tooling

* Reformat existing changelog

* Fix long lines

* Add new changelog to existing changelog

* Generate example changelog entry

* Group entries by type

* Document SemVer

* Add changelog entry

* Remove releases from docs requirements

* Remove example changelog entry

* Add changelog instructions

* Move changelog instructions to contributing.rst

* Update release instructions

Author: bhrutledge

changelog/.gitignore

@@ -0,0 +1 @@
+!.gitignore

changelog/670.feature.rst

@@ -0,0 +1 @@
+Print files to be uploaded using ``upload --verbose``

changelog/675.feature.rst

@@ -0,0 +1 @@
+Print configuration file location when using ``upload --verbose``

changelog/678.bugfix.rst

@@ -0,0 +1 @@
+Make password optional when using ``upload --client-cert``

changelog/680.doc.rst

@@ -0,0 +1 @@
+Adopt PSF code of conduct

changelog/685.feature.rst

@@ -0,0 +1 @@
+Print source and values of credentials when using ``upload --verbose``

changelog/693.bugfix.rst

@@ -0,0 +1 @@
+Support more Nexus versions with ``upload --skip-existing``

changelog/698.bugfix.rst

@@ -0,0 +1 @@
+Support Gitlab Enterprise with ``upload --skip-existing``

changelog/708.feature.rst

@@ -0,0 +1 @@
+Add support for Python 3.9

changelog/714.bugfix.rst

@@ -0,0 +1 @@
+Show a better error message for malformed files

changelog/715.feature.rst

@@ -0,0 +1 @@
+Turn warnings into errors when using ``check --strict``

changelog/718.doc.rst

@@ -0,0 +1 @@
+Adopt towncrier for the changleog

docs/changelog.rst

@@ -24,7 +24,7 @@
 # -- General configuration ----------------------------------------------------
 
 # If your documentation needs a minimal Sphinx version, state it here.
-needs_sphinx = '1.7.0'
+needs_sphinx = "1.7.0"
 
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
@@ -34,15 +34,8 @@
     "sphinx.ext.intersphinx",
     "sphinx.ext.coverage",
     "sphinx.ext.viewcode",
-    "releases",
 ]
 
-# 'releases' (changelog) settings
-releases_issue_uri = "https://github.com/pypa/twine/issues/%s"
-releases_release_uri = "https://github.com/pypa/twine/tree/%s"
-
-releases_debug = False  # Change to True to see debug output
-
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ["_templates"]
 
@@ -188,10 +181,8 @@
 latex_elements = {
     # The paper size ('letterpaper' or 'a4paper').
     # 'papersize': 'letterpaper',
-
     # The font size ('10pt', '11pt' or '12pt').
     # 'pointsize': '10pt',
-
     # Additional stuff for the LaTeX preamble.
     # 'preamble': '',
 }

docs/conf.py

@@ -130,15 +130,51 @@ and build the documentation, run:
 
 
 Submitting changes
-^^^^^^^^^^^^^^^^^^
+------------------
 
 1. Fork `the GitHub repository`_.
 2. Make a branch off of ``master`` and commit your changes to it.
 3. Run the tests, check code style, and build the docs as described above.
-4. Ensure that your name is added to the end of the :file:`AUTHORS`
+4. Optionally, add your name to the end of the :file:`AUTHORS`
    file using the format ``Name <[email protected]> (url)``, where the
    ``(url)`` portion is optional.
-5. Submit a pull request to the ``master`` branch on GitHub.
+5. Submit a pull request to the ``master`` branch on GitHub, referencing an
+   open issue.
+6. Add a changelog entry.
+
+Changelog entries
+^^^^^^^^^^^^^^^^^
+
+The ``docs/changelog.rst`` file is built by `towncrier`_ from files in the
+``changelog/`` directory. To add an entry, create a file in that directory
+named ``{number}.{type}.rst``, where ``{number}`` is the pull request number,
+and ``{type}`` is ``feature``, ``bugfix``, ``doc``, ``removal``, or ``misc``.
+
+For example, if your PR number is 1234 and it's fixing a bug, then you
+would create ``changelog/1234.bugfix.rst``. PRs can span multiple categories by
+creating multiple files: if you added a feature and deprecated/removed an old
+feature in PR #5678, you would create ``changelog/5678.feature.rst`` and
+``changelog/5678.removal.rst``.
+
+A changelog entry is meant for end users and should only contain details
+relevant to them. In order to maintain a consistent style, please keep the
+entry to the point, in sentence case, shorter than 80 characters, and in an
+imperative tone. An entry should complete the sentence "This change will ...".
+If one line is not enough, use a summary line in an imperative tone, followed
+by a description of the change in one or more paragraphs, each wrapped at 80
+characters and separated by blank lines.
+
+You don't need to reference the pull request or issue number in a changelog
+entry, since towncrier will add a link using the number in the file name,
+and the pull request should reference an issue number. Similarly, you don't
+need to add your name to the entry, since that will be associated with the pull
+request.
+
+Changelog entries are rendered using `reStructuredText`_, but they should only
+have minimal formatting (such as ````monospaced text````).
+
+.. _`towncrier`: https://pypi.org/project/towncrier/
+.. _`reStructuredText`: https://www.writethedocs.org/guide/writing/reStructuredText/
 
 
 Architectural overview
@@ -196,9 +232,9 @@ Making a new release
 
 A checklist for creating, testing, and distributing a new version.
 
-#. Add user-facing changes to :file:`docs/changelog.rst`.
-#. Choose a version number, e.g. ``3.2.0``.
-#. Add a ``:release:`` line to :file:`docs/changelog.rst`.
+#. Choose a version number, e.g. ``3.3.0``.
+#. Run ``tox -e changelog -- --version {version}`` to build
+   :file:`docs/changelog.rst`.
 #. Commit and open a pull request for review.
 #. Merge the pull request, and ensure the `GitHub Actions`_ build passes.
 #. Create a new git tag with ``git tag -m "Release v{version}" {version}``.
@@ -228,6 +264,5 @@ merge into a single tool; see `ongoing discussion
 .. _`black`: https://black.readthedocs.io/
 .. _`flake8`: https://flake8.pycqa.org/
 .. _`mypy`: https://mypy.readthedocs.io/
-.. _`plugin`: https://github.com/bitprophet/releases
 .. _`projects`: https://packaging.python.org/glossary/#term-Project
 .. _`open issues`: https://github.com/pypa/twine/issues

docs/contributing.rst

@@ -1,5 +1,4 @@
 doc8>=0.8.0
 readme-renderer>=17.4
-releases>=1.4.0
 Sphinx>=1.7.0
 sphinx_rtd_theme>=0.2.4

docs/requirements.txt

@@ -1,3 +1,11 @@
 [build-system]
 requires = ["setuptools>=40.8", "wheel", "setuptools_scm>=1.15"]
 build-backend = "setuptools.build_meta:__legacy__"
+
+[tool.towncrier]
+package = "twine"
+filename = "docs/changelog.rst"
+directory = "changelog"
+title_format = "{version} ({project_date})"
+issue_format = "`#{issue} <https://github.com/pypa/twine/issues/{issue}>`_"
+underlines = ["-", "^"]

pyproject.toml

@@ -77,6 +77,14 @@ commands =
     mypy --html-report mypy --txt-report mypy {posargs:twine}
     python -c 'with open("mypy/index.txt") as f: print(f.read())'
 
+[testenv:changelog]
+basepython = python3
+skip_install = true
+deps =
+    towncrier
+commands =
+    towncrier {posargs}
+
 [testenv:release]
 # disabled for twine to cause it to upload itself
 # skip_install = True