Keep an Unreleased section at the top of the changelog

.github/pull_request_template.md

@@ -14,5 +14,5 @@
 
 - [ ] `uv run --frozen ruff check .`, `uv run --frozen mypy` and `uv run --frozen pytest --cov` pass
 - [ ] Committed benchmark results regenerated if report contents changed
-- [ ] `CHANGELOG.md` updated if users will notice
+- [ ] A line under `## Unreleased` in `CHANGELOG.md` if users will notice
 - [ ] New third-party data has its license, attribution and exact version recorded

CHANGELOG.md

@@ -1,5 +1,7 @@
 # Changelog
 
+## Unreleased
+
 ## 0.7.0 — Expert review, quality checks, community and documentation site
 
 - Add `bioevidence review` (`check`, `agreement`, `adjudication-sheet`, `score`, `freeze`)

CONTRIBUTING.md

@@ -65,12 +65,14 @@ checked by the test suite. Copy `community/profiles/_template/` to get started.
 ## Pull requests
 
 - Keep each pull request to one purpose; link the issue it resolves.
-- Update `CHANGELOG.md` under a new heading if users will notice the change.
+- If users will notice the change, add a line under `## Unreleased` at the top of
+  `CHANGELOG.md`. Never edit a released version's section.
 - New third-party data needs its license, attribution and exact source version recorded,
   as in `examples/*/sources/README.md`.
 
 ## Releases
 
 Maintainers release by bumping the version in `pyproject.toml` and
-`src/bioevidence_validator/__init__.py`, adding a `CHANGELOG.md` section, and pushing a
+`src/bioevidence_validator/__init__.py`, renaming `## Unreleased` in `CHANGELOG.md` to
+`## X.Y.Z — title` with a fresh, empty `## Unreleased` above it, and pushing a
 `vX.Y.Z` tag. The release workflow tests, publishes to PyPI and creates the GitHub release.

tests/test_repository_files.py

@@ -19,3 +19,12 @@ def test_yaml_parses(path):
 def test_workflow_has_name_and_jobs(path):
     workflow = yaml.load(path.read_text(encoding="utf-8"), Loader=yaml.BaseLoader)
     assert workflow.get("name") and workflow.get("jobs")
+
+
+def test_changelog_keeps_an_unreleased_section_on_top():
+    # Contributors add entries under it; a release renames it and opens a fresh one, so pull
+    # requests never land their notes inside an already-published version.
+    headings = [line for line in (ROOT / "CHANGELOG.md").read_text(encoding="utf-8").splitlines()
+                if line.startswith("## ")]
+    assert headings[0] == "## Unreleased"
+    assert all(h.split()[1][0].isdigit() for h in headings[1:]), "only one Unreleased section"