Use towncrier for changelog generation (#2736)

* Use towncrier for changelog generation

* Generate unreleased changelog

* Fix towncrier command

* Fix issue links

* Don't do unreleased changelog on tagged builds

* Rename 1234.doc.rst to 2736.doc.rst

* Change existing release notes entry to new format

* Update contributing guide for new release notes system

* Update pull request template for new changelog system

Author: dstansby

.github/PULL_REQUEST_TEMPLATE.md

@@ -4,6 +4,6 @@ TODO:
 * [ ] Add unit tests and/or doctests in docstrings
 * [ ] Add docstrings and API docs for any new/modified user-facing classes and functions
 * [ ] New/modified features documented in `docs/user-guide/*.rst`
-* [ ] Changes documented in `docs/release-notes.rst`
+* [ ] Changes documented as a new file in `changes/`
 * [ ] GitHub Actions have all passed
 * [ ] Test coverage is 100% (Codecov passes)

.github/labeler.yml

@@ -1,2 +1,4 @@
-needs release notes:
-- all: ['!docs/release-notes.rst']
+- needs release notes:
+  - all:
+    - changed-files:
+      - any-glob-to-any-file: 'changes/*.rst'

.github/workflows/needs_release_notes.yml

@@ -4,8 +4,11 @@ on:
   - pull_request_target
 
 jobs:
-  triage:
+  labeler:
     if: ${{ github.event.pull_request.user.login != 'dependabot[bot]' }} && ${{ github.event.pull_request.user.login != 'pre-commit-ci[bot]' }}
+    permissions:
+      contents: read
+      pull-requests: write
     runs-on: ubuntu-latest
     steps:
     - uses: actions/labeler@8558fd74291d67161a8a78ce36a881fa63b766a9  # v5.0.0

.pre-commit-config.yaml

@@ -49,3 +49,7 @@ repos:
     rev: v1.8.0
     hooks:
       - id: numpydoc-validation
+  - repo: https://github.com/twisted/towncrier
+    rev: 23.11.0
+    hooks:
+      - id: towncrier-check

.readthedocs.yaml

@@ -4,6 +4,13 @@ build:
   os: ubuntu-22.04
   tools:
     python: "3.12"
+  jobs:
+    pre_build:
+      - |
+        if [ "$READTHEDOCS_VERSION_TYPE" != "tag" ];
+        then
+          towncrier build --version Unreleased --yes;
+        fi
 
 sphinx:
   configuration: docs/conf.py

changes/.gitignore

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

changes/2681.bugfix.rst

@@ -0,0 +1 @@
+Added backwards compatibility for Zarr format 2 structured arrays.

changes/2736.doc.rst

@@ -0,0 +1,2 @@
+Changed the machinery for creating changelog entries.
+Now individual entries should be added as files to the `changes` directory in the `zarr-python` repository, instead of directly to the changelog file.

changes/README.md

@@ -0,0 +1,14 @@
+Writing a changelog entry
+-------------------------
+
+Please put a new file in this directory named `xxxx.<type>.rst`, where
+
+- `xxxx` is the pull request number associated with this entry
+- `<type>` is one of:
+  - feature
+  - bugfix
+  - doc
+  - removal
+  - misc
+
+Inside the file, please write a short description of what you have changed, and how it impacts users of `zarr-python`.

docs/developers/contributing.rst

@@ -216,8 +216,8 @@ The documentation consists both of prose and API documentation. All user-facing
 and functions are included in the API documentation, under the ``docs/api`` folder
 using the `autodoc <https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html>`_
 extension to sphinx. Any new features or important usage information should be included in the
-user-guide (``docs/user-guide``). Any changes should also be included in the release
-notes (``docs/release-notes.rst``).
+user-guide (``docs/user-guide``). Any changes should also be included as a new file in the
+:file:`changes` directory.
 
 The documentation can be built locally by running::
 
@@ -335,11 +335,9 @@ Release procedure
 
 Pre-release
 """""""""""
-1. Make sure that all pull requests which will be
-   included in the release have been properly documented in
-   :file:`docs/release-notes.rst`.
-2. Rename the "Unreleased" section heading in :file:`docs/release-notes.rst`
-   to the version you are about to release.
+1. Make sure that all pull requests which will be included in the release
+   have been properly documented as changelog files in :file:`changes`.
+2. Run ``towncrier build --version x.y.z`` to create the changelog.
 
 Releasing
 """""""""
@@ -352,7 +350,7 @@ appropriate suffix (e.g. `v0.0.0a1` or `v0.0.0rc2`).
 
 Set the description of the release to::
 
-    See release notes https://zarr.readthedocs.io/en/stable/release.html#release-0-0-0
+    See release notes https://zarr.readthedocs.io/en/stable/release-notes.html#release-0-0-0
 
 replacing the correct version numbers. For pre-release versions,
 the URL should omit the pre-release suffix, e.g. "a1" or "rc1".

docs/release-notes.rst

@@ -1,22 +1,8 @@
 Release notes
 =============
 
-Unreleased
-----------
+.. towncrier release notes start
 
-Bug fixes
-~~~~~~~~~
-
-* Backwards compatibility for Zarr format 2 structured arrays (:issue:`2134`)
-
-Features
-~~~~~~~~
-
-Documentation
-~~~~~~~~~~~~~
-
-Other
-~~~~~
 
 3.0.1 (Jan. 17, 2025)
 ---------------------

pyproject.toml

@@ -85,6 +85,7 @@ test = [
 ]
 optional = ["rich", "universal-pathlib"]
 docs = [
+    # Doc building
     'sphinx==8.1.3',
     'sphinx-autobuild>=2021.3.14',
     'sphinx-autoapi==3.4.0',
@@ -94,6 +95,9 @@ docs = [
     'sphinx-reredirects',
     'pydata-sphinx-theme',
     'numpydoc',
+    # Changelog generation
+    'towncrier',
+    # Optional dependencies to run examples
     'numcodecs[msgpack]',
     'rich',
     's3fs',
@@ -415,3 +419,9 @@ checks = [
     "PR05",
     "PR06",
 ]
+
+[tool.towncrier]
+directory = 'changes'
+filename = "docs/release-notes.rst"
+underlines = ["-", "~", "^"]
+issue_format = ":issue:`{issue}`"