docs: explain protocol vs capability versioning - #418
Closed
ptiper wants to merge 10 commits into
Closed
Conversation
ptiper
requested review from
jingyli,
knightlin-shopify,
pemamian,
westeezy and
wry-ry
and removed request for
knightlin-shopify,
pemamian and
westeezy
May 7, 2026 08:13
- Update versioning.md with high-level two-tiered versioning concepts. - Link to detailed specifications in overview.md to avoid duplication. - Add protocol compatibility alert and negotiation links in overview.md. - Fix markdown formatting to pass lint checks.
ptiper
force-pushed
the
docs/update-versioning-docs
branch
from
May 7, 2026 08:51
4073c07 to
b720e36
Compare
Contributor
Author
damaz91
previously approved these changes
Jun 23, 2026
jingyli
reviewed
Jun 23, 2026
jingyli
left a comment
jingyli
left a comment
Contributor
There was a problem hiding this comment.
The line wrapping behaviour in the PR looks a bit odd when viewing against the existing contents we have in the documentation. Curious if this is intended from lint? Or should we make it more consistent with the rest of the file..?
Replace the two-tiered framing in versioning.md with a three-layer model - transport bindings, core protocol, capabilities and extensions - and reconcile the parallel paragraph in overview.md §Version Negotiation, which previously said the protocol version "governs ... transport bindings". That phrasing contradicts the existing line in §Independent Component Versioning: "Transports MAY define their own version handling mechanisms." The three-layer model matches what the schema and the negotiation algorithm already do: - Transport: each service entry declares its own `version`. The wire contract lives in the OpenAPI/OpenRPC/Agent Card document at the service entry's `schema` field. Not consumed by the intersection algorithm; transports MAY evolve independently. - Core protocol (`ucp.version`): cross-cutting mechanisms shared by every transport binding - discovery, negotiation flow, signatures, profile structure, error envelope. Pre-negotiation gate; mismatch returns `version_unsupported`. - Capabilities and extensions: each capability entry declares its own `version`. Intersected at negotiation; the highest mutual version wins, and extensions MAY declare `requires.protocol` and `requires.capabilities` constraints to further filter the active set. Also: - Fixes a broken cross-reference in versioning.md (`specification/overview.md#capability-versions` -> `#version-negotiation`). - Hard-wraps the Protocol Compatibility Constraint IMPORTANT callout in overview.md §Capability Versions to match the file's ~80-col convention and the existing `> [!NOTE]` style in split-payments.md.
igrigorik
force-pushed
the
docs/update-versioning-docs
branch
from
June 25, 2026 07:23
33474c4 to
6f6282d
Compare
damaz91
reviewed
Jun 29, 2026
igrigorik
approved these changes
Jul 3, 2026
5 tasks
Contributor
|
Closing, let's continue in #614. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
4 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Description
Category (Required)
ucp-schematool (resolver, linter, validator). (Requires Maintainer approval)Checklist
Screenshots / Logs (if applicable)