Publish a Versioned Document Role
Publish a canonical Document Role version with the right route, source JSON, and supporting publication signals.
Publishing a versioned Document Role
The versioned Document Role is the canonical document. Everything around it should reinforce that one public truth.
Publish the versioned source under the required `data/document-role-specifications/` naming pattern.
Confirm the document still satisfies the Specification Root contract.
Make sure the canonical page and convenience route describe the same release.
Keep the visible route, version, and summary synchronized.
Check that fixtures and support files still line up with the published version.
If the source, route, and support files disagree, the release is not truly published cleanly.
This guide is for the case where a domain has already been defined and you need to publish a new version cleanly.
The important idea is that the versioned Document Role is the canonical public document. Everything else should support that document, not compete with it.
Recommended Sequence
- Update the canonical JSON source under
data/document-role-specifications/using the repository naming convention. - Verify that the document still matches the Specification Root contract.
- Confirm the versioned public route and any convenience redirect route point to the intended canonical page.
- Update the public page copy so the visible route, version, and summary all describe the same release.
- Confirm support artifacts and fixtures still line up with the published version.
Publication Checks
- The source file uses the required flat naming pattern.
- The public page reflects the exact version being published.
- The route inventory still points readers to the canonical versioned surface.
- The versioned page is easy to cite without relying on a convenience URL.
Avoid
- Publishing a new version by editing only the human-facing page.
- Leaving redirect targets and source JSON out of sync.
- Using the convenience route as the long-term citation target when a versioned URL exists.
