diff --git a/AGENTS.md b/AGENTS.md index 6e9d44913..c5aebbffe 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -60,8 +60,9 @@ Follow that checklist's safety rules: justification and a rollback story. - Update docs when changing setup, onboarding, runtime behavior, architecture, testing guidance, or user-facing workflows. -- Update `CHANGELOG.md` for user-visible behavior, setup, workflow, or - documentation changes that should be release-note ready. +- Do not edit `CHANGELOG.md` in ordinary contributor PRs. The release workflow + owns changelog updates through release commits. If a change is release-note + worthy, include concise release-note wording in the PR body instead. - For UI or UX changes, include before/after evidence and test relevant desktop, narrow, and mobile states. - For behavior changes, add or update automated tests where practical and list diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 97b3d894e..08529741c 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -17,8 +17,9 @@ Hermes WebUI is intentionally simple to work on: Python on the server, vanilla J and the relevant RFC listed there. Use those documents as review guardrails: keep the change scoped, preserve the -no-build-step architecture, update docs/changelog when behavior changes, include -UI evidence for UI changes, and add tests for behavior changes where practical. +no-build-step architecture, update docs when behavior changes, put +release-note-worthy details in the PR body, include UI evidence for UI changes, +and add tests for behavior changes where practical. ### Contract-affecting PRs @@ -96,6 +97,10 @@ There is currently no PR template in this repo, so include the important section If the change is user-visible, include screenshots or a short video. +If the change is release-note-worthy, include concise release-note wording in +the PR body. Do not edit `CHANGELOG.md` directly in ordinary contributor PRs; +the release workflow maintains it through release commits. + For UI or UX changes, before/after images are required. PRs that change the interface or interaction flow without before/after images may not receive meaningful review until that evidence is added. ### 4. AI Usage Disclosure @@ -120,7 +125,9 @@ Common files: - [ROADMAP.md](ROADMAP.md) for shipped features and sprint history - [ARCHITECTURE.md](ARCHITECTURE.md) for implementation details and design constraints - [TESTING.md](TESTING.md) for manual and automated verification guidance -- [CHANGELOG.md](CHANGELOG.md) when maintainers want release-note-ready entries +- [CHANGELOG.md](CHANGELOG.md) for release history context. Do not edit it in + ordinary contributor PRs; include release-note-ready wording in the PR body + so maintainers can carry it into the release workflow. ## Project-Specific Guidelines diff --git a/docs/CONTRACTS.md b/docs/CONTRACTS.md index 3eb8b5d08..39a0ccc3d 100644 --- a/docs/CONTRACTS.md +++ b/docs/CONTRACTS.md @@ -6,8 +6,8 @@ source documents and it does not mark proposals as implemented. Follow each linked document's status and scope. Use this file when starting a change so the relevant public contract is visible -before code is edited. This first version focuses on documentation routing; it -does not change runtime behavior, maintainer policy, bot behavior, or CI gates. +before code is edited. This index focuses on documentation routing and +contributor guidance; it does not change runtime behavior or CI gates. ## Start here @@ -17,8 +17,9 @@ does not change runtime behavior, maintainer policy, bot behavior, or CI gates. PR description expectations, UI evidence, and project-specific constraints. - [`README.md`](../README.md): product overview, quick start, architecture map, feature inventory, and docs index. -- [`CHANGELOG.md`](../CHANGELOG.md): release-note-ready history. Update it when - maintainers should carry the change into release notes. +- [`CHANGELOG.md`](../CHANGELOG.md): release history maintained by the release + workflow. Read it for context, but do not edit it in ordinary contributor PRs; + put release-note-ready wording in the PR body instead. ## Runtime, durability, and state contracts @@ -168,7 +169,8 @@ Required checks: - Onboarding/setup validation used isolated `HERMES_HOME` and `HERMES_WEBUI_STATE_DIR`, unless the human operator explicitly requested real state. -- Docs and `CHANGELOG.md` updates are either included or explicitly not needed. +- Docs updates are included or explicitly not needed, and release-note-worthy + changes are described in the PR body rather than by editing `CHANGELOG.md`. - After the GitHub write, read the PR back and verify the headings rendered as intended. @@ -200,7 +202,8 @@ Before opening a change for review, confirm: - `AGENTS.md`, this index, and any linked contract for the touched subsystem were read before editing. - Behavior, setup, architecture, testing, or workflow changes update the relevant - docs; release-note-ready changes update `CHANGELOG.md`. + docs; release-note-ready changes include PR-body release-note wording while + `CHANGELOG.md` is left to release commits. - UI/UX changes include before/after evidence and cover relevant desktop, narrow, and mobile states. - Runtime, streaming, recovery, replay, compression, or sidebar changes state