Use towncrier for changelog generation

.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/1234.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

@@ -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
 """""""""

docs/release-notes.rst

@@ -1,20 +1,7 @@
 Release notes
 =============
 
-Unreleased
-----------
-
-Bug fixes
-~~~~~~~~~
-
-Features
-~~~~~~~~
-
-Documentation
-~~~~~~~~~~~~~
-
-Other
-~~~~~
+.. towncrier release notes start
 
 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}`"