Documentation
Versioning

Versioning

UCP uses date-based version identifiers in the format YYYY-MM-DD, representing the date of the last incompatible change.

Version Strategy

Version Format

  • Format: YYYY-MM-DD (e.g., 2026-01-23)
  • Meaning: The date of the last incompatible change for this version

Branch Strategy

New development happens on the main branch. We maintain long-term branches for all supported specification versions:

  1. New Version Release Process:

    • After technical committee approves a new version, create a release/YYYY-MM-DD branch from main
    • Implement code freeze immediately when creating the release branch
    • Only allow critical bug fixes during this window

  2. Critical Issue Handling: Two ways to fix critical issues:

    • Fix in release branch then merge to main
    • Fix in main then cherry-pick to release branch

  3. Version Release:

    • Once finalized, merge release branch to main and tag (e.g., git tag -a vYYYY-MM-DD)
    • GitHub Action automatically detects new tags and generates release note drafts and uploads build artifacts

  4. Long-term Maintenance:

    • Unlike temporary feature branches, release/YYYY-MM-DD branches are long-lived
    • Correspond to specific specification versions for historical reference and maintenance

Breaking Changes

PR Identification

  • Breaking change PR titles must include !
  • Example: feat(checkout)!: refactor checkout interface parameters

Advance Notice

  • Breaking changes are announced in Discussions 2 weeks before merging
  • Announcements include change details, impact scope, and migration guide

Change Examples

The following are considered breaking changes:

  • Removing or renaming fields
  • Changing required fields to optional (or vice versa)
  • Altering field data types
  • Modifying endpoint paths or HTTP methods
  • Semantic changes that break backward compatibility

Released Versions

VersionRelease DateMajor ChangesStatus
v2026-01-232026-01-23Cart capability, versioning strategyCurrent
v2026-01-112026-01-11Initial stable versionMaintenance

Upgrade Guide

Check Version 

# View UCP version
ucp --version

# Or check package.json
cat package.json | grep ucp

Upgrade Steps

  1. Read Release Notes: Check Breaking Changes for target version
  2. Update Dependencies: Update to target version
  3. Run Tests: Ensure all tests pass
  4. Adjust Code: Modify code according to breaking changes
  5. Deploy: Deploy to production

Version Compatibility

  • Minor version updates within the same major version should be backward compatible
  • When upgrading across multiple versions, upgrade one version at a time

Implementation Guide

Version Negotiation Flow 

  flowchart LR
    A[Platform sends request] --> B{Business version check}
    B -->|Platform version ≤ Business version| C[Process request]
    B -->|Platform version > Business version| D[Return version not supported error]
    C --> E[Return response + active capability list]
    D --> F[Platform downgrade or update]

Code Examples

Platform Side - Version Negotiation:

def negotiate_capability(business_profile):
    platform_version = "2026-01-23"
    business_version = business_profile["ucp"]["version"]

    # Check version compatibility
    if parse_version(platform_version) > parse_version(business_version):
        raise VersionUnsupportedError(
            f"Platform version {platform_version} not supported. "
            f"Business version: {business_version}"
        )

    # Compute capability intersection
    platform_caps = get_platform_capabilities()
    business_caps = business_profile["ucp"]["capabilities"]
    active_caps = compute_capability_intersection(
        platform_caps, business_caps
    )

    return active_caps

Business Side - Version Verification:

def handle_request(request):
    # Get platform version
    platform_version = request.headers.get("UCP-Version", "2026-01-11")
    business_version = "2026-01-23"

    # Version check
    if parse_version(platform_version) > parse_version(business_version):
        return error_response(
            code="version_unsupported",
            message=f"Version {platform_version} not supported",
            severity="requires_buyer_input"
        )

    # Get platform capabilities
    platform_profile = fetch_profile(request.profile_uri)
    active_caps = compute_capability_intersection(
        platform_profile["capabilities"],
        business_capabilities
    )

    return process_request(request, active_caps)

Migration Examples

Upgrading from v2026-01-11 to v2026-01-23:

  1. New Cart Capability:
# Old code (v2026-01-11)
checkout = create_checkout(line_items=items)

# New code (v2026-01-23)
cart = create_cart(line_items=items)
# ... user browses and modifies ...
checkout = create_checkout(cart_id=cart.id)
  1. Version Declaration Update:
{
  "ucp": {
    "version": "2026-01-23",
    "capabilities": [
      {
        "name": "dev.ucp.shopping.cart",
        "version": "2026-01-23"
      }
    ]
  }
}

FAQ

Q: How to choose the appropriate version?

A:

  • New Projects: Use the latest version
  • Production: Use stable version (currently v2026-01-23)
  • Compatibility Considerations: Refer to versions supported by platform and business

Q: What to do if versions are incompatible?

A:

  1. Check version requirements in error message
  2. Downgrade to compatible version
  3. Or wait for business/platform upgrade

Q: How to track version updates?

A:

Q: How long are release branches kept?

A:

  • Release branches are maintained long-term
  • Typically kept until at least 6 months after the next major version release
  • Critical security fixes are backported to all supported release branches

Related Links

RoadmapSpecification Overview