use towncrier to handle changelog entries (#284)

* use `towncrier` to handle changelog entries

* add change log entry

* add changelog to docs

* looser grep

* make example more explicit

.github/pull_request_template.md

@@ -14,7 +14,11 @@ This PR addresses ...
 
 **Checklist**
 
-- [ ] added entry in `CHANGES.rst` (either in `Bug Fixes` or `Changes to API`)
+- [ ] for a public change, added a towncrier news fragment in `changes/`: <details><summary>`echo "changed something" > changes/<PR#>.<changetype>.rst`</summary>
+
+    - ``changes/<PR#>.apichange.rst``: change to public API
+    - ``changes/<PR#>.bugfix.rst``: fixes an issue
+    - ``changes/<PR#>.general.rst``: infrastructure or miscellaneous change
 - [ ] updated relevant tests
 - [ ] updated relevant documentation
 - [ ] updated relevant milestone(s)

.github/workflows/changelog.yml

@@ -1,24 +1,30 @@
-name: Ensure changelog
+name: changelog
 
 on:
   pull_request:
-    types: [labeled, unlabeled, opened, synchronize, reopened]
+    types:
+      - labeled
+      - unlabeled
+      - opened
+      - synchronize
+      - reopened
 
-# Only cancel in-progress jobs or runs for the current workflow
-#   This cancels the already triggered workflows for a specific PR without canceling
-#   other instances of this workflow (other PRs, scheduled triggers, etc) when something
-#   within that PR re-triggers this CI
 concurrency:
   group: ${{ github.workflow }}-${{ github.ref }}
   cancel-in-progress: true
 
 jobs:
-  ensure_changelog:
-    name: Verify that a changelog entry exists for this pull request
+  check:
+    if: ${{ !contains(github.event.pull_request.labels.*.name, 'no-changelog-entry-needed') }}
     runs-on: ubuntu-latest
     steps:
-    - uses: scientific-python/action-check-changelogfile@0.2
-      env:
-        CHANGELOG_FILENAME: CHANGES.rst
-        CHECK_MILESTONE: false
-        GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+      - uses: actions/setup-python@v5
+        with:
+          python-version: 3
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - run: pip install .
+      - run: pip install towncrier
+      - run: towncrier check
+      - run: towncrier build --draft | grep -P '#${{ github.event.number }}'

.readthedocs.yaml

@@ -20,6 +20,9 @@ build:
   os: ubuntu-22.04
   tools:
     python: mambaforge-4.10
+  jobs:
+    post_install:
+      - towncrier build --keep
 
 conda:
   environment: docs/rtd_environment.yaml

CHANGES.rst

@@ -1,26 +1,3 @@
-1.8.1 (unreleased)
-==================
-
-General
--------
-
-- 
-
-Changes to API
---------------
-
-- 
-
-Bug Fixes
----------
-
-- 
-
-ramp_fitting
-~~~~~~~~~~~~
-
-- Fixed memory leak in C-extension.[#281]
-
 1.8.0 (2024-08-14)
 ==================
 

changes/.gitkeep

@@ -0,0 +1 @@
+

changes/281.bugfix.rst

@@ -0,0 +1 @@
+Fixed memory leak in C-extension.

changes/284.general.rst

@@ -0,0 +1 @@
+use ``towncrier`` to handle changelog entries

docs/index.rst

@@ -29,3 +29,4 @@ Package Documentation
    :maxdepth: 1
 
    stcal/package_index.rst
+   stcal/changes.rst

docs/rtd_environment.yaml

@@ -7,3 +7,4 @@ dependencies:
   - pip
   - graphviz
   - sphinx_rtd_theme>1.2.0
+  - towncrier

docs/stcal/changes.rst

@@ -0,0 +1,7 @@
+.. currentmodule:: stcal
+
+***********
+Change  Log
+***********
+
+.. include:: ../../CHANGES.rst

pyproject.toml

@@ -248,3 +248,21 @@ archs = [
     "auto",
     "aarch64",
 ]
+
+[tool.towncrier]
+filename = "CHANGES.rst"
+directory = "changes"
+package = "stcal"
+title_format = "{version} ({project_date})"
+ignore = [".gitkeep"]
+wrap = true
+issue_format = "`#{issue} <https://github.com/spacetelescope/stcal/{issue}>`_"
+
+[tool.towncrier.fragment.apichange]
+name = "Changes to API"
+
+[tool.towncrier.fragment.bugfix]
+name = "Bug Fixes"
+
+[tool.towncrier.fragment.general]
+name = "General"