From 1d4bba064230e16a3abfd237db1f6553af3b178a Mon Sep 17 00:00:00 2001
From: jedarden <github@jedarden.com>
Date: Sun, 24 May 2026 21:00:14 -0400
Subject: [PATCH] docs(pr): improve PR templates for CHANGELOG discipline
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Update main PR template to emphasize CHANGELOG entries for every behavior change
- Add clear example of how to format CHANGELOG entries
- Create separate release_pr_template.md with comprehensive release checklist
- Move release checklist to bottom of main template with reference to separate template

The templates now institutionalize the plan §7 CHANGELOG pattern:
- Regular PRs: add entry under [Unreleased] with clear format guidance
- Release PRs: use dedicated template with full checklist matching plan §7

Closes: miroir-uyx.2
---
 .github/pull_request_template.md | 60 +++++++++++++----------
 .github/release_pr_template.md   | 81 ++++++++++++++++++++++++++++++++
 2 files changed, 116 insertions(+), 25 deletions(-)
 create mode 100644 .github/release_pr_template.md

diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md
index b5407e2..059f6fa 100644
--- a/.github/pull_request_template.md
+++ b/.github/pull_request_template.md
@@ -1,18 +1,46 @@
-## Summary
+## What changed
 
-<!-- Describe what this PR does and why. -->
+<!-- Brief description of the change. -->
+
+## Why
+
+<!-- Link to issue or explain the motivation. -->
 
 ## Type of change
 
-- [ ] Bug fix
-- [ ] New feature
-- [ ] Refactor
+- [ ] Bug fix (non-breaking change which fixes an issue)
+- [ ] New feature (non-breaking change which adds functionality)
+- [ ] Breaking change (fix or feature that would cause existing functionality to not work as expected)
+- [ ] Refactor (internal restructuring, no external behavior change)
 - [ ] Documentation
 - [ ] Release
 
-## Release checklist
+## CHANGELOG entry
 
-If this is a release PR, verify each item before merging:
+<!-- IMPORTANT: Every PR that changes behavior MUST add an entry under [Unreleased] in CHANGELOG.md -->
+
+<!-- Add your entry under the appropriate subheading (Added/Changed/Deprecated/Removed/Fixed/Security) -->
+
+<!-- Example entry for a bug fix:
+```markdown
+### Fixed
+- Search now returns correct results when query contains special characters (#123)
+```
+-->
+
+## Breaking changes
+
+<!-- Note any breaking changes and migration steps. Else write "N/A" -->
+
+## Test plan
+
+<!-- How was this tested? -->
+
+---
+
+## Release checklist (only for release PRs)
+
+If this is a release PR, use `.github/release_pr_template.md` instead and verify:
 
 - [ ] All tests pass on `main` (`cargo test --workspace`)
 - [ ] `CHANGELOG.md` updated with new version section (`## [x.y.z] - YYYY-MM-DD`)
@@ -20,21 +48,3 @@ If this is a release PR, verify each item before merging:
 - [ ] `Chart.yaml` `version` and `appVersion` updated (done by bump script)
 - [ ] `scripts/release-ready-check.sh` passes locally
 - [ ] Migration notes written in `CHANGELOG.md` if task store schema changed
-- [ ] PR diff includes `CHANGELOG.md` changes
-
-## CHANGELOG diff
-
-<!-- Paste the relevant CHANGELOG section for this release, e.g.:
-
-## [0.2.0] - 2026-04-19
-
-### Added
-- Feature X
-
-### Fixed
-- Bug Y
--->
-
-## Test plan
-
-<!-- How was this tested? -->
diff --git a/.github/release_pr_template.md b/.github/release_pr_template.md
new file mode 100644
index 0000000..ebd7478
--- /dev/null
+++ b/.github/release_pr_template.md
@@ -0,0 +1,81 @@
+# Release v{{VERSION}}
+
+This is a release PR for version {{VERSION}}. It will be tagged as `v{{VERSION}}` after merge.
+
+## Summary
+
+<!-- Brief summary of this release -->
+
+## Release checklist
+
+Before merging, verify each item:
+
+### Version consistency
+
+- [ ] `scripts/bump-version.sh {{VERSION}}` executed successfully
+- [ ] `scripts/release-ready-check.sh {{VERSION}}` passes locally
+- [ ] `Cargo.toml` workspace version is `{{VERSION}}`
+- [ ] `charts/miroir/Chart.yaml` `version` is `{{VERSION}}`
+- [ ] `charts/miroir/Chart.yaml` `appVersion` is `{{VERSION}}`
+
+### CHANGELOG
+
+- [ ] `CHANGELOG.md` has new section `## [{{VERSION}}] - YYYY-MM-DD`
+- [ ] All changes since last release are documented under appropriate subheadings
+- [ ] Release notes extracted from CHANGELOG will be used for GitHub release
+
+### Testing
+
+- [ ] All tests pass on `main` branch
+  ```bash
+  cargo test --workspace
+  ```
+- [ ] `cargo clippy --all-targets -- -D warnings` passes
+- [ ] `cargo fmt --check` passes
+
+### Breaking changes / Migration
+
+- [ ] If task store schema changed: Migration notes added to CHANGELOG.md
+- [ ] If config schema changed: Migration path documented
+- [ ] If API compatibility changed: Versioning policy followed
+
+### Post-merge actions (automated via Argo)
+
+After this PR is merged:
+1. Tag will be created automatically: `git tag -a v{{VERSION}}`
+2. CI will build release artifacts
+3. GitHub release will be created with CHANGELOG notes
+
+## CHANGELOG diff
+
+<!-- Paste the relevant CHANGELOG section for this release -->
+
+```markdown
+## [{{VERSION}}] - YYYY-MM-DD
+
+### Added
+- Feature X
+
+### Changed
+- Behavior Y modified
+
+### Deprecated
+- Old feature Z deprecated
+
+### Removed
+- Deprecated feature W removed
+
+### Fixed
+- Bug V fixed
+
+### Security
+- Security issue U addressed
+```
+
+## Test plan
+
+<!-- How was this release tested? -->
+
+- [ ] Smoke tests pass on dev cluster
+- [ ] Upgrade tested from previous version
+- [ ] Rollback tested if applicable