[wimaha]

Why

README and docs/*.md describe main (Docker :dev), but most users run :latest, which is the last release (2.4.0). 14 commits have been merged since then, including a breaking change (POST-only key routes) and trustedOrigins. A :latest user currently reads docs for features they don't have.

What

• Note at the top of README, docs/environment_variables.md and docs/installation.md: these pages describe main/:dev. The README note links the README of 2.4.0 and the new CHANGELOG.
• CHANGELOG.md (Keep a Changelog): Unreleased lists everything since 2.4.0 (Test the proxy against a simulated car #169–Update Go toolchain and dependencies #172). Older versions point to the GitHub releases. A "Releasing" section lists the steps before tagging.
• Markers: Sections that exist only in main get a line *(unreleased)* below the heading. It goes on its own line so heading anchors like #trustedorigins stay stable. At release time each one becomes *(since X)*.
• Release workflow: A new docs job runs scripts/check-release-docs.sh <tag> before publishing. It stops the release if *(unreleased)* markers are left, if CHANGELOG.md has no ## <tag> section, or if the README note doesn't point to <tag>. Manual runs on a branch skip the check, as before.
• release_docs_test.go runs on every CI run (make test). It checks that the README note matches the latest version in CHANGELOG.md, that the docs carry the note, and that markers sit on their own line.

Release steps from now on

1. ## Unreleased → ## 2.5.0 - <date>, with a new empty ## Unreleased above it
2. *(unreleased)* → *(since 2.5.0)*
3. README note: 2.4.0 → 2.5.0 (text and link)
4. Commit, then tag 2.5.0

Testing

• go vet ./..., go test -race ./...
• Negative check: if the README note points to 2.3.0, TestReadmeNotePointsToLatestRelease fails.
• check-release-docs.sh 2.5.0 on the current state fails with all three findings. On a copy prepared for release (steps 1–3 applied) it passes. With 2.5.1 against that copy it fails again.

🤖 Generated with Claude Code

[github-actions]

✅ Ready to merge

This PR only changes docs, a changelog, a test and the release workflow. The proxy code, API, config and Docker image are not touched.

Impact on existing users: None – the change is additive. Users only see a note in the docs.

To-do for the author

• Nothing left to do

Test before merging: After merge, push a test tag (or prepare the 2.5.0 release) and check that the new docs job passes and docker still publishes :latest.

Technical details

• .github/workflows/release.yml: docker now needs docs. The if allows success or skipped, so manual runs on a branch still publish as before. Tag runs fail if the docs check fails. This is the intended behaviour. Side effect: any tag (e.g. v2.5.0 or 2.5.0-rc1) fails the check unless README/CHANGELOG use the same string. The "Releasing" section already says "no v".
• scripts/check-release-docs.sh: logic looks right. Not run by me; I did not execute the script or the tests.
• release_docs_test.go: reads files relative to the repo root, which works with go test in the root package.