diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index 9662e8a..656079f 100644 --- a/.github/workflows/release.yml +++ b/.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<> $GITHUB_OUTPUT echo "$CHANGELOG" >> $GITHUB_OUTPUT diff --git a/CHANGELOG.md b/CHANGELOG.md index af10874..7196593 100644 --- a/CHANGELOG.md +++ b/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. diff --git a/README.md b/README.md index 4b0aa5b..1ecb873 100644 --- a/README.md +++ b/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 diff --git a/RELEASE.md b/RELEASE.md new file mode 100644 index 0000000..511def9 --- /dev/null +++ b/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.