Skip to content

The version-pin guard reads manifests only, so a version written in prose can still go stale #108

Description

@macanderson

Problem

.github/scripts/check-sdk-version-pins.py (added in #98 / PR #106) compares
versions between manifests. A version written in prose is invisible to it,
and two are already stale.

sdk/PUBLISHING.md, in the "After publishing" section:

  • Line ~213 names go get .../sdk/go/contextgraph@v0.1.0 as part of the
    acceptance bar to re-run. The Go SDK's only tag is sdk/go/v0.1.0, so that
    command is not wrong today — but it is pinned prose beside two sibling
    commands that are unpinned (npm install @contextgraphprotocol/typescript-sdk,
    pip install contextgraph-sdk), and the repo is on 2.0.0. A reader cannot
    tell whether v0.1.0 is deliberate or left behind.
  • Line ~15 says Python is "✅ published 0.1.0 (2026-07-31)". sdk/python/pyproject.toml
    ships 2.0.0. Whether that line is a historical record of the first publish
    or a status field that should track the current version is exactly the
    ambiguity worth removing.

The Go SDK also has no in-tree package version at all — a Go module is
versioned by its git tag, so sdk/go/go.mod has nothing for a guard to read.
That is recorded as out of scope in
docs/adr/0012-sdk-version-pins-share-a-major.md, and it means the Go SDK is
the one SDK whose published version can drift from the repo with nothing at all
watching.

How to reproduce

rg -n 'v0\.1\.0|published 0\.1\.0' sdk/PUBLISHING.md
python3 .github/scripts/check-sdk-version-pins.py   # green: it reads no prose
git tag -l 'sdk/go/*'

What done looks like

  1. sdk/PUBLISHING.md's status table and acceptance-bar commands either state
    the current versions or say plainly that they are a historical record of the
    first publish. Pick one convention and apply it to all three rows.
  2. A decision, written in the ADR or a comment, on whether the Go SDK's tag
    should be checked against Cargo.toml's [workspace.package] version
    the "SDKs move in lockstep with the crates" rule in MIGRATION.md §5.4
    names the SDKs without excluding Go. If yes, the check reads git tag -l 'sdk/go/v*', which means it can only run where tags are fetched
    (fetch-depth: 0 or an explicit git fetch --tags).
  3. Optionally, extend check-sdk-version-pins.py to install commands in
    markdown — npm install <pkg>@<version>, pip install <pkg>==<version>,
    go get <module>@<version> — resolving each against the manifest that owns
    the package. Historical records need an exemption list, the way
    check-deploy-hygiene.py exempts docs/adr/ and CHANGELOG.md.

Constraints

Found while adding the version-pin guard in #98 / PR #106.

Metadata

Metadata

Assignees

No one assigned

    Labels

    P2Next cycle

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions