Merge pull request #56 from richardkoehler/chore/release-tooling-towncrier-docs

Release tooling: Towncrier + prepare-release workflow + docs

Author: richardkoehler

.github/workflows/prepare-release.yml

@@ -0,0 +1,90 @@
+name: CD - Prepare release PR
+
+# Runs the same logic as ``scripts/release_prepare.py`` locally: bump versions,
+# assemble ``CHANGELOG.md`` with Towncrier, commit, push a branch, open a PR.
+# Tagging ``v*`` remains a deliberate maintainer step after merge (see docs/releasing.rst).
+
+on:
+  workflow_dispatch:
+    inputs:
+      version:
+        description: "Version (X.Y.Z, no v prefix)"
+        required: true
+        type: string
+      release_date:
+        description: "Towncrier release date (YYYY-MM-DD); leave empty for today (UTC)"
+        required: false
+        type: string
+
+permissions:
+  contents: write
+  pull-requests: write
+
+jobs:
+  open-pr:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+        with:
+          ref: main
+          fetch-depth: 0
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b
+        with:
+          python-version: "3.12"
+          enable-cache: true
+
+      - name: Sync dev dependencies
+        run: uv sync --locked --dev
+
+      - name: Compute branch name and release date
+        id: meta
+        shell: bash
+        run: |
+          VERSION="${{ github.event.inputs.version }}"
+          echo "branch=chore/release-prep-${VERSION}" >> "$GITHUB_OUTPUT"
+          D="${{ github.event.inputs.release_date }}"
+          if [ -z "$D" ]; then
+            D=$(date -u +"%Y-%m-%d")
+          fi
+          echo "date=${D}" >> "$GITHUB_OUTPUT"
+
+      - name: Configure git author
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+
+      - name: Create release prep branch
+        run: git checkout -b "${{ steps.meta.outputs.branch }}"
+
+      - name: Run release_prepare.py
+        run: |
+          uv run python scripts/release_prepare.py "${{ github.event.inputs.version }}" \
+            --date "${{ steps.meta.outputs.date }}" \
+            --commit \
+            --any-branch
+
+      - name: Push branch
+        run: git push -u origin "${{ steps.meta.outputs.branch }}"
+
+      - name: Open pull request
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          VERSION: ${{ github.event.inputs.version }}
+          RDATE: ${{ steps.meta.outputs.date }}
+          BRANCH: ${{ steps.meta.outputs.branch }}
+        run: |
+          cat > "$RUNNER_TEMP/pr-body.md" <<EOF
+          Automated release preparation for **${VERSION}** (Towncrier date: *${RDATE}*).
+
+          **Review**
+          - \`src/dbs_annotator/__init__.py\` and \`[tool.briefcase].version\` in \`pyproject.toml\` match **${VERSION}**.
+          - \`CHANGELOG.md\` for this version; removed \`newsfragments/*.md\` files were consumed by Towncrier.
+
+          **After merge** tag the merge commit and push \`v${VERSION}\`; see \`docs/releasing.rst\`. Pushing \`v*\` triggers \`release.yml\`.
+          EOF
+          gh pr create --base main --head "$BRANCH" \
+            --title "chore(release): prepare v${VERSION}" \
+            --body-file "$RUNNER_TEMP/pr-body.md"

CONTRIBUTING.md

@@ -4,6 +4,8 @@ We welcome contributions to the Clinical DBS Annotator! This document provides g
 
 For detailed guidelines, please see the [Contributing Guide](docs/contributing.rst).
 
+**Releases (maintainers):** use the PR-based process and manual `v*` tag described in [docs/releasing.rst](docs/releasing.rst) (Sphinx: *Developer guide → Releasing*). The helper is `scripts/release_prepare.py`; GitHub Actions workflow **CD - Prepare release PR** runs the same steps.
+
 ## Quick Start
 
 1. Fork the repository

docs/conf.py

@@ -32,6 +32,9 @@
 ]
 
 templates_path = ["_templates"]
+# Do not list ``_autosummary`` here: those ``.rst`` stubs are generated under
+# ``docs/_autosummary/`` during the same build and must be parsed. (Ignore the
+# directory in git via ``.gitignore``, not in Sphinx ``exclude_patterns``.)
 exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
 
 # Known, non-actionable warnings that would otherwise fail `-W` builds.

docs/contributing.rst

@@ -18,7 +18,7 @@ Prerequisites
 To contribute to this project, you should have:
 
 - **Python 3.12 or newer** (matches ``requires-python`` in ``pyproject.toml``;
-  CI tests on 3.12, 3.13, and 3.14).
+  CI uses 3.12 on Ubuntu, Windows, and macOS).
 - **uv** (https://github.com/astral-sh/uv) for dependency management and
   running tools.
 - **Git** installed and configured.
@@ -167,6 +167,33 @@ Optional: regenerate UI screenshot artifacts for docs (uploaded as CI artifact):
    QT_QPA_PLATFORM=offscreen DOCS_SCREENSHOT_DIR=docs/_build/screenshots \
      uv run pytest tests/docs/test_docs_screenshots.py -m docs_screenshot
 
+Sphinx-related paths under ``docs/``:
+
+- **``docs/_static/``** — **Keep in version control.** These are source assets (images,
+  optional extra CSS/JS). Sphinx only *copies* them into ``docs/_build/html/_static/``
+  when you build; the underscore is a Sphinx convention for “static inputs”, not
+  garbage output.
+
+- **``docs/_templates/``** (including ``_templates/autosummary/`` if present) —
+  **Keep in version control** when the ``.html``/``.rst`` files there are **hand-written**
+  Jinja templates that customize the HTML builder or autosummary. They are part of
+  your documentation *source*, not generated API stubs.
+
+- **``docs/_autosummary/``** at the **project root** (next to your ``.rst`` sources) —
+  **Do not commit.** Those files are **generated stubs** produced by
+  ``sphinx.ext.autosummary``; they belong in ``.gitignore`` and are recreated by
+  ``sphinx-build`` (or your docs CI job).
+
+- **``docs/_generated/``** — **Depends on your workflow.** If that directory holds
+  output from a **script** (for example includes generated from Python constants),
+  you can either (a) **commit** the files so a plain ``sphinx-build`` works everywhere,
+  with CI checking they are up to date, or (b) **gitignore** them and always run the
+  generator before Sphinx in CI and locally. Do **not** delete the folder if you still
+  ``.. include::`` it from an ``.rst`` file unless you switch fully to (b) and teach
+  CI to regenerate it.
+
+**Never commit** the HTML tree ``docs/_build/`` (already ignored).
+
 Code Standards
 ---------------
 
@@ -324,8 +351,9 @@ Our review process:
    - ``uv audit`` for dependency vulnerabilities.
    - ``ruff`` (lint + format) and ``ty`` (type check).
    - ``pytest`` on Ubuntu, Windows, and macOS with a coverage floor.
-   - Briefcase ZIP packaging smoke test on Windows.
-   - Documentation build (Sphinx ``-W``) and link check.
+   - Prose checks (codespell, doc8, interrogate) via pre-commit.
+   - Briefcase smoke test on Linux (``create`` + ``build`` without packaging).
+   - Documentation build (Sphinx ``-W``), TSV schema doc drift check, and link check.
 
 2. **Peer review** by maintainers.
 3. **Discussion** of any required changes.
@@ -387,22 +415,29 @@ We use a simple trunk-based strategy:
 Release Process
 ~~~~~~~~~~~~~~~
 
-1. Update ``dbs_annotator.__version__`` in
-   ``src/dbs_annotator/__init__.py`` (Hatch reads this as the distribution
-   version) and, if it changed, ``[tool.briefcase].version`` in
+Maintainers follow a **PR-based** flow: bump versions and assemble the changelog on a
+branch, merge to ``main``, then **tag** ``vX.Y.Z`` and push the tag to publish builds.
+
+Concrete steps:
+
+1. Update ``dbs_annotator.__version__`` in ``src/dbs_annotator/__init__.py`` (Hatch
+   reads this as the distribution version) and ``[tool.briefcase].version`` in
    ``pyproject.toml``. These two values must match.
-2. Build ``CHANGELOG.md`` from Towncrier fragments:
+2. Build ``CHANGELOG.md`` from Towncrier fragments (or use ``scripts/release_prepare.py`` /
+   the **CD - Prepare release PR** workflow), for example:
 
    .. code-block:: bash
 
       uv run towncrier build --yes --version X.Y.Z --date YYYY-MM-DD
-3. Open a release PR, land it on ``main``, then push the matching
-   ``vX.Y.Z`` tag.
-4. The ``CD - Create GitHub Release`` workflow builds Python wheels/sdist and
-   Briefcase installers (Windows MSI, macOS DMG, Linux system package), then
-   creates the GitHub Release with artifacts attached.
+
+3. Open a release PR, land it on ``main``, then push the matching ``vX.Y.Z`` tag.
+4. The **CD - Create GitHub Release** workflow builds Python wheels/sdist and Briefcase
+   installers (Windows MSI, macOS DMG, Linux system package), then creates the GitHub
+   Release with artifacts attached.
 5. Read the Docs publishes the matching versioned documentation from the tag.
 
+See :doc:`releasing` for more detail (local script, workflow inputs, and tagging).
+
 Continuous Integration
 ~~~~~~~~~~~~~~~~~~~~~~
 

docs/index.rst

@@ -51,6 +51,7 @@ Developed at the **Brain Modulation Lab, Massachusetts General Hospital**.
    :caption: Developer Guide
 
    contributing
+   releasing
    api
 
 ----

docs/releasing.rst

@@ -0,0 +1,116 @@
+Releasing
+=========
+
+This project uses a **pull request** to prepare each release, then a **manual Git tag**
+as the only step that starts publication (GitHub Actions builds installers and
+creates a GitHub Release when a ``v*`` tag is pushed).
+
+Version sources
+---------------
+
+Keep these in sync whenever you cut a release:
+
+- ``__version__`` in ``src/dbs_annotator/__init__.py`` — Hatch reads this as the
+  ``dbs-annotator`` distribution version.
+- ``version`` under ``[tool.briefcase]`` in ``pyproject.toml`` (Briefcase requires a static string)
+
+The automation below updates both, then runs `Towncrier`_ to fold Markdown fragments
+under ``newsfragments/`` into ``CHANGELOG.md`` (see ``[tool.towncrier]`` in
+``pyproject.toml``).
+
+.. _Towncrier: https://towncrier.readthedocs.io/
+
+Day-to-day: changelog fragments
+-------------------------------
+
+For each PR that should appear in the release notes, add a fragment in ``newsfragments/``
+(usually in the same PR as the change). Types are ``added``, ``changed``, ``fixed``, and
+``docs`` — for example ``123.added.md`` or ``123.docs.md`` for PR number 123.
+
+Create a stub interactively:
+
+.. code-block:: bash
+
+   uv run towncrier create 123.added.md
+
+CI may require a fragment when certain paths change unless the PR is labeled
+``skip-changelog`` or ``internal-only`` (see ``CONTRIBUTING.md``).
+
+Option A — Prepare the release PR locally
+-----------------------------------------
+
+1. Ensure ``main`` is up to date and you have a **clean** working tree (or pass
+   ``--allow-dirty`` only if you intend to include other edits — not recommended).
+
+2. Create a branch (do **not** commit the release bump directly on ``main``):
+
+   .. code-block:: bash
+
+      git checkout main
+      git pull
+      git checkout -b chore/release-prep-X.Y.Z
+
+3. Run the helper (omit ``--commit`` first if you want to inspect diffs only):
+
+   .. code-block:: bash
+
+      uv sync --dev
+      uv run python scripts/release_prepare.py X.Y.Z --dry-run
+      uv run python scripts/release_prepare.py X.Y.Z --commit
+
+   Use ``--date YYYY-MM-DD`` if the Towncrier release date should not be “today”.
+   Use ``--skip-towncrier`` only in exceptional cases (changelog skipped).
+
+4. Push the branch and open a pull request into ``main``. Wait for CI to pass, then
+   merge.
+
+Option B — Prepare the release PR from GitHub Actions
+-------------------------------------------------------
+
+1. In GitHub: **Actions** → **CD - Prepare release PR** → **Run workflow**.
+
+2. Enter **Version** (``X.Y.Z`` without a ``v`` prefix). Optionally set **Release date**
+   (``YYYY-MM-DD``); otherwise UTC “today” is used.
+
+3. The workflow creates branch ``chore/release-prep-X.Y.Z``, runs the same steps as
+   ``scripts/release_prepare.py``, pushes it, and opens a pull request.
+
+4. Review and merge the PR when CI is green.
+
+Publish: tag after merge (deliberate final step)
+------------------------------------------------
+
+After the release-prep PR is **merged** into ``main``:
+
+1. Update your local ``main`` and identify the **merge commit** (or use GitHub’s
+   suggested SHA for the PR merge).
+
+2. Create an **annotated** tag matching the version (``v`` prefix for the git tag
+   only):
+
+   .. code-block:: bash
+
+      git checkout main
+      git pull
+      git tag -a vX.Y.Z -m "Release vX.Y.Z" <merge_commit_sha>
+      git push origin vX.Y.Z
+
+3. That push triggers ``.github/workflows/release.yml`` (tag pattern ``v*``), which
+   builds Python wheels and Briefcase artifacts and, when appropriate, publishes a
+   GitHub Release.
+
+Do **not** push a ``v*`` tag until the release-prep PR is merged and you are satisfied
+with ``CHANGELOG.md`` and the version numbers on ``main``.
+
+Manual workflow dispatch on ``release.yml`` can still build artifacts without a new
+tag; see that workflow’s inputs if you need a one-off build.
+
+Troubleshooting
+---------------
+
+- **“Working tree is not clean”** — stash or commit unrelated work, or use a fresh clone.
+- **Towncrier fails** — ensure there is at least one valid fragment for the release, or
+  confirm ``CHANGELOG.md`` still contains the ``## [Unreleased]`` heading Towncrier
+  uses as ``start_string`` in ``pyproject.toml``.
+- **Branch already exists** — delete the remote branch ``chore/release-prep-X.Y.Z`` or
+  pick a new branch name before re-running the workflow.

newsfragments/55.docs.md

@@ -0,0 +1 @@
+Document PR-based releases (`scripts/release_prepare.py`, **CD - Prepare release PR** workflow), maintainer `docs/releasing.rst`, and Sphinx generated-dir guidance (`_autosummary`, `_generated`, `_static`, `_templates`).

pyproject.toml

@@ -33,10 +33,10 @@ dependencies = [
 
 [dependency-groups]
 dev = [
-    "pytest>=8.0.0",
-    "pytest-qt>=4.4.0",
-    "pytest-timeout>=2.3.0",
-    "pytest-cov>=4.1.0",
+    "pytest>=9.0.3",
+    "pytest-qt>=4.5.0",
+    "pytest-timeout>=2.4.0",
+    "pytest-cov>=7.1.0",
     "ruff>=0.1.0",
     "pre-commit>=3.6",
     "pre-commit-uv>=4.2.1",