Skip to content

docs(release): unpark the release workflow and correct its setup status #8

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

Merged
kboshold merged 2 commits into from
Jul 31, 2026
Merged

docs(release): unpark the release workflow and correct its setup status #8

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
c9bb0a1
docs(release): unpark the release workflow and record the backfilled tag
kboshold Jul 31, 2026
433c350
docs(release): correct the setup status, it is not confirmed done
kboshold Jul 31, 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
14 changes: 8 additions & 6 deletions .github/workflows/release.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,11 +1,13 @@
name: Release (draft, parked, not enabled)
name: Release

# PARKED. This is a design draft for the @sidebase/streamctl publish path. It
# is workflow_dispatch only and gated behind the protected `release`
# environment, so it cannot publish until someone wires the secrets and
# dispatches it by hand. docs/release.md has the ship-time checklist.
# Publishes @sidebase/streamctl to the public npm registry under the @sidebase
# scope. workflow_dispatch only, and scoped to the `release` environment.
#
# That environment is only a gate once it exists and carries reviewers plus
# NPM_TOKEN. GitHub auto-creates a missing environment unprotected and
# secretless, so an unconfigured dispatch skips the approval pause and dies at
# publish on auth. docs/release.md has the setup checklist and how to check it.
#
# Single-package publish to the public npm registry under the @sidebase scope.
# The two packages version independently, no lockstep. Publish the CLI before
# the config package on a first publish: the config repo's validate-presets
# consumes the schema this package exports. See docs/release.md.
Expand Down
31 changes: 27 additions & 4 deletions docs/release.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,9 +1,10 @@
# Release runbook (`@sidebase/streamctl`)

> **Status: 0.1.0 is on the registry.** The `Release` workflow
> (`.github/workflows/release.yml`) stays `workflow_dispatch`-only and gated behind
> the protected `release` environment, so every publish is a deliberate manual
> dispatch by a maintainer who has completed the one-time setup below.
> **Status: `0.1.0` is on the registry, published by hand.** The `Release`
> workflow (`.github/workflows/release.yml`) has never published, and the
> one-time setup below is not confirmed done. It stays `workflow_dispatch`-only
> and scoped to the `release` environment, so every publish is a deliberate
> manual dispatch.

`streamctl` publishes to the public npm registry under the `@sidebase` scope. It
is an intentionally ESM-only package; the published tarball ships only `dist/`.
Expand Down Expand Up @@ -36,6 +37,18 @@ removed) so consumer CI that parses it survives CLI upgrades.

## One-time setup

**Not verified as done.** `0.1.0` reached the registry by a manual publish that
bypassed this workflow, so its presence says nothing about whether the workflow
can publish. As of writing, `gh api repos/sidebase/streamctl/environments`
returns zero environments and `gh secret list` is empty, so at minimum step 3 is
outstanding. Step 2's token may exist as an **org** secret, which is not readable
without org admin. Confirm before the first dispatch.

A missing environment does not fail loudly: GitHub creates one on demand with no
protection rules and no secrets, so the run loses its approval gate and reaches
the publish step with an empty `NODE_AUTH_TOKEN`. It then fails on auth, before
the push, leaving origin untouched.

1. **npm org / scope.** Create/claim the `@sidebase` org on npmjs.com and add the
release machine account. Confirm the package name `@sidebase/streamctl` is free
(or owned). `publishConfig.access` is already `public` in `package.json`.
Expand Down Expand Up @@ -66,6 +79,16 @@ approve the environment gate. The workflow:
After the run, verify the published tarball on npm, the `vX.Y.Z` tag, and the
generated GitHub Release notes.

Step 6 diffs against the previous tag, so every release needs its predecessor
tagged or the notes cover the whole history. **`0.1.0` was published outside this
workflow and left no tag.** `v0.1.0` has since been backfilled onto
`265809b` (`chore: bump deps (#6)`), the last commit carrying that version, so
the next release diffs against the right point. Nothing else needs backfilling.

The version is an input, not something you edit first. Do not bump
`package.json` by hand before dispatching: step 2 sets it, and a pre-bumped
working tree just means the release commit contains no version change.

## Notes for the next release

Include these in the release notes; the rest is generated from commit subjects.
Expand Down