Skip to content

docs: simplify the SDK release flow #386

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
sjmiller609 wants to merge 2 commits into
base: main
Choose a base branch
from
+13 −11
Open

docs: simplify the SDK release flow #386

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
78da671
docs: simplify the SDK release flow
sjmiller609 Aug 10, 2026
88d4381
Document SDK promotion recovery PRs
sjmiller609 Aug 10, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 3 additions & 3 deletions .github/workflows/stlc-generate.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,9 +9,9 @@
# each SDK repo and opens a do-not-merge draft PR per repo — never main, no
# seal-back, no docs publish. See the runbook.
# On push to main: rebuilds and pushes to each staging repo's main. The staging
# promotion workflow fast-forwards production main, where release-please opens
# the version + changelog PR. Merging that PR publishes the package, and
# production releases fast-forward back into staging.
# promotion workflow advances the public SDK's `next` branch, and release
# automation opens or updates one versioned PR from `next` to `main`. Merging
# that PR publishes the package, and production releases sync back to staging.
#
# Operator commands and recovery notes are in docs/runbooks/sdk-generation-stlc.md.
name: Generate SDKs with stlc
Expand Down
18 changes: 10 additions & 8 deletions docs/runbooks/sdk-generation-stlc.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,18 +9,20 @@ Hypeman's Go and TypeScript SDKs are generated by
internal SDK staging repositories and posts one build-manifest comment.
2. Merging the config PR validates the integrated SDKs and pushes staging
`main` only after bootstrap, lint, tests, and clean-worktree checks pass.
3. Each staging repo opens or updates one `stainless/release` PR against its
public production repo. Merge it with a merge commit; never squash or rebase.
4. Release-please opens the version and changelog PR in production. Merging it
publishes the package.
3. Each staging repo advances its public production repo's `next` branch.
4. Release automation opens or updates one versioned PR from `next` to `main`.
New SDK changes accumulate in that PR until it is merged. Merge it with a
merge commit to publish the package; the next SDK change opens a new PR.
If promotion finds a Git conflict, it opens a draft recovery PR against
`next`; resolve and merge it, then rerun the staging promotion workflow.
5. The scheduled sync fast-forwards production commits back into staging.

## Normal API changes

Update `openapi.yaml` and `stainless.yaml`, then open a PR. Review the generated
preview branches and manifest diagnostics before merging. The public SDK
promotion PRs are created or updated automatically; publishing requires merging
them with merge commits, then merging the release-please PRs.
preview branches and manifest diagnostics before merging. Each public SDK gets
one versioned release PR; publishing requires merging that PR with a merge
commit.

Every merged SDK-affecting PR becomes a releasable SDK commit automatically.
Explicit `feat:`, `fix:`, `perf:`, and `revert:` titles are preserved; other
Expand Down Expand Up @@ -70,5 +72,5 @@ rerun full SDK validation.
## Final hosted cutover

Remove hosted-only secrets and uninstall the Stainless GitHub App only after a
complete preview → staging → promotion → release-please → publish → back-sync
complete preview → staging → `next` → release PR → publish → back-sync
round trip succeeds for both SDKs.
Loading