ci: release automation — PR template, Prepare release workflow, RELEASE_NOTES body

- PR template: Summary, Test plan, Closes #N
- Prepare release: workflow_dispatch to tag from main (version input)
- Release: populate body from RELEASE_NOTES.md section via extract_release_notes.py
- docs/release-process.md: release steps and automation summary
- README: link release process and PR template

Made-with: Cursor

Author: haasonsaas

.github/pull_request_template.md

@@ -0,0 +1,13 @@
+## Summary
+
+<!-- What does this PR do? -->
+
+## Test plan
+
+- [ ] `cargo test`
+- [ ] `cargo clippy --all-targets`
+- <!-- Add any manual or integration steps -->
+
+## Closes
+
+<!-- Link issues this PR ships: Closes #28, #29 -->

.github/scripts/extract_release_notes.py

@@ -0,0 +1,47 @@
+#!/usr/bin/env python3
+"""Extract the release notes section for a given version from RELEASE_NOTES.md.
+
+Usage:
+  python3 .github/scripts/extract_release_notes.py 0.5.27
+
+Prints the section for "# Release Notes - v0.5.27" up to the next "---" or
+"# Release Notes - v". If no section is found, exits 1 (caller can use a fallback).
+"""
+
+from __future__ import annotations
+
+import re
+import sys
+from pathlib import Path
+
+
+def main() -> int:
+    if len(sys.argv) != 2:
+        print("Usage: extract_release_notes.py <version>", file=sys.stderr)
+        return 1
+    version = sys.argv[1].strip()
+    if version.startswith("v"):
+        version = version[1:]
+    path = Path("RELEASE_NOTES.md")
+    if not path.exists():
+        print("RELEASE_NOTES.md not found", file=sys.stderr)
+        return 1
+    text = path.read_text()
+    # Match "# Release Notes - v0.5.27" or "# Release Notes - v0.5.27 "
+    pattern = rf"^# Release Notes - v{re.escape(version)}\s*$"
+    match = re.search(pattern, text, re.MULTILINE)
+    if not match:
+        return 1
+    start = match.end()
+    # End at next "---" (horizontal rule) or next "# Release Notes - v"
+    end_match = re.search(r"\n---\s*\n|^# Release Notes - v", text[start:], re.MULTILINE)
+    end = start + end_match.start() if end_match else len(text)
+    section = text[start:end].strip()
+    if not section:
+        return 1
+    print(section)
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

.github/workflows/prepare-release.yml

@@ -0,0 +1,65 @@
+# Manual workflow: create and push a release tag from main.
+# Prerequisites: Cargo.toml and charts/diffscope/Chart.yaml appVersion must already
+# be bumped and merged to main. Then run this workflow with the same version.
+# This pushes the tag and triggers the Release workflow (builds, release notes, assets).
+name: Prepare release
+
+on:
+  workflow_dispatch:
+    inputs:
+      version:
+        description: 'Release version (e.g. 0.5.28)'
+        required: true
+        type: string
+
+permissions:
+  contents: write
+
+jobs:
+  tag-and-push:
+    name: Tag and push
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout main
+        uses: actions/checkout@v5
+        with:
+          ref: main
+          fetch-depth: 0
+
+      - name: Normalize version input
+        id: version
+        run: |
+          v="${{ inputs.version }}"
+          v="${v#v}"
+          echo "version=$v" >> "$GITHUB_OUTPUT"
+          echo "tag=v$v" >> "$GITHUB_OUTPUT"
+
+      - name: Verify Cargo.toml version matches
+        run: python3 .github/scripts/check_version_sync.py --tag "v${{ steps.version.outputs.version }}"
+
+      - name: Verify Chart appVersion matches
+        run: |
+          chart_version=$(python3 -c "
+          import re
+          from pathlib import Path
+          c = Path('charts/diffscope/Chart.yaml').read_text()
+          m = re.search(r\"\"\"appVersion:\s*['\"]?(.*?)['\"]?\s*$\"\"\", c, re.MULTILINE)
+          print(m.group(1).strip()) if m else exit(1)
+          ")
+          expected="${{ steps.version.outputs.version }}"
+          if [ "$chart_version" != "$expected" ]; then
+            echo "Chart appVersion ($chart_version) does not match input ($expected). Bump charts/diffscope/Chart.yaml and merge to main first."
+            exit 1
+          fi
+
+      - name: Create and push tag
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          tag="${{ steps.version.outputs.tag }}"
+          if git rev-parse "$tag" >/dev/null 2>&1; then
+            echo "Tag $tag already exists."
+            exit 1
+          fi
+          git tag -a "$tag" -m "Release $tag"
+          git push origin "$tag"

.github/workflows/release.yml

@@ -29,6 +29,15 @@ jobs:
         id: get_version
         run: echo "VERSION=${GITHUB_REF#refs/tags/}" >> "$GITHUB_OUTPUT"
 
+      - name: Extract release notes from RELEASE_NOTES.md
+        id: release_notes
+        run: |
+          v="${GITHUB_REF#refs/tags/v}"
+          python3 .github/scripts/extract_release_notes.py "$v" > release_notes_section.txt || true
+          echo "body<<RELEASE_NOTES_EOF" >> "$GITHUB_OUTPUT"
+          cat release_notes_section.txt >> "$GITHUB_OUTPUT" || true
+          echo "RELEASE_NOTES_EOF" >> "$GITHUB_OUTPUT"
+
       - name: Verify release metadata matches tag
         env:
           TAG_NAME: ${{ steps.get_version.outputs.VERSION }}
@@ -55,7 +64,7 @@ jobs:
           body: |
             # DiffScope ${{ steps.get_version.outputs.VERSION }}
             
-            See [CHANGELOG.md](https://github.com/evalops/diffscope/blob/main/CHANGELOG.md) for details.
+            ${{ steps.release_notes.outputs.body }}
             
             ## 🚀 Installation
             

README.md

@@ -1002,7 +1002,7 @@ The summary includes:
 
 Contributions are welcome! Please open an issue first to discuss what you would like to change. Enhancement backlog and triage: see [docs/ROADMAP.md](docs/ROADMAP.md) and `gh issue list --label "priority: high"`.
 
-**PR workflow:** Open a PR → ensure CI is green (version, lint, security, test, mutation, review) → merge when ready. Use a short test plan in the PR description. Small, focused PRs are preferred.
+**PR workflow:** Open a PR → ensure CI is green (version, lint, security, test, mutation, review) → merge when ready. Use a short test plan in the PR description. Small, focused PRs are preferred. Use the PR template (Summary, Test plan, **Closes #N**). **Release process:** [docs/release-process.md](docs/release-process.md) (version bump, RELEASE_NOTES, Prepare release workflow).
 
 ### Local Development Checks
 

docs/release-process.md

@@ -0,0 +1,48 @@
+# Release process
+
+This doc and GitHub Actions make releases repeatable with minimal manual steps.
+
+## One-time per release (on main)
+
+1. **Bump version** in a PR (or directly on main):
+   - `Cargo.toml` → `[package].version = "0.5.28"`
+   - `charts/diffscope/Chart.yaml` → `appVersion: "0.5.28"`
+2. **Update release notes** in the same PR (or a follow-up):
+   - In `RELEASE_NOTES.md`, add a new section at the top:
+     ```markdown
+     # Release Notes - v0.5.28
+     📅 **Release Date**: YYYY-MM-DD
+     ## Summary
+     - Bullet points for this release.
+     ## Full Changelog
+     [v0.5.27...v0.5.28](https://github.com/evalops/diffscope/compare/v0.5.27...v0.5.28)
+     ---
+     ```
+   - Optionally update `docs/ROADMAP.md` “Shipped” section.
+3. **Merge to main** (e.g. “chore: bump version to 0.5.28”).
+
+## Create the release (automated)
+
+4. **Run the “Prepare release” workflow**
+   - In the repo: **Actions** → **Prepare release** → **Run workflow**.
+   - Enter the **version** (e.g. `0.5.28`). Must match `Cargo.toml` and `Chart.yaml` on main.
+   - The workflow creates tag `v0.5.28`, pushes it, and triggers the **Release** workflow.
+5. **Release workflow** (runs on tag push):
+   - Verifies `Cargo.toml` and Chart `appVersion` match the tag.
+   - Extracts the section for this version from `RELEASE_NOTES.md` and uses it in the GitHub Release body.
+   - Builds binaries for Linux/macOS/Windows, builds Docker image, creates the release and uploads assets.
+
+## PR workflow (reminder)
+
+- Use the **PR template** (Summary, Test plan, **Closes #N**).
+- Linking “Closes #28” in the PR body auto-closes the issue when the PR is merged.
+
+## Automation summary
+
+| Step | Automation |
+|------|------------|
+| Version sync (CI) | `check_version_sync.py` fails if `Cargo.toml` is behind latest tag. |
+| Tag and trigger release | **Prepare release** workflow (manual run with version input). |
+| Release body | **Release** workflow reads `RELEASE_NOTES.md` for the tagged version. |
+| Binaries + Docker | **Release** workflow builds and uploads. |
+| Issue close | Add “Closes #N” in PR body. |