Conversation
Record how to validate an api-client-go bump and an LD-API-Version pin, including the second HTTP client and generated commands whose beta flag is not in the OpenAPI tag. Co-authored-by: Ramon Niebla <nieblara@users.noreply.github.com>
Replace PR-specific history, hard-coded version facts, and command lists with lookups that stay correct: a spec query for beta-only operations, searches for each client's callers, and the client's own default header. Co-authored-by: Ramon Niebla <nieblara@users.noreply.github.com>
nieblara
marked this pull request as ready for review
September 30, 2026 02:31
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
2 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.
Requirements
This is documentation. The platform checkbox stays open because the playbook does not change runtime behavior.
Related issues
REL-16083 and #832, the api-client-go v24 /
LD-API-Version: 20240415upgrade this playbook came out of.Describe the solution you've provided
Adds
docs/playbooks/rest-api-version-upgrades.mdand a pointer inCONTRIBUTING.md.The playbook is the checklist for any future
api-client-gobump orLD-API-Versionchange. It avoids facts that go stale after one upgrade. Instead of listing commands, versions, or known-bad operations, it gives the lookups that produce them:rgsearches for callers of the typed client and the resources client.LD-API-Versiona givenapi-client-gomajor sends by default.jqquery overld-openapi.jsonfor operations that requirebetabut lack a(beta)tag, so the generator setsIsBeta: falsefor them.It also covers the patch-body regression, which tests have to fail if the pin is wrong, and the live checks
go testdoes not perform.Each command in the playbook was run on
mainand on the PR 832 head (5af62e9). The spec query returns the five agent-graph operations on both, which is the open issue in PR 832.Describe alternatives you've considered
Keeping the checklist only in the PR 832 description. A playbook in the repo is what the next upgrade can follow without re-deriving the two-client layout.
Additional context
No live API calls were made.
Note
Overview
Adds contributor guidance for
api-client-gobumps andLD-API-Versionchanges, which unit tests alone do not fully validate.CONTRIBUTING.mdnow links to a new playbook and states that PRs touching the client or version header should follow it before marking validation complete.docs/playbooks/rest-api-version-upgrades.mddocuments a repeatable process: the typed client (internal/client.New) vs resources client (MakeRequest/ generated commands), pre-edit lookups (rg,jqonld-openapi.jsonfor beta-only operations), a code checklist, required unit tests (headers, generatorIsBeta, PATCH"value": false), and manual live checks (login, list/get commands, dev-server sync). It also lists what to document in the PR (target version, breaking model changes, older-token behavior).Reviewed by Cursor Bugbot for commit e2817df. Bugbot is set up for automated code reviews on this repo. Configure here.