Lessons from moving the Go SDK out of core (preliminary migration playbook)

[rhuss]

The Go SDK now lives in ai-openshell/sdk-go: the history is imported, the module builds on its own, and #5245 deprecated sdk/go in core and dropped its CI gate. It's the first of the RFC 0019 moves (#4426), so I wrote down what we learned while it's fresh, as a checklist that the Python SDK, TypeScript SDK, packages, and windows moves can copy.

This is preliminary. Phases 0 to 2 (prerequisites, import, cutover) are done, and those parts describe what happened. Phases 3 to 5 (automation, retirement, first lockstep release) haven't run yet. They're marked Pending with the questions still open, and I'll update them as they land. Once sdk-go ships its first release, I plan to propose a cleaned-up version as rfc/0019-repository-migration/playbook.md.

Feedback I'd find most useful:

• If you're planning one of the next moves: what's missing for your component?
• If you maintain core CI or the ai-openshell org: is anything here wrong, or would you do it differently?

After the migration is completed (after release 0.1.8), I plan to also provide a skill that helps in that migration. The actual migration was done with intent-driven development, specifically by using cc-spex and speckit. I just wanted to share the result early on, so that you also can feed your agents with this data for any potential migration that will happen in parallel.

Tracking issue for the Go move: #5031.

Who this is for

Maintainers planning one of the remaining RFC 0019 moves: the Python and TypeScript SDKs, packages, windows, and later the provider repositories. Every move leaves the same core repository, so the lessons about core's PR gates apply to all of them. Placeholders: <component> (for example "Python SDK"), <subdir> (its path in core), <target> (the new ai-openshell/... repository), <surface> (the name core's prompts and scripts use for the component, for example go-sdk).

Phases

Each phase lists its entry gate and a checklist you can copy into the tracking issue. The Go move took six calendar days from the first issue to the core cutover, most of it waiting for approvals.

Phase	Gate	Outcome
0 Prerequisites	none	go-ahead, team, settings, drained PRs, freeze commit
1 Import	phase 0	history and a standalone build on <target> main
2 Cutover	phase 1, state:accepted on the core issue	core stops gating on <subdir>, open PRs ported
3 Automation	phase 1, bot App	bump proposals, E2E against releases, release tagging, drift check
4 Retirement	phase 3, final deprecated release from core	<subdir> removed from core
5 Release	phase 3, next core stable release	first lockstep release from <target>

Phase 0: Prerequisites

• File the tracking issue in core. READ contributors can't set labels; ask a maintainer for state:accepted before any core PR.
• Read the target org's rulesets (main-integrity: PR, approval, code owner, last-push approval, no force push) and your access to <target> and ai-openshell/infra (gh api repos/<org>/<repo> --jq .permissions).
• Check live team membership and repository collaborators. The owning team needs at least two members besides the person who pushes, or nothing merges without an admin.
• Write the admin request issue with the exact settings (team permissions, Pages, merge methods including merge commits, who reviews). Keep the bot App out of it; ask for the App in its own issue when phase 3 starts.
• Inventory every reference to the component in core: workflows, tasks/*.toml aggregates, CodeQL matrix and config, release workflows, Dependabot, CODEOWNERS, review prompts and their validators. Search for the path and for <surface>.
• Search the subdirectory's tests for relative paths that climb out of it and list the shared fixtures to vendor.
• Scan open core PRs by file list (not title) for changes under <subdir>. Sort them into component-only PRs, core features with hand-written component changes, and PRs that only regenerate bindings.
• Announce the freeze at least a week ahead on the tracking issue and on each affected PR. Pick a release boundary and say which side late merges land on. Ping a second time a few days before, naming who can unblock what.
• Track each drain PR on four gates: issue acceptance, the CI mirror (/ok to test <sha>), maintainer approval, and open review threads.
• Rehearse extraction, merge, and standalone build on the current tip before the freeze day.

Phase 1: Import

• Record the freeze commit and the pinned core version in the new repository (for example hack/migration/FREEZE).
• Extract with git filter-repo from a throwaway clone reduced to one branch at the freeze commit. Rewrite #N to NVIDIA/OpenShell#N. Run with GIT_CONFIG_GLOBAL=/dev/null GIT_CONFIG_SYSTEM=/dev/null.
• Verify tree hash, commit, author, and sign-off counts, and grep for bare references. Put the output in the import PR.
• Merge the history into <target> with --allow-unrelated-histories and a merge commit. Resolve the auto-init README conflict in favor of the component's README.
• Make the component standalone in a second PR: new package or module path, bindings generated from a pinned core release, self-contained task runner, vendored fixtures plus a check against the pinned source, LICENSE, CI.
• Rerun the climbing-path search on the freeze tree; PRs merged in the last days can add new shared fixtures.
• Grep docs config and README for old repository URLs and personal mirrors.
• Smoke-test as a consumer from a clean environment (install from main, build the README example).

Phase 2: Cutover and porting

• Open one core issue per core PR (the tracking issue stays open, so it can't be the closing issue) and get each accepted.
• Core PR A: deprecation notice, moved-notice README, drop the CI gate that forced changes under <subdir>, and add a required check that fails on added or modified files there. Exempt deletions and the notice files instead of relying on a label.
• Ask for exactly one area label that has a reviewer table in REVIEWERS.md, together with /ok to test. After the CI mirror runs, answer review comments without pushing and carry polish into the next PR.
• Port open PRs with format-patch --relative=<subdir> --no-signoff and git am. Rewrite renamed paths inside the patches before applying, and only in lines the port adds. Port only the top PR of a stack.
• Comment on each ported core PR with its replacement and ask the author to close it.
• After a squash merge in <target>, rebase every stacked branch right away. Verify each push with git ls-remote and read lease SHAs from it.
• Prove the approval path: a code owner other than the last pusher approves and merges a PR without an admin.

Phase 3: Automation (Pending)

• Governance PR: CODEOWNERS (check team slugs with gh api orgs/<org>/teams; every team named needs repository access), Dependabot, CodeQL, workflow linting (actionlint, zizmor, shellcheck), docs publishing, CONTRIBUTING, SECURITY, AGENTS. Follow org-wide choices (the DCO GitHub app) over copies from core.
• Run zizmor on every workflow copied from core before adopting it.
• Request the bot App with the minimum permissions the workflows use (contents, pull requests, issues, metadata). Store its client ID and private key in an environment that only main can deploy to.
• Poll core releases on a schedule instead of cross-org push triggers.
• Base the E2E lane on core's supported container deployment at the released tag, not on core's from-source test setup.
• Dry-run bump proposals, release tagging, and the drift check against a real version pair before going live.

Open questions: the first live run of the release poller and its first bot PR, the drift issue's noise level against core main, and how bot steps that need PR context (label triggers, comment commands) fit an environment restricted to main.

Phase 4: Retirement (Pending)

• Wait for a core stable release that contains PR A, so the deprecation reaches users through a tag.
• Core PR B: remove <subdir>, its tasks and toolchain, CodeQL entries, release jobs and their needs and expected-job checks, and the freeze check. Rewrite the user docs page for the new location, with examples compiled against the new package.
• Run the sync-agent-infra skill and search for <surface> as well as the path.
• Close the tracking issue with a summary.

Open questions: whether the deprecated tag shows up in the language's package index as expected, and how long the old docs page should keep the migration steps.

Phase 5: Release (Pending)

• Tag the first release from <target> with release notes that name the core version.
• Publish a "supported core versions" table in the README.
• Run every quickstart check end to end and close the migration log.

Open questions: everything about the first lockstep release; it hasn't happened yet.

Lessons by topic

Governance

• Check the target org's rulesets before assuming push access. ai-openshell applies main-integrity to every Terraform-managed repo, and only org admins can bypass.
• require_last_push_approval plus a team without a second reviewer means nothing can merge without an admin. Grow the owning team before the move.
• Prove the approval path on a real PR before the cutover.
• Ask for the smallest repository role that works. Write covers labels, workflows, tags, releases, and Pages deploys. Only Actions secrets and security settings need repository admin, and an org admin can set those once. Repository admin doesn't bypass org rulesets.
• Spell out the target settings in the request issue instead of "an infra PR follows". In the Go move the admin applied them directly from the issue text.
• Being able to clone a private infra repo doesn't mean you can push to it, and org repos may disable forking.
• Check live team membership and the repository's collaborators before drafting governance requests. Terraform history can hold changes the plan missed.
• Check team slugs before writing CODEOWNERS; display names can differ from slugs (maintainers, not openshell-maintainers).
• A CODEOWNERS rule only works for a team with access to the repository. When reviewers ask for a path owned by another team, request that team's access in the same comment.
• Follow the org's existing choices over copies from core. The org installs the DCO GitHub app on every public repo, so the new repo needs neither a DCO workflow nor a DCO file.
• Repo settings, teams, and members live in ai-openshell/infra. Plan an infra change (made by an infra team member) as step zero.
• Contributors with READ on NVIDIA/OpenShell need a state:accepted issue for every core-side PR. The tracking issue must stay open, so file one issue per core PR.

Automation identity (Pending)

• PRs opened with GITHUB_TOKEN do not trigger workflows. Bot PRs need a GitHub App token.
• Ask for the bot App only when the automation phase starts, in its own issue.
• Request the App with the minimum permissions the workflows use, and check whether any workflow edits workflow files before asking for workflows: write.
• Keep bot App secrets in an environment that only the default branch can deploy to. Repository secrets let any pushed branch mint a bot token, push as the bot, and approve its own change.
• An environment limited to the default branch rules out bot steps in PR context. Design those as separate workflows from the start.
• Polling core on a schedule avoids cross-org secrets. Use push triggers only once a cross-org App exists.
• A shell GITHUB_TOKEN overrides the gh keyring login. Check gh auth status when a push of workflow files fails with a missing workflow scope.

CI coupling

• Inventory every place core CI references the component before planning the removal.
• Search for the component's surface name as well as its paths. Review prompts and their validators can name a component without referring to its directory.
• Search the subtree's tests for relative paths that climb out of it. Shared fixtures in core break silently on extraction; vendor them and add a check against the pinned source.
• Rerun that search on the freeze tree after the rehearsal. A fixture newer than the pinned tag can't be checked against it yet.
• Run zizmor on workflows copied from core before adopting them. Suppressions in core's config hide findings a new repo doesn't need to inherit.
• Read core's E2E setup before planning the new repo's lane, and base the lane on core's supported container deployment (compose file, Helm chart) when it runs published images.

Releases (Pending)

• Directory-prefixed tags (sdk/go/vX.Y.Z) can break tooling that runs git describe (setuptools-scm in fix(ci): keep Release Dev publishing when the snap upload or a Go tag breaks it #5018). Separate repos remove that class of problem.
• Dry-run release automation against a real version pair before going live. The compare API silently truncates at 300 files, and gh api puts 404 error JSON on stdout.
• Fix the freeze to a release boundary and say which side late merges land on. In the Go move, freezing at the end of the release day put three fixes into the new repo that core's tag of the same version lacks.

History

• Most commits touching a subdirectory may be cross-cutting core work (66 of 79 for sdk/go). Filtered history keeps them, which is acceptable in exchange for blame and authorship.
• Rewrite #N references to NVIDIA/OpenShell#N during extraction, or they autolink to the new repo's issues.
• If the target repo was auto-initialized, the import needs a merge commit, so that merge method must be allowed, and README.md conflicts. Rehearse the merge along with the extraction.
• git filter-repo crashes on multi-line alias values in git config --list. Run it with GIT_CONFIG_GLOBAL=/dev/null GIT_CONFIG_SYSTEM=/dev/null.
• Reduce the extraction clone to one branch at the freeze commit before filtering.
• A verification script (tree hash, commit, author, and sign-off counts, bare references) makes the import PR reviewable from any core checkout. The whole extraction takes seconds, so rehearse it.

Deprecation (Pending)

• Retire in two core PRs: deprecate and drop the CI gate first, remove the code after the final deprecated release and once the new repo's automation is live.
• A freeze announced only by comment doesn't stop merges. Add a required check that fails on changes to the moved directory, together with dropping the gate that forced those changes.
• Let that check exempt deletions and the notice files instead of relying on an exception label; READ contributors can't create or set labels.

Porting

• Drain scans need the PR file lists, not titles. Most PRs that touch the component are core features that update bindings or wrappers alongside.
• Announce the freeze at least a week ahead and ping twice. Acceptance labels and reviews arrived only after the second, more specific ping.
• Track each drain PR on four gates: issue acceptance, CI mirror, maintainer approval, open review threads. A green check on one says nothing about the others.
• "PR Issue Acceptance" needs a closing keyword; "Part of #N" fails even when the issue is accepted.
• /ok to test is pinned to a SHA. Every push by the author needs a new one, so a PR fixed after review silently waits again.
• Review Readiness needs exactly one area label with a reviewer table in REVIEWERS.md; an existing GitHub label is not enough.
• Fork PRs hold pull_request workflows as "awaiting approval" until a maintainer clicks "Approve and run". They are not part of Required CI Gates.
• After an /ok to test lands, don't push non-blocking polish. Answer the review and carry the polish into the next PR.
• Authors often push fixes with a top-level summary instead of thread replies. A review pass on freeze day that maps each thread to fixed or deferred saves approvers from reconstructing it.
• Port with format-patch --relative=<subdir> plus git am, and rewrite renamed paths inside the patches before applying.
• Pass --no-signoff to format-patch; a porter's format.signoff=true adds their sign-off to every contributor's commit.
• Never rewrite old paths across the whole tree after a port. The new repo mentions them on purpose in migration notes.
• A 3-way am resolution with --theirs still has old paths. Rewrite the resolved lines before git am --continue.
• Check for stacked PRs and port only the top one.
• A squash merge of a stacked PR leaves its original commits on every branch above it. Rebase the stack right after the merge.
• Verify pushes with git ls-remote, not the push output, and read lease SHAs from it too.

Docs

• Grep docs config and README for the old repository and for personal mirrors. They survive the path rewrite because they don't contain the path.
• Compile and vet the user docs' examples against the new package before the removal PR, and keep the migration steps on core's docs page for a release.
• Carry docs notes from ported PRs into the new repo's guides as their own commit.