use towncrier to handle change log entries and add instructions to …

…new pull requests (#187)

.github/pull_request_template.md

@@ -0,0 +1,29 @@
+<!-- If this PR closes a JIRA ticket, make sure the title starts with the JIRA issue number,
+for example JP-1234: <Fix a bug> -->
+Resolves [JP-nnnn](https://jira.stsci.edu/browse/JP-nnnn)
+Resolves [RCAL-nnnn](https://jira.stsci.edu/browse/RCAL-nnnn)
+
+<!-- If this PR closes a GitHub issue, reference it here by its number -->
+Closes #
+
+<!-- describe the changes comprising this PR here -->
+This PR addresses ...
+
+<!-- if you can't perform these tasks due to permissions, please ask a maintainer to do them -->
+## Tasks
+- [ ] update or add relevant tests
+- [ ] update relevant docstrings and / or `docs/` page
+- [ ] Does this PR change any API used downstream? (if not, label with `no-changelog-entry-needed`)
+  - [ ] write news fragment(s) in `changes/`: `echo "changed something" > changes/<PR#>.<changetype>.rst` (see below for change types)
+  - [ ] run regression tests with this branch installed (`"git+https://github.com/<fork>/stpipe@<branch>"`)
+    - [ ] [`jwst` regression test](https://github.com/spacetelescope/RegressionTests/actions/workflows/jwst.yml)
+    - [ ] [`romancal` regression test](https://github.com/spacetelescope/RegressionTests/actions/workflows/romancal.yml)
+
+<details><summary>news fragment change types...</summary>
+
+- ``changes/<PR#>.feature.rst``: new feature
+- ``changes/<PR#>.bugfix.rst``: fixes an issue
+- ``changes/<PR#>.doc.rst``: documentation change
+- ``changes/<PR#>.removal.rst``: deprecation or removal of public API
+- ``changes/<PR#>.misc.rst``: infrastructure or miscellaneous change
+</details>

.github/workflows/changelog.yml

@@ -1,19 +1,30 @@
-name: confirm changelog entry
+name: changelog
 
 on:
   pull_request:
-    types: [labeled, unlabeled, opened, synchronize, reopened]
+    types:
+      - labeled
+      - unlabeled
+      - opened
+      - synchronize
+      - reopened
 
 concurrency:
   group: ${{ github.workflow }}-${{ github.ref }}
   cancel-in-progress: true
 
 jobs:
   check:
+    if: ${{ !contains(github.event.pull_request.labels.*.name, 'no-changelog-entry-needed') }}
     runs-on: ubuntu-latest
     steps:
-      - uses: scientific-python/[email protected]
-        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

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

CHANGES.rst

@@ -1,8 +1,3 @@
-0.7.1 (unreleased)
-==================
-
--
-
 0.7.0 (2024-08-13)
 ==================
 

changes/187.doc.rst

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

docs/rtd_environment.yaml

@@ -6,3 +6,4 @@ dependencies:
   - python=3.11
   - pip
   - graphviz
+  - towncrier

docs/source/changes.rst

@@ -0,0 +1,5 @@
+***********
+Change  Log
+***********
+
+.. include:: ../../CHANGES.rst

docs/source/index.rst

@@ -6,6 +6,7 @@ Welcome to stpipe's documentation!
    :caption: Contents:
 
    model_library.rst
+   changes.rst
 
 API
 ===

pyproject.toml

@@ -142,3 +142,26 @@ force-exclude = "^/(\n  (\n      \\.eggs\n    | \\.git\n    | \\.pytest_cache\n
 
 [tool.codespell]
 skip = "*.pdf,*.fits,*.asdf,.tox,build,./tags,.git,docs/_build"
+
+[tool.towncrier]
+filename = "CHANGES.rst"
+directory = "changes"
+package = "stpipe"
+title_format = "{version} ({project_date})"
+ignore = [".gitkeep"]
+wrap = true
+issue_format = "`#{issue} <https://github.com/spacetelescope/stpipe/issues/{issue}>`_"
+
+[tool.towncrier.fragment.feature]
+name = "New Features"
+
+[tool.towncrier.fragment.bugfix]
+name = "Bug Fixes"
+
+[tool.towncrier.fragment.doc]
+name = "Documentation"
+
+[tool.towncrier.fragment.removal]
+name = "Deprecations and Removals"
+
+[tool.towncrier.fragment.misc]