@workerstack/clients 1.0.0-rc.30 → 1.0.0-rc.31
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +175 -21
- package/bin/clients.js +5 -6
- package/bin/installgen.js +5 -9
- package/dist/cli.js +3 -1
- package/dist/emit/csharp/sdk-method.d.ts +18 -1
- package/dist/emit/csharp/sdk-method.js +14 -3
- package/dist/emit/csharp/sdk.js +4 -1
- package/dist/emit/go/sdk-method.d.ts +9 -0
- package/dist/emit/go/sdk-method.js +10 -1
- package/dist/emit/go/sdk.js +4 -3
- package/dist/emit/java/sdk-client.js +1 -0
- package/dist/emit/java/sdk-op.d.ts +6 -1
- package/dist/emit/java/sdk-op.js +15 -3
- package/dist/emit/java/sdk.js +7 -1
- package/dist/emit/python/sdk-method.d.ts +11 -0
- package/dist/emit/python/sdk-method.js +15 -0
- package/dist/emit/python/sdk.js +5 -1
- package/dist/emit/rust/sdk-method.d.ts +12 -1
- package/dist/emit/rust/sdk-method.js +10 -2
- package/dist/emit/rust/sdk.js +4 -1
- package/dist/emit/ts/http.d.ts +8 -0
- package/dist/emit/ts/http.js +48 -3
- package/dist/emit/ts/package.js +1 -0
- package/dist/emit/ts/sdk-types-preamble.js +10 -2
- package/dist/emit/ts/sdk-types.d.ts +0 -5
- package/dist/emit/ts/sdk-types.js +52 -8
- package/dist/emit/ts/sdk.d.ts +3 -1
- package/dist/emit/ts/sdk.js +40 -8
- package/dist/emit/ts/service-map.d.ts +5 -0
- package/dist/emit/ts/service-map.js +10 -1
- package/dist/emit/ts/single-flight-text.d.ts +3 -0
- package/dist/emit/ts/single-flight-text.js +38 -0
- package/dist/emit/ts/tanstack-query.d.ts +3 -2
- package/dist/emit/ts/tanstack-query.js +54 -29
- package/dist/gen/process.js +2 -1
- package/dist/gen/switch-on.constants.d.ts +2 -0
- package/dist/gen/switch-on.constants.js +2 -0
- package/dist/gen/targets.d.ts +4 -3
- package/dist/gen/targets.js +4 -3
- package/dist/ir/invalidate-reads.d.ts +17 -0
- package/dist/ir/invalidate-reads.js +104 -0
- package/dist/ir/load.d.ts +10 -0
- package/dist/ir/load.js +62 -14
- package/dist/ir/read-method.constants.d.ts +2 -0
- package/dist/ir/read-method.constants.js +2 -0
- package/dist/release/load.js +1 -1
- package/dist/runtime/csharp/Config.cs +9 -1
- package/dist/runtime/csharp/Exchange.cs +56 -4
- package/dist/runtime/csharp/Hooks.cs +9 -0
- package/dist/runtime/csharp/Operation.cs +6 -1
- package/dist/runtime/csharp/WsDial.cs +3 -1
- package/dist/runtime/go/config.go +5 -0
- package/dist/runtime/go/hooks.go +70 -0
- package/dist/runtime/go/request.go +6 -2
- package/dist/runtime/go/stream.go +4 -1
- package/dist/runtime/go/ws.go +3 -1
- package/dist/runtime/java/ClientConfig.java +11 -0
- package/dist/runtime/java/Flight.java +2 -12
- package/dist/runtime/java/Hooks.java +45 -0
- package/dist/runtime/java/InvalidateEvent.java +10 -0
- package/dist/runtime/java/InvalidateHook.java +12 -0
- package/dist/runtime/java/InvalidateTarget.java +7 -0
- package/dist/runtime/java/Operation.java +23 -3
- package/dist/runtime/java/Realtime.java +3 -1
- package/dist/runtime/java/WsDial.java +3 -0
- package/dist/runtime/python/config.py +8 -2
- package/dist/runtime/python/exchange.py +3 -1
- package/dist/runtime/python/hooks.py +110 -5
- package/dist/runtime/python/operation.py +2 -0
- package/dist/runtime/python/send_async.py +14 -2
- package/dist/runtime/python/send_sync.py +4 -2
- package/dist/runtime/python/ws.py +5 -1
- package/dist/runtime/rust/config.rs +6 -1
- package/dist/runtime/rust/exchange.rs +15 -3
- package/dist/runtime/rust/hooks.rs +127 -2
- package/dist/runtime/rust/log.rs +11 -3
- package/dist/runtime/rust/request.rs +17 -0
- package/dist/runtime/rust/ws.rs +9 -1
- package/dist/runtime/ts/config.ts +69 -0
- package/dist/runtime/ts/http.ts +12 -10
- package/dist/runtime/ts/request.ts +2 -0
- package/dist/runtime/ts/response.ts +7 -0
- package/dist/runtime/ts/sdk-invalidate.ts +82 -0
- package/dist/runtime/ts/sdk-single-flight.constants.ts +25 -0
- package/dist/runtime/ts/sdk-single-flight.ts +203 -0
- package/dist/runtime/ts/sdk-sse.ts +5 -1
- package/dist/runtime/ts/sdk-ws.ts +9 -3
- package/dist/runtime/ts/sdk.ts +55 -31
- package/dist/runtime/ts/single-flight-batch.ts +184 -0
- package/dist/runtime/ts/single-flight-body.ts +59 -0
- package/dist/runtime/ts/single-flight-run.ts +160 -0
- package/dist/runtime/ts/single-flight.constants.ts +31 -0
- package/dist/runtime/ts/single-flight.ts +158 -0
- package/dist/runtime/ts-tanstack-query/invalidate.ts +96 -92
- package/dist/runtime/ts-tanstack-query/query.ts +140 -168
- package/package.json +10 -18
- package/references/INDEX.md +31 -0
- package/references/cli.md +33 -0
- package/references/configuring.md +29 -0
- package/references/documentation.md +15 -0
- package/references/errors.md +23 -0
- package/references/flags.md +104 -0
- package/references/gates.md +46 -0
- package/references/generate.md +29 -0
- package/references/install-scripts.md +28 -0
- package/references/install.md +38 -0
- package/references/license.md +8 -0
- package/references/mcp.md +76 -0
- package/references/output.md +45 -0
- package/references/overview.md +14 -0
- package/references/release-tooling.md +34 -0
- package/references/release.md +305 -0
- package/references/sdks.md +393 -0
- package/references/start.md +22 -0
- package/references/tdd.md +16 -0
|
@@ -0,0 +1,305 @@
|
|
|
1
|
+
---
|
|
2
|
+
description: Release public packages
|
|
3
|
+
order: 145
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Releasing a product's public packages
|
|
7
|
+
|
|
8
|
+
`@workerstack/clients` releases a product's public packages from the private repo that generates them. One
|
|
9
|
+
`release.config.ts` lists the packages. `clients release bump` cuts each package's next version from what
|
|
10
|
+
changed. `clients release sync` mirrors each package into its own public repo and pushes the `v<version>` tag.
|
|
11
|
+
Each public repo's `release.yml` then publishes on that tag through OIDC, with no registry token stored anywhere.
|
|
12
|
+
Three reusable workflows in `workerstack/clients` run these steps in CI, so a consumer repo only writes short callers.
|
|
13
|
+
|
|
14
|
+
## Contents
|
|
15
|
+
|
|
16
|
+
- [Consumer prerequisites](#consumer-prerequisites)
|
|
17
|
+
- [release.config.ts](#releaseconfigts)
|
|
18
|
+
- [New product checklist](#new-product-checklist)
|
|
19
|
+
- [The reusable workflows](#the-reusable-workflows)
|
|
20
|
+
- [CLI](#cli)
|
|
21
|
+
- [Versioning](#versioning)
|
|
22
|
+
- [Tags](#tags)
|
|
23
|
+
- [Deployed spec gate](#deployed-spec-gate)
|
|
24
|
+
- [Channels](#channels)
|
|
25
|
+
- [Secrets](#secrets)
|
|
26
|
+
|
|
27
|
+
## Consumer prerequisites
|
|
28
|
+
|
|
29
|
+
- `@workerstack/clients` in the repo's dependencies. The `workflows-v1` workflows need 1.0.0-rc.25 or later, the first
|
|
30
|
+
version with `release codegen` and `release toolchains`. The workflows run the consumer's own installed copy and pin
|
|
31
|
+
none.
|
|
32
|
+
- `@workerstack/system` in the repo's dependencies, and a `system.config.ts` at the repo root that declares every name
|
|
33
|
+
the release config lists in `toolchains`, each at the version codegen needs:
|
|
34
|
+
|
|
35
|
+
```ts
|
|
36
|
+
import { defineConfig } from "@workerstack/system"
|
|
37
|
+
|
|
38
|
+
export default defineConfig({ deps: { go: "1.27.2", rust: "1.99.1", uv: "0.13.1", ruff: "0.17.1" } })
|
|
39
|
+
```
|
|
40
|
+
|
|
41
|
+
- `packageManager: "bun@<version>"` in the root `package.json` (the workflows read Bun's version from it) and a
|
|
42
|
+
committed `bun.lock` (they run `bun install --frozen-lockfile`, with the repo's scripts on).
|
|
43
|
+
|
|
44
|
+
## release.config.ts
|
|
45
|
+
|
|
46
|
+
A product's config sits in its own directory. Each package's source dir is a sibling named after the package, and
|
|
47
|
+
every other non-hidden directory there is an error. A package's public repo is `github.com/<repo>`.
|
|
48
|
+
|
|
49
|
+
```ts
|
|
50
|
+
import { defineRelease } from "@workerstack/clients/release"
|
|
51
|
+
|
|
52
|
+
export default defineRelease({
|
|
53
|
+
project: "<product>",
|
|
54
|
+
/* regenerates every package from the repo root; bump runs it, and it must honor RELEASE_VERSIONS */
|
|
55
|
+
codegen: ["bun", "scripts/codegen.ts"],
|
|
56
|
+
/* the system.config.ts deps codegen needs, installed in this order before it runs */
|
|
57
|
+
toolchains: ["go", "rust", "uv", "ruff"],
|
|
58
|
+
homepage: "https://<domain>",
|
|
59
|
+
metadata: { license: "MIT", authors: ["<Name> <oss@<domain>>"] },
|
|
60
|
+
packages: [
|
|
61
|
+
{
|
|
62
|
+
name: "cli",
|
|
63
|
+
repo: "<org>/cli",
|
|
64
|
+
description: "<one line: the repo's, every registry's, and the first CHANGELOG entry>",
|
|
65
|
+
topics: ["<product>", "cli"],
|
|
66
|
+
commitMessage: "chore: generate from openapi spec",
|
|
67
|
+
clients: {
|
|
68
|
+
target: "cli",
|
|
69
|
+
options: { binaryName: "<bin>", modulePath: "github.com/<org>/cli", repo: "<org>/cli" },
|
|
70
|
+
},
|
|
71
|
+
},
|
|
72
|
+
{
|
|
73
|
+
name: "sdk-typescript",
|
|
74
|
+
repo: "<org>/sdk-typescript",
|
|
75
|
+
description: "<one line>",
|
|
76
|
+
topics: ["<product>", "sdk"],
|
|
77
|
+
commitMessage: "chore: generate from openapi spec",
|
|
78
|
+
clients: { target: "ts" },
|
|
79
|
+
registries: [{ kind: "npm" }, { kind: "jsr" }],
|
|
80
|
+
},
|
|
81
|
+
],
|
|
82
|
+
spec: {
|
|
83
|
+
committedPath: "api/openapi.public.json",
|
|
84
|
+
deployedUrl: "https://api.<domain>/openapi.json",
|
|
85
|
+
},
|
|
86
|
+
})
|
|
87
|
+
```
|
|
88
|
+
|
|
89
|
+
| Field | Meaning |
|
|
90
|
+
| ----------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
91
|
+
| `project` | The product's slug: each package's `<project>/<name>` key, and what codegen filters on |
|
|
92
|
+
| `codegen` | The argv that regenerates every package, run from the repo root. Bump runs it again with `RELEASE_VERSIONS` (JSON, package name to version) set |
|
|
93
|
+
| `toolchains` | Optional, none by default. The `system.config.ts` dep names codegen needs; the workflows install them in this order |
|
|
94
|
+
| `committer` | Optional. The identity sync commits as (`public-sync[bot]` by default); a GitHub App's bot address works |
|
|
95
|
+
| `homepage` | https. Every public repo's website and every registry's homepage |
|
|
96
|
+
| `metadata` | Optional. Package metadata every generated package carries (authors, license, keywords and the rest); a package's own `metadata` wins over it |
|
|
97
|
+
| `packages[].clients` | How clients generates the package: its target and that target's options. Absent for a hand-kept package (one that publishes the spec itself) |
|
|
98
|
+
| `packages[].registries` | Where the public repo's rendered `release.yml` publishes: `npm`, `jsr`, `pypi`, `crates`, `go`, `nuget`, `maven`, or `github` with `assets` |
|
|
99
|
+
| `packages[].branch` | The public repo's branch sync pushes to, `main` by default |
|
|
100
|
+
| `packages[].bootstrapExclude` | Globs the first push leaves out, so the next sync adds them as their own commit |
|
|
101
|
+
| `spec` | The committed spec codegen builds from (repo-relative), and the URL prod serves it at (the deployed spec gate) |
|
|
102
|
+
|
|
103
|
+
## New product checklist
|
|
104
|
+
|
|
105
|
+
1. Create or pick the GitHub org for the public repos, and an empty public repo `<org>/<package>` for each package.
|
|
106
|
+
Sync pushes their content; nobody commits there by hand.
|
|
107
|
+
2. Register the account-backed channels the packages need. Every registry that supports it publishes through a
|
|
108
|
+
trusted publisher for repo `<org>/<package>`, workflow `release.yml`:
|
|
109
|
+
- JSR: create `@<scope>` and link the package to its repo.
|
|
110
|
+
- npm: npm adds a trusted publisher only to a package that exists, so publish it once by hand with a short-lived
|
|
111
|
+
granular token, add the trusted publisher, then revoke the token.
|
|
112
|
+
- PyPI: add a pending trusted publisher (it works before the first upload).
|
|
113
|
+
- crates.io: publish once with `cargo publish` and a short-lived token, then add the trusted publisher.
|
|
114
|
+
- NuGet: add a trusted-publishing policy for the repo and workflow, and set the repo variable `NUGET_USER` to the
|
|
115
|
+
nuget.org user that owns it.
|
|
116
|
+
- Maven Central has no OIDC: verify the namespace, generate a Portal user token, create a GPG key whose public half
|
|
117
|
+
is on `keys.openpgp.org`, and add the four `MAVEN_*` secrets to the SDK's repo (see [Secrets](#secrets)).
|
|
118
|
+
- Go: nothing to register; the workflow's `proxy.golang.org` fetch indexes the tag.
|
|
119
|
+
- A CLI's channels are clients `cli` options, each optional: a Homebrew tap repo, a Scoop bucket repo, a
|
|
120
|
+
`microsoft/winget-pkgs` fork, an AUR account with an SSH key. Each one's token goes in the CLI's repo.
|
|
121
|
+
3. Create a GitHub App with `contents: write`, `workflows: write` (sync pushes each repo's `release.yml`) and
|
|
122
|
+
`administration: write` (sync sets each repo's description, homepage and topics), install it on the org's public repos, and store its ID and private key as two Actions secrets in the private repo.
|
|
123
|
+
4. Write `release.config.ts` with a dir per package, add the prerequisites above, and check the config:
|
|
124
|
+
`clients release sync --config <path> --validate-only`. A CLI also needs a hand `README.md` and `LICENSE`;
|
|
125
|
+
clients writes its `.goreleaser.yaml` and `.github/workflows/release.yml`.
|
|
126
|
+
5. Publishing needs no workflow edits: every public tree carries a `release.yml` (the CLI's from clients, the rest
|
|
127
|
+
rendered from `registries`). Before the first real tag, run a repo's `release.yml` by hand with `workflow_dispatch`
|
|
128
|
+
to see each registry accept it. A repo whose version is already live must get that tag pushed by hand before its
|
|
129
|
+
first `release.yml` lands, or sync tags and republishes it.
|
|
130
|
+
6. First release: commit the spec (bump records the commit a release is cut from), run the bump caller (or
|
|
131
|
+
`clients release bump --config <path>` locally), and merge the release PR. Each package releases 1.0.0 with
|
|
132
|
+
its `description` as the entry. The next sync tags each package.
|
|
133
|
+
7. Verify: each public repo's `release` run is green (`gh run list -R <org>/<package> -w release`), its GitHub release
|
|
134
|
+
has its assets, each registry serves the new version, and a CLI's tap, bucket, winget PR and AUR package show it.
|
|
135
|
+
|
|
136
|
+
## The reusable workflows
|
|
137
|
+
|
|
138
|
+
A consumer calls each one from its own workflow, pinned to the `workflows-v1` tag. The caller owns the triggers,
|
|
139
|
+
the `concurrency` group and the permissions it grants. A reusable workflow's job never gets more than its caller
|
|
140
|
+
grants, and secrets pass only through the declared `secrets:`, never `secrets: inherit` across owners. Every job runs
|
|
141
|
+
the same set-up: checkout, Node 24 (the release config loads as TypeScript), Bun from `packageManager`,
|
|
142
|
+
`bun install --frozen-lockfile`, each `toolchains` name through `system install <name> --upgrade` at its
|
|
143
|
+
`system.config.ts` pin with those tools first on PATH, then `release codegen`.
|
|
144
|
+
|
|
145
|
+
Each workflow also takes `cli`, the command that runs clients, split on spaces. It defaults to
|
|
146
|
+
`bun x --no-install clients`, the bin a consumer's `@workerstack/clients` install links. A consumer leaves it
|
|
147
|
+
unset. This repo's own release fixture passes `node bin/clients.js`, because bun never links a root package's
|
|
148
|
+
own bin.
|
|
149
|
+
|
|
150
|
+
```yaml
|
|
151
|
+
# .github/workflows/release-sync.yml
|
|
152
|
+
on:
|
|
153
|
+
push:
|
|
154
|
+
branches: [main]
|
|
155
|
+
paths: ["<product>-release/**", "api/**"]
|
|
156
|
+
schedule: [{ cron: "0 3 * * *" }]
|
|
157
|
+
workflow_dispatch:
|
|
158
|
+
inputs:
|
|
159
|
+
dry-run: { type: boolean, default: false }
|
|
160
|
+
only: { type: string, required: false }
|
|
161
|
+
concurrency: { group: release-sync, cancel-in-progress: false }
|
|
162
|
+
permissions: { contents: read }
|
|
163
|
+
jobs:
|
|
164
|
+
sync:
|
|
165
|
+
uses: workerstack/clients/.github/workflows/release-sync.yml@workflows-v1
|
|
166
|
+
with:
|
|
167
|
+
config: <product>-release/release.config.ts
|
|
168
|
+
app-owner: <org>
|
|
169
|
+
dry-run: ${{ inputs.dry-run == true }}
|
|
170
|
+
only: ${{ inputs.only }}
|
|
171
|
+
secrets:
|
|
172
|
+
app-id: ${{ secrets.RELEASE_APP_ID }}
|
|
173
|
+
app-private-key: ${{ secrets.RELEASE_APP_PRIVATE_KEY }}
|
|
174
|
+
```
|
|
175
|
+
|
|
176
|
+
| `release-sync.yml` | Meaning |
|
|
177
|
+
| --------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
|
|
178
|
+
| `config` | Required. The release config, repo-relative |
|
|
179
|
+
| `app-owner` | The App installation's owner (the public repos' org); blank means the caller repo's owner |
|
|
180
|
+
| `dry-run` | Stage each tree and report what would be pushed and tagged, pushing nothing |
|
|
181
|
+
| `only` | Comma-separated package names (`name` or `project/name`); blank means every package |
|
|
182
|
+
| `app-id`, `app-private-key` | Secrets, optional. Without both, the token step is skipped and only a dry run works (sync says `GH_TOKEN env is required`) |
|
|
183
|
+
|
|
184
|
+
```yaml
|
|
185
|
+
# .github/workflows/release-bump.yml
|
|
186
|
+
on:
|
|
187
|
+
workflow_dispatch:
|
|
188
|
+
inputs:
|
|
189
|
+
major: { type: boolean, default: false }
|
|
190
|
+
permissions: { contents: write, pull-requests: write }
|
|
191
|
+
jobs:
|
|
192
|
+
bump:
|
|
193
|
+
uses: workerstack/clients/.github/workflows/release-bump.yml@workflows-v1
|
|
194
|
+
with:
|
|
195
|
+
config: <product>-release/release.config.ts
|
|
196
|
+
major: ${{ inputs.major == true }}
|
|
197
|
+
```
|
|
198
|
+
|
|
199
|
+
`release-bump.yml` takes `config` (required) and `major` (release every changed package as a major). It also installs
|
|
200
|
+
`go` when `toolchains` does not list it, because bump runs oasdiff through `go run`. When a package changed, it opens
|
|
201
|
+
or updates the release PR on branch `auto/release-bump` with exactly the paths bump printed as `wrote:`. That PR is
|
|
202
|
+
opened with the caller's `GITHUB_TOKEN`, so it starts no workflows of its own: run the validate caller by hand, or
|
|
203
|
+
review the PR's diff.
|
|
204
|
+
|
|
205
|
+
```yaml
|
|
206
|
+
# .github/workflows/release-validate.yml
|
|
207
|
+
on:
|
|
208
|
+
pull_request:
|
|
209
|
+
paths: ["<product>-release/**"]
|
|
210
|
+
permissions: { contents: read }
|
|
211
|
+
jobs:
|
|
212
|
+
validate:
|
|
213
|
+
uses: workerstack/clients/.github/workflows/release-validate.yml@workflows-v1
|
|
214
|
+
with:
|
|
215
|
+
config: <product>-release/release.config.ts
|
|
216
|
+
```
|
|
217
|
+
|
|
218
|
+
`release-validate.yml` takes `config` and runs the set-up, codegen, then `release sync --validate-only`.
|
|
219
|
+
|
|
220
|
+
A dry run proves the whole path short of the push: the toolchains install, codegen runs, every package's tree is
|
|
221
|
+
staged against its public repo's current tip, its `release.yml` is rendered, and the report says which packages would
|
|
222
|
+
be pushed and which `v<version>` tags would be created. It leaves out the push, the tag and the repo settings step.
|
|
223
|
+
|
|
224
|
+
## CLI
|
|
225
|
+
|
|
226
|
+
```
|
|
227
|
+
clients release bump --config <path> [--major]
|
|
228
|
+
clients release sync --config <path> [--only <names>] [--dry-run] [--validate-only]
|
|
229
|
+
clients release bootstrap --config <path> (--all | --only <names>) [--force-bootstrap]
|
|
230
|
+
clients release codegen --config <path>
|
|
231
|
+
clients release toolchains --config <path>
|
|
232
|
+
```
|
|
233
|
+
|
|
234
|
+
- `bump` regenerates, decides each package's release, gates generated output on prod, writes versions, regenerates at
|
|
235
|
+
them, and records the release. It prints one `bumped: <name> <version> <kind>` line per release and one
|
|
236
|
+
`wrote: <path>` line per file it touched.
|
|
237
|
+
- `sync` mirrors each package and pushes its tag. It needs `GH_TOKEN` unless `--dry-run` or `--validate-only` is set.
|
|
238
|
+
- `bootstrap` makes the first push to an empty public repo, or over the stub a new repo starts with.
|
|
239
|
+
- `codegen` runs the config's codegen from the repo root, as bump runs it.
|
|
240
|
+
- `toolchains` prints the config's `toolchains`, one per line.
|
|
241
|
+
|
|
242
|
+
## Versioning
|
|
243
|
+
|
|
244
|
+
`bump` runs the product's codegen, then compares each package with what its `.release-state.json` recorded at the last
|
|
245
|
+
release. It compares the generated output (backend's `.clients-generated.json` map, or the spec itself for a hand-kept
|
|
246
|
+
package) and the tracked hand files (version lines normalized, the CHANGELOG and the state file left out). Nothing
|
|
247
|
+
moved means no release, even when the spec moved.
|
|
248
|
+
|
|
249
|
+
When the output changed on a moved spec, oasdiff compares the spec with the one the last release was cut from (read
|
|
250
|
+
back with `git show <commit>:<path>`). Any API change, breaking or not, is a minor. Output that changed with no API change,
|
|
251
|
+
and any hand-file change, is a patch. A package stays on its major line: a major comes only from `--major`, which makes each
|
|
252
|
+
package that releases a major.
|
|
253
|
+
|
|
254
|
+
A release writes the new version into every version file the package has (`package.json`, `jsr.json`,
|
|
255
|
+
`pyproject.toml`). It reruns codegen with `RELEASE_VERSIONS`, so version-baked output is regenerated at that version.
|
|
256
|
+
Only then does it record the digests, the spec's commit and the version in `.release-state.json`, so the merged release
|
|
257
|
+
PR finds nothing left to release. The spec must be committed first, because the state records HEAD. A refusal writes
|
|
258
|
+
nothing, so a rerun decides the same. Each public repo's `release.yml` checks the tag against its version files, so a
|
|
259
|
+
tag whose files disagree fails before anything publishes.
|
|
260
|
+
|
|
261
|
+
## Tags
|
|
262
|
+
|
|
263
|
+
Sync tags; the private repo never does. After sync pushes a package, or finds the bot's tip already equal to the
|
|
264
|
+
source, it pushes `v<version>` from the package's `.release-state.json` unless that tag exists. It never moves a tag,
|
|
265
|
+
so a rerun, or a run after one that stopped between its commit and its tag, converges. A merged release PR therefore
|
|
266
|
+
releases every bumped package on the next sync. Never delete or move a pushed tag.
|
|
267
|
+
|
|
268
|
+
## Deployed spec gate
|
|
269
|
+
|
|
270
|
+
Generated code may only describe operations prod serves. The gate fetches `spec.deployedUrl` and compares it with the
|
|
271
|
+
committed spec by canonical sha. Sync refuses a package whose changed paths include a file clients generated. Bump
|
|
272
|
+
refuses the whole run, hand-kept packages included, when a generated package whose output changed would release. On
|
|
273
|
+
drift both print both shas and the operations on either side. Deploy, then rerun the bump caller; sync reruns on its
|
|
274
|
+
schedule.
|
|
275
|
+
|
|
276
|
+
## Channels
|
|
277
|
+
|
|
278
|
+
| Package kind | Channel | Published by |
|
|
279
|
+
| -------------------------- | --------------------------------------------------------------------------------------------- | ----------------------------------------- |
|
|
280
|
+
| CLI | GitHub Release: archives, `checksums.txt` signed by cosign, build attestations, `version.txt` | backend's `release.yml` in the CLI's repo |
|
|
281
|
+
| CLI | Homebrew cask, Scoop manifest, winget PR, AUR `<bin>-bin`, deb/rpm/apk assets (each optional) | the same, with its channel's secret |
|
|
282
|
+
| TypeScript SDK, MCP server | npm (provenance), JSR | the rendered `release.yml` |
|
|
283
|
+
| Go SDK | the Go proxy (`proxy.golang.org` fetch of the tag) | the rendered `release.yml` |
|
|
284
|
+
| Python SDK | PyPI (attestations) | the rendered `release.yml` |
|
|
285
|
+
| Rust SDK | crates.io | the rendered `release.yml` |
|
|
286
|
+
| C# SDK | NuGet | the rendered `release.yml` |
|
|
287
|
+
| Java SDK | Maven Central (GPG-signed bundle through the Central Portal) | the rendered `release.yml` |
|
|
288
|
+
| OpenAPI spec | GitHub Release with `openapi.json` | the rendered `release.yml` |
|
|
289
|
+
|
|
290
|
+
A rendered `release.yml` checks the tag against the version each registry publishes from, publishes, and retries until
|
|
291
|
+
the registry serves the version. A rejected or repeated upload fails the run; a rerun is `workflow_dispatch` with the
|
|
292
|
+
tag. Go modules at 2.0.0 and up carry `/v<major>` in their path, which codegen adds for the go and cli targets.
|
|
293
|
+
|
|
294
|
+
## Secrets
|
|
295
|
+
|
|
296
|
+
| Secret | Where | Read by |
|
|
297
|
+
| -------------------------------------------------- | ---------------- | --------------------------------------------------------------------------------- |
|
|
298
|
+
| the App's ID and private key | the private repo | the sync caller, passed as `app-id` and `app-private-key` |
|
|
299
|
+
| `HOMEBREW_TAP_TOKEN` | `<org>/cli` | goreleaser's cask push to the tap |
|
|
300
|
+
| `SCOOP_BUCKET_TOKEN` | `<org>/cli` | goreleaser's manifest push to the bucket |
|
|
301
|
+
| `WINGET_TOKEN` | `<org>/cli` | goreleaser's push to the winget-pkgs fork and its PR to `microsoft/winget-pkgs` |
|
|
302
|
+
| `AUR_SSH_KEY` | `<org>/cli` | goreleaser's push to `aur.archlinux.org/<bin>-bin.git` |
|
|
303
|
+
| none for npm, JSR, PyPI, crates.io, NuGet | | trusted publishers; NuGet's login also reads the repo variable `NUGET_USER` |
|
|
304
|
+
| `MAVEN_CENTRAL_USERNAME`, `MAVEN_CENTRAL_PASSWORD` | `<org>/sdk-java` | the Central Portal user token: uploads the bundle and polls until it is published |
|
|
305
|
+
| `MAVEN_GPG_PRIVATE_KEY`, `MAVEN_GPG_PASSPHRASE` | `<org>/sdk-java` | signs every bundle file; the public key must be on a keyserver Central reads |
|