@devries-cameron20 / composio Mirror · read-only / commits / 918a55a9b
Fork 0

Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.

Mirrored from https://github.com/Camo67/composio.git

Synced Nov 21, 06:00 UTC

docs(release): document release states, betas and verification

jkomyno committed Nov 5, 2026 at 19:07 UTC 918a55a9b9e08d87f208a50b3db964dc7d5fe487
6 files changed +57 -17
.agents/skills/cli-release/references/release-workflow.md
+1 -1
@@ -19,7 +19,7 @@
19 - `.github/workflows/cli.test-installation.yml` validates installers after publication.
20 - `.changeset/config.json` ignores `@composio/cli`.
21
22 -`sdk.release.yml` owns stable Python/TypeScript publication; `ts.release.yml` retains the `main` SDK beta lane. CLI binary releases use their own workflow.
22 +`sdk.release.yml` owns stable and beta Python/TypeScript publication from `next`; `ts.release.yml` retains the 1.0 prerelease train on `main`. CLI binary releases use their own workflow.
23
24 ## Choose The Path
25
.agents/skills/python-release/references/release-workflow.md
+1 -1
@@ -10,7 +10,7 @@ make build
10
11 `make build` cleans build outputs, builds the root package, then builds provider packages and collects distributions.
12
13 -Stable Python releases use the unified `sdk.release.yml` member request and one approved release PR. Author changesets for the private `@composio/python-sdk` marker; the release bot synchronizes core and all supported provider metadata. Read `ts/docs/internal/release.md` for request, approval, merge, recovery and owner setup steps.
13 +Stable and beta Python releases use the unified `sdk.release.yml` member request and one approved release PR; a beta publishes `X.Y.ZbN` for core and every provider. Author changesets for the private `@composio/python-sdk` marker; the release bot synchronizes core and all supported provider metadata. Read `ts/docs/internal/release.md` for request, approval, merge, recovery and owner setup steps.
14
15 Recovery: re-run a failed tag run with `gh run rerun <tag-run-id> --failed`. When the approved candidate expired, add a changeset and request a new release. Agents stop at "release PR ready for approval" and never merge it.
16
.agents/skills/repo-guidance/references/repository-workflow.md
+1 -1
@@ -50,7 +50,7 @@ make build
50 - Public SDK behavior changes need a Changesets note for each affected TypeScript package and/or the private `@composio/python-sdk` marker. Python core and supported providers share one stable release train.
51 - `@composio/cli` is ignored by Changesets. Never target it in a changeset while it remains ignored; use the `cli-release` skill for beta builds and stable promotion.
52 - Repo guidance, docs-only, tests-only, internal validation and CLI-only changes do not require an SDK note. Explicit behavior exemptions need a meaningful `<!-- sdk-release-note-exempt: meaningful reason of at least 20 characters -->` comment in the PR body.
53 -- Stable SDKs use **SDK release** on protected `next`: a member issue request, one release PR that a non-requester approves and a person merges, and a tag run that publishes the PR-built candidates. Recover with **Re-run failed jobs**. Read `ts/docs/internal/release.md` before operating it.
53 +- Stable and beta SDKs use **SDK release** on protected `next`: a member issue request, one release PR that a non-requester approves and a person merges, and a tag run that publishes the PR-built candidates. Recover with **Re-run failed jobs**. Read `ts/docs/internal/release.md` before operating it.
54
55 ## Generated And Vendor Files
56
CONTRIBUTING.md
+1 -1
@@ -307,7 +307,7 @@ bun run lint:links
307
308 ## Release Process
309
310 -Any active ComposioHQ member can request a stable SDK release through the SDK release issue form. Repository writers can also run **SDK release** on `next`. A repository writer who did not request the release approves the final release PR, a person merges it, and automation publishes the candidates the PR built and checked. See the shared runbook below. CLI binaries and `main` beta releases keep their separate workflows.
310 +Any active ComposioHQ member can request a stable or beta SDK release through the SDK release issue form. Repository writers can also run **SDK release** on `next`. A repository writer who did not request the release approves the final release PR, a person merges it, and automation publishes the candidates the PR built and checked. See the shared runbook below. CLI binaries and the 1.0 prerelease train on `main` keep their separate workflows.
311
312 - TypeScript packages and the CLI: [`ts/docs/internal/release.md`](ts/docs/internal/release.md)
313 - Python packages: [`python/docs/release.md`](python/docs/release.md)
ts/AGENTS.md
+1 -1
@@ -32,7 +32,7 @@ pnpm test:e2e:cli
32
33 - Do not edit `ts/vendor/`; those submodules are read-only references.
34 - Keep generated outputs owned by their generator.
35 -- Add a Changesets note for each affected published TypeScript package; cross-language changes also target the private `@composio/python-sdk` marker. Stable SDK publication uses the unified request workflow.
35 +- Add a Changesets note for each affected published TypeScript package; cross-language changes also target the private `@composio/python-sdk` marker. Stable and beta SDK publication uses the unified request workflow.
36 - Never add changesets for `@composio/cli` while `.changeset/config.json` ignores it; record CLI notes in `ts/packages/cli/CHANGELOG.md` instead.
37 - Prefer focused package tests before broad workspace tests.
38 - Parse untyped or external data (API payloads, JSON, `unknown`) at the boundary with schemas and let inferred types flow downstream: zod in SDK packages (`@composio/core`, providers, shared packages), `effect/Schema` in `ts/packages/cli/`. Never hand-roll structural guards (`'x' in obj` / `typeof` chains) or cast parsed JSON with `as`.
ts/docs/internal/release.md
+52 -12
@@ -1,18 +1,45 @@
1 -# Stable SDK releases
1 +# SDK releases
2
3 -One workflow, `sdk.release.yml`, releases the TypeScript SDK, the Python SDK, or both. A member requests the release, the bot opens one release PR, a reviewer approves it, and a person merges it. The workflow then publishes the files the PR checked and opens a docs PR that pins the released versions.
3 +One workflow, `sdk.release.yml`, releases the TypeScript SDK, the Python SDK, or both, as a stable release or a beta. A member requests the release, the bot opens one release PR, a reviewer approves it, and a person merges it. The workflow then publishes the files the PR checked, checks that users get exactly those files, and, for a stable release, opens a docs PR that pins the released versions.
4
5 ```text
6 request (issue or dispatch) → release PR (bot) → candidate checks → approve → merge
7 - → tag sdk-release/<id> → publish npm + PyPI → docs pin PR
7 + → tag sdk-release/<id> → publish npm + PyPI → verify → docs pin PR (stable)
8 ```
9
10 +## Release states
11 +
12 +The request issue always shows where the release is: one status comment that the bot edits in place, and one `sdk-release:<state>` label. `scripts/sdk-release/state.ts` lists every state and which stage can end in it.
13 +
14 +| State | Meaning | Issue |
15 +| ------------- | ----------------------------------------------------------------------------------------------- | ------ |
16 +| `in-review` | The release PR is open. | open |
17 +| `publishing` | The merged PR is tagged; the tag run is publishing. | open |
18 +| `published` | Every planned package is on its registry. | closed |
19 +| `failed` | A job failed or was cancelled. **Re-run failed jobs** resumes it. | open |
20 +| `needs-input` | The request form could not be read. | closed |
21 +| `waiting` | Another release PR is open. Request again after it finishes. | closed |
22 +| `blocked` | A release merged into `next` but was never tagged. Re-run its tag job or revert its release PR. | closed |
23 +| `empty` | No pending changesets for the selected languages. | closed |
24 +| `abandoned` | The release PR closed without merging. | closed |
25 +| `refused` | The release PR merged but failed the gate. Revert it, then request again. | closed |
26 +
27 ## Request
28
29 1. Open a GitHub issue with the **SDK release** form. Every active ComposioHQ member can use it, including members with repository Read access. Repository writers can instead run **SDK release** on `next` in Actions.
13 -2. Leave each language at `auto` to follow its changesets, or choose `patch`, `minor`, `major`, or `skip`. An explicit bump with no changesets creates a maintenance release; `auto` with no changesets replies "Nothing to release."
30 +2. Choose the channel: `stable`, or `beta` for a preview.
31 +3. Leave each language at `auto` to follow its changesets, or choose `patch`, `minor`, `major`, or `skip`. An explicit bump with no changesets creates a maintenance release; `auto` with no changesets ends as `empty`.
32 +
33 +For a stable release, the bot plans versions on the current `next`, regenerates the SDK reference docs, writes the package changelogs and one docs changelog entry, and opens the release PR. Later `next` commits wait for the next release. Only one release PR is open at a time, across both channels.
34 +
35 +### Betas
36 +
37 +A beta goes through the same release PR, approval, gate and tag as a stable release. Only its versions and npm dist-tag differ:
38
15 -The bot plans versions on the current `next`, regenerates the SDK reference docs, writes the package changelogs and one docs changelog entry, and opens the release PR. Later `next` commits wait for the next release. Only one release PR is open at a time.
39 +- Its versions are the ones the pending changesets would release, suffixed with the planning run: `0.29.0-beta.<run>` on npm and `0.29.0b<run>` on PyPI. Core and every Python provider release together.
40 +- Its release PR commits only `.github/sdk-release-plan.json`. The candidate checks apply the versions where they build, so `next` keeps its stable versions and every changeset stays pending for the stable release.
41 +- npm publishes it under the `next` dist-tag and never moves `latest`. (`beta` belongs to the 1.0 train on `main`.) pip and uv install it only with `--pre` or an exact pin.
42 +- It needs no docs check, writes no changelog and opens no docs pin PR.
43
44 ## Review and approve
45
@@ -25,15 +52,16 @@ Do not push to the release branch. The tag step accepts only the bot's commit, s
52
53 ## Merge and publish
54
28 -A person merges the approved, green release PR under normal `next` protection. On merge, the `tag` job checks that the head is the bot's commit, the approval, and the candidate and docs checks, then tags the head `sdk-release/<id>`. If the gate fails it creates no tag and comments the fix on the PR: revert the release PR on `next`, then request the release again.
55 +A person merges the approved, green release PR under normal `next` protection. On merge, the `tag` job checks that the head is the bot's commit, the approval, and the candidate checks (plus the docs check for a stable release), then tags the head `sdk-release/<id>`. If the gate refuses the release it creates no tag and comments the fix on the PR: revert the release PR on `next`, then request the release again. Closing the release PR without merging abandons the release.
56
57 The tag run then:
58
59 1. Pins the candidate artifacts built on the release PR by ID and digest. It never rebuilds.
33 -2. Uploads only the files npm and PyPI are missing. An existing file with identical bytes is accepted; different bytes stop the run with a conflict. npm versions are uploaded under a release-only dist-tag, and `latest` moves once every upload is visible.
34 -3. Comments the published versions on the request issue and opens a docs PR that pins the released npm versions in `docs/package.json` and `docs/bun.lock`. Merging that PR after its checks pass is what makes twoslash type-check the docs against the released types.
60 +2. Uploads only the files npm and PyPI are missing. An existing file with identical bytes is accepted; different bytes stop the run with a conflict. npm versions are uploaded under a release-only dist-tag; the channel's tag (`latest` or `next`) moves forward once every upload is visible, and the release-only tag is removed.
61 +3. Checks what users get. Each npm tarball's provenance must name `sdk.release.yml` at this release's tag and describe the reviewed bytes, and `npm audit signatures` passes on a fresh install. Each PyPI file must be attested by `sdk.release.yml` in `pypi-release`, and `pypi-attestations` verifies the signature.
62 +4. For a stable release, opens a docs PR that pins the released npm versions in `docs/package.json` and `docs/bun.lock`. Merging that PR after its checks pass is what makes twoslash type-check the docs against the released types.
63
36 -If any job fails, the run comments the failed jobs and the run link on the request issue.
64 +The last job of each stage shows the outcome on the request issue, including failed and cancelled jobs.
65
66 ## Recover a failed release
67
@@ -41,6 +69,18 @@ Open the tag run and choose **Re-run failed jobs**. A re-run publishes the same
69
70 If the artifacts expired, or a registry already serves different bytes, add changesets for the affected packages on `next` and request a new release. It plans from the versions in `next`, so the unpublished versions are skipped and the packages move to the next version.
71
72 +## Verify a release yourself
73 +
74 +Anyone can check that a published version came from this workflow:
75 +
76 +```bash
77 +# npm: registry signatures and provenance of an installed version
78 +npm install @composio/core@0.29.0 && npm audit signatures
79 +# PyPI: the PEP 740 attestation of a published file
80 +uvx pypi-attestations verify pypi --repository https://github.com/ComposioHQ/composio \
81 + https://files.pythonhosted.org/.../composio-0.29.0-py3-none-any.whl
82 +```
83 +
84 ## Add a release note
85
86 Run from the repository root:
@@ -77,12 +117,12 @@ Complete these hosted prerequisites before the first release.
117 1. Install a dedicated SDK release App with repository Contents, Pull requests, and Issues write, Actions read, and organization Members read. It needs no protection bypass on `next`. Set the `SDK_RELEASE_APP_SLUG` and `SDK_RELEASE_APP_CLIENT_ID` variables. Put `SDK_RELEASE_APP_PRIVATE_KEY` only in the `sdk-release-control` environment, restricted to `next`.
118 2. Protect `sdk-release/*` tags against creation, update, and deletion, with only this App allowed to bypass. Publishing trusts these tags, so check that an ordinary writer cannot create or move one.
119 3. Create `npm-release` and `pypi-release` environments that deploy only from `sdk-release/*` tags.
80 -4. Register trusted publishers for `.github/workflows/sdk.release.yml` with the `npm-release` environment on every npm package, and with `pypi-release` on every PyPI package. Always set the environment: PyPI treats a publisher without one as matching any environment. On npm, enable **Allow npm dist-tag**, because the publish job moves `latest` with `npm dist-tag`. Register shortly before the first release, because npm drops a new trusted publisher that hasn't published within 2 days. Keep the existing `ts.release.yml` and `py.release.yml` publishers. npm allows up to 10 trusted publishers per package and PyPI accepts several, so the `main` beta lane and core prereleases keep publishing.
120 +4. Register trusted publishers for `.github/workflows/sdk.release.yml` with the `npm-release` environment on every npm package, and with `pypi-release` on every PyPI package. Always set the environment: PyPI treats a publisher without one as matching any environment. On npm, enable **Allow npm dist-tag**, because the publish job moves `latest` or `next` and removes the release-only tag with `npm dist-tag`. Register shortly before the first release, because npm drops a new trusted publisher that hasn't published within 2 days. Keep the existing `ts.release.yml` and `py.release.yml` publishers. npm allows up to 10 trusted publishers per package and PyPI accepts several, so the `main` beta lane and core prereleases keep publishing.
121 5. Restrict pushes to `sdk-release/batch-*` branches to the App. The tag step refuses heads the App did not commit, so this only prevents confusion.
122 6. Keep Actions artifact retention at 30 days or more.
123
84 -## CLI binaries and beta SDKs
124 +## CLI binaries and the 1.0 train
125
126 CLI binaries keep **Build CLI Binaries** and GitHub Releases. `@composio/cli` stays excluded from changesets. Follow the [CLI release skill](../../../.agents/skills/cli-release/references/release-workflow.md).
127
88 -The `main` SDK beta lane keeps `ts.release.yml`, its prerelease state and its trusted identity. `py.release.yml` keeps build-only dispatch and core prereleases.
128 +The 1.0 prerelease train on `main` keeps `ts.release.yml`, its prerelease state, the npm `beta` dist-tag and its trusted identity. `py.release.yml` keeps build-only dispatch and core prereleases. Betas of `next` use `sdk.release.yml` instead.