Skip to content

docs: fix checkout status lifecycle diagram to match spec prose - #672

Open
SumuduLansakara wants to merge 1 commit into
Universal-Commerce-Protocol:mainfrom
SumuduLansakara:main-fork
Open

docs: fix checkout status lifecycle diagram to match spec prose#672
SumuduLansakara wants to merge 1 commit into
Universal-Commerce-Protocol:mainfrom
SumuduLansakara:main-fork

Conversation

@SumuduLansakara

Copy link
Copy Markdown

Description

The Checkout Status Lifecycle diagram only showed a one-way path from
ready_for_complete into complete_in_progress, with no way back to
incomplete and no path to requires_escalation. The normative prose
elsewhere in this file describes both:

  • Complete Checkout's response section states that any other status
    retains its core status lifecycle semantics, explicitly naming
    incomplete ("for a recoverable change") and requires_escalation
    ("for Buyer handoff") as valid outcomes alongside completed and
    complete_in_progress.
  • ready_for_complete can regress to incomplete via Update Checkout
    as well (business rules can reintroduce a missing requirement).

Update the diagram to show:

  • ready_for_complete -> requires_escalation, labeled with the
    Complete Checkout escalation path.
  • ready_for_complete <-> incomplete as two directional arrows: the
    existing "all info collected" transition down, and a new "Update
    Checkout, or Complete Checkout (recoverable)" transition back up.

Add a note documenting the two transitions still omitted from the
diagram for readability (complete_in_progress resolving via Buyer
handoff or via the cancellation race described in Accepted
completion), so the diagram's simplifications are explicit rather
than silent.

No normative or schema changes; documentation only.

Category (Required)

  • Core Protocol: Changes to the base communication layer, global context, or breaking refactors. (Requires Technical Council approval)
  • Governance/Contributing: Updates to GOVERNANCE.md, CONTRIBUTING.md, or CODEOWNERS. (Requires Governance Council approval)
  • Capability: New schemas (Discovery, Cart, etc.) or extensions. (Requires Maintainer approval)
  • Documentation: Updates to README, or documentations regarding schema or capabilities. (Requires Maintainer approval)
  • Infrastructure: CI/CD, Linters, or build scripts. (Requires DevOps Maintainer approval)
  • Maintenance: Version bumps, lockfile updates, or minor bug fixes. (Requires DevOps Maintainer approval)
  • SDK: Language-specific SDK updates and releases. (Requires DevOps Maintainer approval)
  • Samples / Conformance: Maintaining samples and the conformance suite. (Requires Maintainer approval)
  • UCP Schema: Changes to the ucp-schema tool (resolver, linter, validator). (Requires Maintainer approval)
  • Community Health (.github): Updates to templates, workflows, or org-level configs. (Requires DevOps Maintainer approval)

Related Issues

None filed — found while reading the spec, opening directly as a docs fix.

Checklist

  • I have followed the Contributing Guide (including Conventional Commits title requirements and ! for breaking changes).
  • I have updated the documentation (if applicable).
  • My changes pass all local linting and formatting checks.
  • I have added tests that prove my fix is effective or that my feature works.
  • New and existing unit tests pass locally with my changes.
  • (For Core/Capability) I have included/updated the relevant JSON schemas.
  • I have regenerated Python Pydantic models by running generate_models.sh under python_sdk.

Screenshots / Logs (if applicable)

Before:

       +------------+                         +---------------------+
       | incomplete |<----------------------->| requires_escalation |
       +-----+------+                         |   (buyer handoff    |
             |                                |  via continue_url)  |
             | all info collected             +----------+----------+
             v                                           |
    +------------------+                                 |
    |ready_for_complete|                                 |

After: see the updated diagram in docs/specification/checkout.md.

@google-cla

google-cla Bot commented Aug 1, 2026

Copy link
Copy Markdown

Thanks for your pull request! It looks like this may be your first contribution to a Google open source project. Before we can look at your pull request, you'll need to sign a Contributor License Agreement (CLA).

View this failed invocation of the CLA check for more information.

For the most up to date status, view the checks section at the bottom of the pull request.

@damaz91 damaz91 added the status:needs-triage Signal that the PR is ready for human triage label Aug 1, 2026
The Checkout Status Lifecycle diagram only showed a one-way path from
ready_for_complete into complete_in_progress, with no way back to
incomplete and no path to requires_escalation. The normative prose
elsewhere in this file describes both:

- Complete Checkout's response section states that any other status
  retains its core status lifecycle semantics, explicitly naming
  incomplete (for a recoverable change) and requires_escalation (for
  Buyer handoff) as valid outcomes alongside completed and
  complete_in_progress.
- ready_for_complete can regress to incomplete via Update Checkout as
  well (business rules can reintroduce a missing requirement).

Update the diagram to show:

- ready_for_complete -> requires_escalation, labeled with the Complete
  Checkout escalation path.
- ready_for_complete <-> incomplete as two directional arrows: the
  existing all info collected transition down, and a new Update
  Checkout, or Complete Checkout (recoverable) transition back up.

Add a note documenting the two transitions still omitted from the
diagram for readability (complete_in_progress resolving via Buyer
handoff or via the cancellation race described in Accepted
completion), so the diagram's simplifications are explicit rather
than silent.

No normative or schema changes; documentation only.
@damaz91 damaz91 added bug Something isn't working documentation Improvements or additions to documentation status:under-review and removed status:needs-triage Signal that the PR is ready for human triage labels Aug 3, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

bug Something isn't working documentation Improvements or additions to documentation status:under-review

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants