From 6408eea6be82b7d0623d28eda4bd98309288536a Mon Sep 17 00:00:00 2001
From: zacharyburnett <zburnett@stsci.edu>
Date: Mon, 19 Aug 2024 10:30:42 -0400
Subject: [PATCH] update documentation to reference `towncrier` news fragments

---
 .github/pull_request_template.md |  4 ++--
 .github/workflows/changelog.yml  | 27 ++++++++++++++-------------
 CONTRIBUTING.rst                 | 10 ++++++++++
 3 files changed, 26 insertions(+), 15 deletions(-)

diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md
index 56a248f3e..32be9e07f 100644
--- a/.github/pull_request_template.md
+++ b/.github/pull_request_template.md
@@ -29,6 +29,6 @@ If this PR fixes an issue, please add closing keywords (eg 'fixes #XXX')
 
 - [ ] pre-commit checks ran successfully
 - [ ] tests ran successfully
-- [ ] for a public change, a changelog entry was added
-- [ ] for a public change, documentation was updated
+- [ ] for a public change, added news fragment (`changes/<PR#>.<changetype>.rst`)
+- [ ] for a public change, updated documentation
 - [ ] for any new features, unit tests were added
diff --git a/.github/workflows/changelog.yml b/.github/workflows/changelog.yml
index 9e949e086..dc25b6f39 100644
--- a/.github/workflows/changelog.yml
+++ b/.github/workflows/changelog.yml
@@ -1,26 +1,27 @@
-name: 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:
-  changelog:
-    name: Confirm changelog entry
+  check:
+    if: ${{ !contains(github.event.pull_request.labels.*.name, 'no-changelog-entry-needed') }}
     runs-on: ubuntu-latest
     steps:
-      - name: Checkout code
-        uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+      - uses: actions/checkout@v4
         with:
           fetch-depth: 0
-      - name: Grep for PR number in CHANGES.rst
-        run: grep -P '\[[^\]]*#${{github.event.number}}[,\]]' CHANGES.rst
-        if: ${{ !contains(github.event.pull_request.labels.*.name, 'no-changelog-entry-needed') }}
+      - run: pip install towncrier
+      - run: towncrier build
+      - run: grep -P '\[[^\]]*#${{github.event.number}}[,\]]' CHANGES.rst
diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst
index 5a9c5022b..c623fc53d 100644
--- a/CONTRIBUTING.rst
+++ b/CONTRIBUTING.rst
@@ -53,3 +53,13 @@ to the maintainers, who are glad to assist you.
     a maintainer, you can comment ``@meeseeksdev backport to <branch>`` on a pull
     request to manually trigger a backport. Moreover, when merging a "backport"
     pull request, please use the "Rebase and merge" option.
+
+.. note::
+    When making a public change, add a news fragment to ``changes/`` with the
+    filename ``<PR#>.<changetype>.rst``. The change types are as follows:
+
+    - ``feature``: new feature
+    - ``bugfix``: bug fix
+    - ``doc``: documentation change
+    - ``removal``: deprecation or removal of public API
+    - ``misc``: not of interest to users