From da53d3e13793e77927dc8b21bbaa4a5371ffda37 Mon Sep 17 00:00:00 2001 From: David Stansby Date: Mon, 20 Jan 2025 15:44:47 +0000 Subject: [PATCH 1/9] Use towncrier for changelog generation --- .github/labeler.yml | 6 ++++-- .github/workflows/needs_release_notes.yml | 5 ++++- .pre-commit-config.yaml | 4 ++++ changes/.gitignore | 1 + changes/1234.doc.rst | 2 ++ changes/README.md | 14 ++++++++++++++ docs/developers/contributing.rst | 8 +++----- docs/release-notes.rst | 15 +-------------- pyproject.toml | 9 +++++++++ 9 files changed, 42 insertions(+), 22 deletions(-) create mode 100644 changes/.gitignore create mode 100644 changes/1234.doc.rst create mode 100644 changes/README.md diff --git a/.github/labeler.yml b/.github/labeler.yml index f186216099..4dd680ee5a 100644 --- a/.github/labeler.yml +++ b/.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' diff --git a/.github/workflows/needs_release_notes.yml b/.github/workflows/needs_release_notes.yml index f37c6349d4..7a6c5462b4 100644 --- a/.github/workflows/needs_release_notes.yml +++ b/.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 diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index 28d1673652..908b0d5c28 100644 --- a/.pre-commit-config.yaml +++ b/.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 diff --git a/changes/.gitignore b/changes/.gitignore new file mode 100644 index 0000000000..f935021a8f --- /dev/null +++ b/changes/.gitignore @@ -0,0 +1 @@ +!.gitignore diff --git a/changes/1234.doc.rst b/changes/1234.doc.rst new file mode 100644 index 0000000000..0cfe264eb1 --- /dev/null +++ b/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. diff --git a/changes/README.md b/changes/README.md new file mode 100644 index 0000000000..74ed9f94a9 --- /dev/null +++ b/changes/README.md @@ -0,0 +1,14 @@ +Writing a changelog entry +------------------------- + +Please put a new file in this directory named `xxxx..rst`, where + +- `xxxx` is the pull request number associated with this entry +- `` 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`. diff --git a/docs/developers/contributing.rst b/docs/developers/contributing.rst index 5582c6ae8f..1663022401 100644 --- a/docs/developers/contributing.rst +++ b/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 """"""""" diff --git a/docs/release-notes.rst b/docs/release-notes.rst index 3fdf8c847a..2e6961ddc2 100644 --- a/docs/release-notes.rst +++ b/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) --------------------- diff --git a/pyproject.toml b/pyproject.toml index 73f3b9faae..69b288e408 100644 --- a/pyproject.toml +++ b/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,8 @@ checks = [ "PR05", "PR06", ] + +[tool.towncrier] +directory = 'changes' +filename = "docs/release-notes.rst" +underlines = ["-", "~", "^"] From 0299af0632d224e5df39f9395877fd5b0c4f779a Mon Sep 17 00:00:00 2001 From: David Stansby Date: Mon, 20 Jan 2025 15:48:26 +0000 Subject: [PATCH 2/9] Generate unreleased changelog --- .readthedocs.yaml | 3 +++ 1 file changed, 3 insertions(+) diff --git a/.readthedocs.yaml b/.readthedocs.yaml index 32a3f0e4e1..7339d1726a 100644 --- a/.readthedocs.yaml +++ b/.readthedocs.yaml @@ -4,6 +4,9 @@ build: os: ubuntu-22.04 tools: python: "3.12" + jobs: + pre_build: + - towncrier --build --version Unreleased --yes sphinx: configuration: docs/conf.py From 9254be07692625d969ccae02b472f9bed7ac085e Mon Sep 17 00:00:00 2001 From: David Stansby Date: Mon, 20 Jan 2025 15:53:36 +0000 Subject: [PATCH 3/9] Fix towncrier command --- .readthedocs.yaml | 2 +- docs/developers/contributing.rst | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/.readthedocs.yaml b/.readthedocs.yaml index 7339d1726a..a3dfbaeeba 100644 --- a/.readthedocs.yaml +++ b/.readthedocs.yaml @@ -6,7 +6,7 @@ build: python: "3.12" jobs: pre_build: - - towncrier --build --version Unreleased --yes + - towncrier build --version Unreleased --yes sphinx: configuration: docs/conf.py diff --git a/docs/developers/contributing.rst b/docs/developers/contributing.rst index 1663022401..df240d8ae4 100644 --- a/docs/developers/contributing.rst +++ b/docs/developers/contributing.rst @@ -337,7 +337,7 @@ Pre-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. +2. Run ``towncrier build --version x.y.z`` to create the changelog. Releasing """"""""" From 9a37aa4c47ddaed7605591c55bb28cb199128934 Mon Sep 17 00:00:00 2001 From: David Stansby Date: Mon, 20 Jan 2025 15:58:05 +0000 Subject: [PATCH 4/9] Fix issue links --- pyproject.toml | 1 + 1 file changed, 1 insertion(+) diff --git a/pyproject.toml b/pyproject.toml index 69b288e408..e7a1c5c2c4 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -424,3 +424,4 @@ checks = [ directory = 'changes' filename = "docs/release-notes.rst" underlines = ["-", "~", "^"] +issue_format = ":issue:`{issue}`" From f936e52bfcc3b4ee2bf102815d3268fe4b9deb60 Mon Sep 17 00:00:00 2001 From: David Stansby Date: Mon, 20 Jan 2025 16:07:32 +0000 Subject: [PATCH 5/9] Don't do unreleased changelog on tagged builds --- .readthedocs.yaml | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/.readthedocs.yaml b/.readthedocs.yaml index a3dfbaeeba..6253a7196f 100644 --- a/.readthedocs.yaml +++ b/.readthedocs.yaml @@ -6,7 +6,11 @@ build: python: "3.12" jobs: pre_build: - - towncrier build --version Unreleased --yes + - | + if [ "$READTHEDOCS_VERSION_TYPE" != "tag" ]; + then + towncrier build --version Unreleased --yes; + fi sphinx: configuration: docs/conf.py From f3c5685931e076adf268dc5594544e7976a13eca Mon Sep 17 00:00:00 2001 From: David Stansby Date: Mon, 20 Jan 2025 16:42:21 +0000 Subject: [PATCH 6/9] Rename 1234.doc.rst to 2736.doc.rst --- changes/{1234.doc.rst => 2736.doc.rst} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename changes/{1234.doc.rst => 2736.doc.rst} (100%) diff --git a/changes/1234.doc.rst b/changes/2736.doc.rst similarity index 100% rename from changes/1234.doc.rst rename to changes/2736.doc.rst From 24708e11a7aac320479ad2a4341963a322488097 Mon Sep 17 00:00:00 2001 From: David Stansby Date: Wed, 22 Jan 2025 11:04:53 +0000 Subject: [PATCH 7/9] Change existing release notes entry to new format --- changes/2681.bugfix.rst | 1 + docs/release-notes.rst | 16 +--------------- 2 files changed, 2 insertions(+), 15 deletions(-) create mode 100644 changes/2681.bugfix.rst diff --git a/changes/2681.bugfix.rst b/changes/2681.bugfix.rst new file mode 100644 index 0000000000..fa69f73e06 --- /dev/null +++ b/changes/2681.bugfix.rst @@ -0,0 +1 @@ +Added backwards compatibility for Zarr format 2 structured arrays. diff --git a/docs/release-notes.rst b/docs/release-notes.rst index 2276889cf6..2943250c38 100644 --- a/docs/release-notes.rst +++ b/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) --------------------- From 827e46dbb3e469d9fbea6637eb3d3f565b7ea2cd Mon Sep 17 00:00:00 2001 From: David Stansby Date: Wed, 22 Jan 2025 11:07:09 +0000 Subject: [PATCH 8/9] Update contributing guide for new release notes system --- docs/developers/contributing.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/developers/contributing.rst b/docs/developers/contributing.rst index df240d8ae4..220e24eced 100644 --- a/docs/developers/contributing.rst +++ b/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 `_ 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:: @@ -350,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". From 8e4265e6eb025f482eabed7f422a03a1a97cc39f Mon Sep 17 00:00:00 2001 From: David Stansby Date: Wed, 22 Jan 2025 11:08:55 +0000 Subject: [PATCH 9/9] Update pull request template for new changelog system --- .github/PULL_REQUEST_TEMPLATE.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index 723c995cef..9b64c97d0a 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.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)