Move the changelog to Towncrier fragments and build CHANGELOG.md at each deploy

.github/CONTRIBUTING.md

@@ -11,6 +11,7 @@ make check                 # Ruff check + Pyright over source directories
 make test                  # service unit tests in Docker
 make test-complete         # unit tests + local integration tests
 make push-pr-branch        # push current branch to origin with tracking
+make changelog-draft       # print the CHANGELOG.md section the next release adds
 ./scripts/generate-clients.sh
 ```
 
@@ -52,6 +53,11 @@ gh pr view <PR> --repo PolicyEngine/policyengine-sim-api --json isDraft,headRepo
 Before opening the PR, open or identify a GitHub issue for the work. The first
 line of the PR description must be `Fixes #ISSUE_NUMBER`.
 
+Every PR adds a changelog fragment, `changelog.d/<name>.<type>.md`, where
+`<type>` is breaking, added, changed, fixed or removed; don't edit
+`CHANGELOG.md` yourself. The release after each merge builds the fragments into
+`CHANGELOG.md`. See `docs/engineering/skills/github-prs.md#changelog-fragments`.
+
 The PR is valid only if it is a draft and the head repository is
 `PolicyEngine/policyengine-sim-api`. If you cannot push to that repository, ask
 for access instead of opening a fork PR.

.github/pull_request_template.md

@@ -5,6 +5,10 @@ Fixes #
 - [ ] This PR is a draft.
 - [ ] This PR is from a branch in `PolicyEngine/policyengine-sim-api`, not a personal fork.
 
+## Changelog
+
+- [ ] This PR adds a changelog fragment, `changelog.d/<name>.<type>.md`, whose type is breaking, added, changed, fixed or removed.
+
 ## Summary
 
 -

.github/scripts/build-changelog.sh

@@ -0,0 +1,38 @@
+#!/usr/bin/env bash
+
+# Build the next release: raise VERSION from the pending changelog fragments,
+# then let Towncrier write their section of CHANGELOG.md and remove them with
+# git rm. The versioning job in simulation-deploy.yml runs this after a merge
+# to main and commits the result with commit-release.sh; make changelog runs
+# it locally.
+#
+#   build-changelog.sh          build the release
+#   build-changelog.sh --draft  print the section the next release would add,
+#                               and change no file
+#
+# changelog_fragments.py refuses to bump unless changelog.d/ holds at least
+# one fragment and nothing else, so Towncrier never skips a file. Towncrier
+# runs from the locked environment in .github/towncrier (its uv.lock).
+#
+# Run from the repository root, with Python 3.11 or later as python3.
+
+set -euo pipefail
+
+script_directory="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+fragments="${script_directory}/changelog_fragments.py"
+
+case "${1:-}" in
+  "")
+    python3 "${fragments}" bump
+    read -r version < VERSION
+    uv run --frozen --project .github/towncrier towncrier build --yes --version "${version}"
+    ;;
+  --draft)
+    next_version="$(python3 "${fragments}" next-version)"
+    uv run --frozen --project .github/towncrier towncrier build --draft --version "${next_version}"
+    ;;
+  *)
+    echo "Usage: build-changelog.sh [--draft]" >&2
+    exit 2
+    ;;
+esac