Add release checklist and changelog-driven release notes

.github/workflows/release.yml

@@ -69,14 +69,18 @@ jobs:
             echo "version=${GITHUB_REF#refs/tags/v}" >> $GITHUB_OUTPUT
           fi
 
-      - name: Generate changelog
+      - name: Extract changelog entry
         id: changelog
         run: |
-          PREV_TAG=$(git describe --tags --abbrev=0 HEAD^ 2>/dev/null || echo "")
-          if [ -n "$PREV_TAG" ]; then
-            CHANGELOG=$(git log --pretty=format:"* %s (%h)" $PREV_TAG..HEAD)
-          else
-            CHANGELOG=$(git log --pretty=format:"* %s (%h)" -20)
+          VERSION="${{ steps.version.outputs.version }}"
+          SECTION=$(awk "/^## ${VERSION//./\\.} /{flag=1; next} /^## /{flag=0} flag" CHANGELOG.md)
+          if ! grep -q "^## ${VERSION//./\\.} " CHANGELOG.md; then
+            echo "Missing CHANGELOG.md entry for version $VERSION" >&2
+            exit 1
+          fi
+          CHANGELOG="$SECTION"
+          if [ -z "$CHANGELOG" ]; then
+            CHANGELOG="- See CHANGELOG.md for version $VERSION."
           fi
           echo "changelog<<EOF" >> $GITHUB_OUTPUT
           echo "$CHANGELOG" >> $GITHUB_OUTPUT

CHANGELOG.md

@@ -4,4 +4,17 @@ All notable changes to this project will be documented in this file.
 
 Version tagging is currently automated with `commit-and-tag-version`, but the changelog itself is intended to be a human-readable release summary.
 
+The release process is documented in `RELEASE.md`. Keep `Unreleased` current and
+promote those entries into a dated section when cutting a release.
+
+## Unreleased
+
+### Docs
+
+- Establish a repo-level release checklist and changelog maintenance guidance.
+
 ## 0.1.0 (2026-03-16)
+
+### Added
+
+- Initial release of the embedded asset server and bundled frontend component library.

README.md

@@ -490,11 +490,15 @@ cargo build
 
 Consumer integration stays npm-free. Maintainer release automation does not.
 
+- Keep `CHANGELOG.md` current as work lands.
+- Use `RELEASE.md` as the source of truth when preparing a public release.
+- Run `make pre-release` before tagging.
 - Runtime and application integration use only the bundled static assets and the Rust crate.
 - Version bump targets in `Makefile` currently use `npx commit-and-tag-version`.
+- The GitHub and Forgejo release workflows trigger only after the generated `v*` tag is pushed.
 - Release and publish validation otherwise run through Cargo and GitHub Actions.
 
-If you are cutting a release locally, make sure Node.js with `npx` is available before using the `bump-*` targets.
+If you are cutting a release locally, make sure Node.js with `npx` is available before using the `bump-*` targets. After the bump completes, push the release commit and tag with `git push --follow-tags` or an equivalent tag-push command so the release automation actually starts.
 
 ## Acknowledgments
 

RELEASE.md

@@ -0,0 +1,32 @@
+# Release Checklist
+
+Use this checklist for every public release of `solverforge-ui`.
+
+## Before Tagging
+
+- Confirm `main` is green in CI.
+- Run `make assets` and verify no generated file drift remains.
+- Run `make pre-release`.
+- Review `CHANGELOG.md` and move the relevant `Unreleased` entries into the new version section.
+- Confirm README and wireframe docs still match the shipped surface.
+- Verify the crate version in `Cargo.toml` matches the intended release.
+
+## Tagging
+
+- Use one of the `make bump-patch`, `make bump-minor`, or `make bump-major` targets if you want the existing tag helper workflow.
+- If using the bump targets locally, ensure Node.js with `npx` is available.
+- Push the release commit and tag to GitHub.
+
+## After Tagging
+
+- Confirm the GitHub release job succeeds.
+- Confirm the crates.io publish job succeeds.
+- Inspect the published package contents with the package verification workflow.
+- Sanity-check the release notes body against the new `CHANGELOG.md` entry.
+
+## Changelog Rules
+
+- Keep `Unreleased` up to date as work lands.
+- Group entries under short headings like `Added`, `Changed`, `Fixed`, and `Docs` when helpful.
+- Write entries for user-visible changes, not internal churn.
+- Before cutting a release, promote the relevant `Unreleased` items into a dated version heading.