diff --git a/.pi/prompts/pre-release-audit.md b/.pi/prompts/pre-release-audit.md index 3b54f6d1..62fe4362 100644 --- a/.pi/prompts/pre-release-audit.md +++ b/.pi/prompts/pre-release-audit.md @@ -44,10 +44,10 @@ Process: - formatting-only changes - comment-only/doc-only changes unless they materially affect users -6. Audit `.pi/docs/CHANGELOG.md` and issue references. +6. Audit `docs/next/CHANGELOG.md` and issue references. - Treat root `CHANGELOG.md` as the latest released changelog. - - Treat `.pi/docs/CHANGELOG.md` as the next-release changelog. - - Compare meaningful user-facing changes in the commit range against `.pi/docs/CHANGELOG.md`. + - Treat `docs/next/CHANGELOG.md` as the next-release changelog. + - Compare meaningful user-facing changes in the commit range against `docs/next/CHANGELOG.md`. - Flag missing entries for new features, bug fixes, removals, breaking changes, defaults, compatibility changes, user-visible command/config/API behavior, and security-relevant changes. - Inspect commit bodies for issue reference lines in the form `refs #`. - Flag normal commits that use GitHub closing keywords like `fixes #`, `closes #`, or `resolves #`, because they close issues before release when they land on `master`. @@ -60,14 +60,14 @@ Process: 7. Audit next-release public docs. - Treat root `README.md`, `CONFIGURATION.md`, `INTEGRATIONS.md`, and `SOCKET_API.md` as the latest released public docs. - - Treat `.pi/docs/README.md`, `.pi/docs/CONFIGURATION.md`, `.pi/docs/INTEGRATIONS.md`, and `.pi/docs/SOCKET_API.md` as the next-release versions. - - Compare meaningful user-facing changes in the range against `.pi/docs/` first. + - Treat `docs/next/README.md`, `docs/next/CONFIGURATION.md`, `docs/next/INTEGRATIONS.md`, and `docs/next/SOCKET_API.md` as the next-release versions. + - Compare meaningful user-facing changes in the range against `docs/next/` first. - Flag missing next-release docs for new or changed features, commands, config keys, protocol behavior, integrations, defaults, and compatibility notes. - - Compare `.pi/docs/` against the root docs. Flag each difference as intended to ship in this release, stale, or needing user decision. + - Compare `docs/next/` against the root docs. Flag each difference as intended to ship in this release, stale, or needing user decision. - Also audit `website/` and example config snippets for release readiness, but keep them aligned with the latest published release unless the user explicitly asks for prerelease docs. 8. Verify finalization state. - - Before `just release`, approved `.pi/docs/*` files must be copied to their root counterparts. + - Before `just release`, approved `docs/next/*` files must be copied to their root counterparts. - Run or recommend: ```bash just release-docs-check @@ -77,8 +77,8 @@ Process: 9. Apply changes only when asked. - Do not edit files during the audit unless the user explicitly asks you to apply fixes. - - When asked to apply audit fixes, update `.pi/docs/CHANGELOG.md` and any relevant `.pi/docs/` files first. - - When asked to finalize release docs, copy approved `.pi/docs/` files into the matching root files and run `just release-docs-check`. + - When asked to apply audit fixes, update `docs/next/CHANGELOG.md` and any relevant `docs/next/` files first. + - When asked to finalize release docs, copy approved `docs/next/` files into the matching root files and run `just release-docs-check`. Output format: diff --git a/AGENTS.md b/AGENTS.md index f5258d5f..21a9344e 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -51,10 +51,10 @@ Unit tests live next to the code (`#[cfg(test)] mod tests`). If you add behavior ## Conventions - Conventional commits, lowercase, no emojis. -- Do not edit root `CHANGELOG.md` during normal feature or fix work. For user-facing features, fixes, removals, breaking changes, and meaningful behavior changes, update `.pi/docs/CHANGELOG.md` in the same change when it makes sense. +- Do not edit root `CHANGELOG.md` during normal feature or fix work. Maintainers prepare `docs/next/CHANGELOG.md` during release review unless explicitly asked to update it earlier. - Treat the root public docs as the latest released docs. Do not document unreleased behavior in root `README.md`, `CONFIGURATION.md`, `INTEGRATIONS.md`, `SOCKET_API.md`, or `CHANGELOG.md` during normal feature or fix work. -- Treat `.pi/docs/README.md`, `.pi/docs/CONFIGURATION.md`, `.pi/docs/INTEGRATIONS.md`, `.pi/docs/SOCKET_API.md`, and `.pi/docs/CHANGELOG.md` as the next-release versions of those public docs. When unreleased work needs public documentation, update the matching file under `.pi/docs/` instead of the root file. -- Before release, copy the approved `.pi/docs/` versions into the root public docs. `just release` blocks until each root public doc and `CHANGELOG.md` are identical to their `.pi/docs/` counterparts. +- Treat `docs/next/README.md`, `docs/next/CONFIGURATION.md`, `docs/next/INTEGRATIONS.md`, `docs/next/SOCKET_API.md`, and `docs/next/CHANGELOG.md` as the next-release versions of those public docs. When unreleased work needs public documentation, update the matching file under `docs/next/` instead of the root file. +- Before release, copy the approved `docs/next/` versions into the root public docs. `just release` blocks until each root public doc and `CHANGELOG.md` are identical to their `docs/next/` counterparts. - Keep website copy and config examples aligned with the latest published release unless the user explicitly asks for prerelease docs. - Put local PRDs, planning notes, and exploratory specs under `.prd/`; that directory is ignored and locally controlled. - When a normal feature or fix commit relates to a GitHub issue, add a commit body line `refs #` after the subject. Use this shape: @@ -70,7 +70,7 @@ Unit tests live next to the code (`#[cfg(test)] mod tests`). If you add behavior ## Releases -Before cutting a release, run `/pre-release-audit` to compare commits since the last tag against `.pi/docs/CHANGELOG.md` and `.pi/docs/`, then copy the approved next-release docs and changelog into the root public docs. The release script promotes the root changelog's `## Unreleased` section into the versioned entry and copies the prepared changelog back to `.pi/docs/CHANGELOG.md` so the next cycle starts clean. +Before cutting a release, run `/pre-release-audit` to compare commits since the last tag against `docs/next/CHANGELOG.md` and `docs/next/`, then copy the approved next-release docs and changelog into the root public docs. The release script promotes the root changelog's `## Unreleased` section into the versioned entry and copies the prepared changelog back to `docs/next/CHANGELOG.md` so the next cycle starts clean. Default release flow: diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index f6be5604..45aeae8b 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -46,6 +46,23 @@ If your issue does not make the direction clear, it will likely be closed. If you plan to implement the change yourself, say that directly in the issue and use the `intends-to-pr` label. That signals intent. It is not approval. +## Documentation for unreleased changes + +The root docs describe the latest released version of herdr. Do not update root `README.md`, `CONFIGURATION.md`, `INTEGRATIONS.md`, `SOCKET_API.md`, or `CHANGELOG.md` for normal PRs. + +If your PR changes user-facing behavior, update the matching next-release docs under `docs/next/` instead. + +Examples: + +- config changes: update `docs/next/CONFIGURATION.md` +- integration changes: update `docs/next/INTEGRATIONS.md` +- socket/API changes: update `docs/next/SOCKET_API.md` +- workflow or usage changes: update `docs/next/README.md` + +You do not need to edit the changelog for normal PRs. Maintainers prepare `docs/next/CHANGELOG.md` during release review. + +If you are unsure whether docs are needed, mention it in the PR. + ## Before submitting a PR Install the repo hook once in your clone. diff --git a/.pi/docs/CHANGELOG.md b/docs/next/CHANGELOG.md similarity index 100% rename from .pi/docs/CHANGELOG.md rename to docs/next/CHANGELOG.md diff --git a/.pi/docs/CONFIGURATION.md b/docs/next/CONFIGURATION.md similarity index 100% rename from .pi/docs/CONFIGURATION.md rename to docs/next/CONFIGURATION.md diff --git a/.pi/docs/INTEGRATIONS.md b/docs/next/INTEGRATIONS.md similarity index 100% rename from .pi/docs/INTEGRATIONS.md rename to docs/next/INTEGRATIONS.md diff --git a/.pi/docs/README.md b/docs/next/README.md similarity index 100% rename from .pi/docs/README.md rename to docs/next/README.md diff --git a/.pi/docs/SOCKET_API.md b/docs/next/SOCKET_API.md similarity index 100% rename from .pi/docs/SOCKET_API.md rename to docs/next/SOCKET_API.md diff --git a/justfile b/justfile index 30fabe1b..794c398b 100644 --- a/justfile +++ b/justfile @@ -32,11 +32,11 @@ build: build-libghostty-vt: scripts/build_vendored_libghostty_vt.sh -# Check that public docs and changelog have been finalized from .pi/docs before release +# Check that public docs and changelog have been finalized from docs/next before release release-docs-check: @for file in README.md CONFIGURATION.md INTEGRATIONS.md SOCKET_API.md CHANGELOG.md; do \ - if ! diff -u "$file" ".pi/docs/$file"; then \ - echo "error: $file differs from .pi/docs/$file; finalize release docs before releasing"; \ + if ! diff -u "$file" "docs/next/$file"; then \ + echo "error: $file differs from docs/next/$file; finalize release docs before releasing"; \ exit 1; \ fi; \ done @@ -53,11 +53,11 @@ release version: fi just release-docs-check python3 scripts/changelog.py prepare --version {{version}} - cp CHANGELOG.md .pi/docs/CHANGELOG.md + cp CHANGELOG.md docs/next/CHANGELOG.md sed -i.bak 's/^version = ".*"/version = "{{version}}"/' Cargo.toml && rm -f Cargo.toml.bak cargo update -p herdr --offline just check - git add CHANGELOG.md .pi/docs/CHANGELOG.md Cargo.toml Cargo.lock + git add CHANGELOG.md docs/next/CHANGELOG.md Cargo.toml Cargo.lock git diff --cached --quiet || git commit -m "release: v{{version}}" git tag -a v{{version}} -m "v{{version}}" git push --follow-tags