Principle
SemVer for the contract
Versioning is about implementer impact: breaking changes, additive changes, and compatible fixes.
OpenAgent · Changelog
Changelog
A guide to tracking changes in the Open Agent Specification. For canonical history, use the specification repository and the specification changelog view.
Source
Canonical diffs
Framing
SemVer
Bias
Implementer-first
§ 01How to follow changes
Use canonical sources
If you're implementing a verifier or an SDK, treat these as authoritative: the spec repository history, RFC discussions, and the specification changelog view.
Specification changelogA structured view designed for implementers: what changed, where it lives, and what to verify.In-siteRepository historyPull requests, review comments, and merged diffs. This is the record a verifier can audit.CanonicalRFC processProposals are reviewed in public before they change the contract. It's where ambiguity gets removed.Discussion
§ 02Versioning principles
What changelogs should guarantee
A changelog is useful when it maps directly to implementer work: what to update, what to test, and what can break.
Principle
Changelog is a pointer
A changelog entry should link back to the canonical diff and RFC discussion, not be the only record.
Principle
Verifier expectations matter
If verifier behavior changes, it must be explicit in the contract and easy to test.
Principle
No silent drift
Docs and examples should move with the contract so implementers don't guess what's current.
Next
Need help assessing impact?
If a contract change affects verifier behavior, bring it to the RFC process so the decision and rationale stay public.