Skip to content

Beautiful, AI-native markdown IDE and LLM wiki

chore(ok): enforce concise changelog authoring and review (#4468)

Andrew Mikofalvy3a597b135d70
diff --git a/.changeset/README.md b/.changeset/README.md
index 0da04686a..ad0bd338a 100644
--- a/.changeset/README.md
+++ b/.changeset/README.md
@@ -16,6 +16,8 @@ holds three bits of information:
---
+Follow the [changelog authoring and review policy](../AGENTS.md) when writing release notes.
+
## Open Knowledge convention — pre-1.0 bump types
**While Open Knowledge is pre-1.0, NEVER declare a `major` bump in a changeset.** OK uses a modified semver where the bump types map differently:
diff --git a/AGENTS.md b/AGENTS.md
index 6e09ef96f..05117ffe9 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -82,7 +82,9 @@ Every behavior-changing PR ships a `.changeset/<kebab-name>.md` file. The body b
- Create one with `pnpm run changeset`, or hand-write a file named `.changeset/<descriptive-kebab-slug>.md`.
- Front-matter: at minimum `'@inkeep/open-knowledge': patch`. OpenKnowledge follows semver with a **pre-1.0 shift-down**: while we're below `1.0.0`, what semver would call a major (breaking API change) is encoded as `minor`, and what semver would call a minor (new feature) is encoded as `patch`. Most changesets are `patch`. `minor` is rare — reserve it for large API contract changes or large feature additions. **Never declare `major` pre-1.0** (see the `"//"` line in `.changeset/config.json`).
-- Body should lead with the user-visible verb, name the affected command or surface in a code-span, and (if relevant) show before/after. Skip internal references like spec IDs or story numbers — those rot and aren't visible to readers of the public release notes.
+
+**Changelog authoring and review.** Use one short sentence for the user-visible outcome; a second only for a necessary qualification or upgrade action. Maximum 50 words per changeset body, across all paragraphs and bullets. Omit implementation details, internal identifiers and exhaustive edge cases; link migration instructions. Reviewers check accuracy, required actions and brevity; request technical detail in docs. Never split one explanation across changesets to evade the budget.
+
- Don't write inline references to sibling-package versions (e.g. `@inkeep/[email protected]`) — the fixed-group lock-step bumps are computed at release time and any number you'd write would be wrong.
- Skip changesets for docs-only edits, test-only edits, or CI-only edits that don't change runtime behavior.