From 2be9f360d74df28b15dc198f15191e54e3ac95e4 Mon Sep 17 00:00:00 2001 From: David Stansby Date: Wed, 22 Jan 2025 11:19:25 +0000 Subject: [PATCH] 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 --- .github/PULL_REQUEST_TEMPLATE.md | 2 +- .github/labeler.yml | 6 ++++-- .github/workflows/needs_release_notes.yml | 5 ++++- .pre-commit-config.yaml | 4 ++++ .readthedocs.yaml | 7 +++++++ changes/.gitignore | 1 + changes/2681.bugfix.rst | 1 + changes/2736.doc.rst | 2 ++ changes/README.md | 14 ++++++++++++++ docs/developers/contributing.rst | 14 ++++++-------- docs/release-notes.rst | 16 +--------------- pyproject.toml | 10 ++++++++++ 12 files changed, 55 insertions(+), 27 deletions(-) create mode 100644 changes/.gitignore create mode 100644 changes/2681.bugfix.rst create mode 100644 changes/2736.doc.rst create mode 100644 changes/README.md 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) 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/.readthedocs.yaml b/.readthedocs.yaml index 32a3f0e4e1..6253a7196f 100644 --- a/.readthedocs.yaml +++ b/.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 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/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/changes/2736.doc.rst b/changes/2736.doc.rst new file mode 100644 index 0000000000..0cfe264eb1 --- /dev/null +++ b/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. 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..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:: @@ -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". 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) --------------------- diff --git a/pyproject.toml b/pyproject.toml index 73f3b9faae..e7a1c5c2c4 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,9 @@ checks = [ "PR05", "PR06", ] + +[tool.towncrier] +directory = 'changes' +filename = "docs/release-notes.rst" +underlines = ["-", "~", "^"] +issue_format = ":issue:`{issue}`"