Version contracts and documentation together

Know which version you mean

A contract's version identifies a particular declared behavior. A package version identifies a distribution artifact. A website or application revision identifies a deployment. Those numbers can change independently.

When reporting a problem, include the contract key and version plus the package versions or source commit. The documentation shell's version is not enough to identify the operation a consumer is executing.

Use explicit references where reproducibility matters

The portable VersionedSpecRef model contains a key and version. OptionalVersionedSpecRef permits the version to be omitted, typically selecting the latest available definition through the owning resolver.

Use explicit versions in examples and compatibility tests that must be reproducible. If you intentionally use latest-version selection, test what happens when the registry receives a newer definition.

export interface VersionedSpecRef {
  key: string;
  version: string;
}

Exact type shape from contracts-spec/src/versioning/refs.ts at d58fa5b7; comments omitted.

Review the behavioral change

Compare inputs, outputs, named failures, policy requirements and effect expectations. Adding a required input can break an existing caller even when the handler remains unchanged. Tightening an approval rule can change which requests succeed.

Plan how old consumers transition: keep the old contract temporarily, provide an intentional mapping, or coordinate an upgrade. Do not silently repoint a stable example at a different behavioral contract.

Publish the matching documentation

Pin source links and examples to the release they describe. Generate reference output from that same source and retain the provenance in the docs artifact. Update prose when an import path or execution guarantee changes.

When a source refactor preserves a compatibility facade, explain both the canonical owner and the supported historical import. Ownership moving between packages is not automatically a consumer migration.