release cascade - nself-org/cli GitHub Wiki
The ɳSelf release cascade is an ordered, sha256-anchored sequence of 12 steps. Every release of every artifact (CLI, admin, plugins-pro, ntv, nchat, nclaw, nfamily, clawde, homebrew-nself) follows this sequence. No step can be skipped. No step can be re-ordered.
ɳSelf ships 11 sub-repos under one ecosystem version. A release that updates the CLI tarball but forgets to update the homebrew sha256 leaves users with a broken brew upgrade. The cascade makes the complete sequence explicit and auditable.
| Step | ID | Action | Owner |
|---|---|---|---|
| 1 | T01 | Lock version in version.go (cli), pubspec.yaml (flutter apps), package.json (web) |
Implementer |
| 2 | T02 | Build release tarballs for all target platforms (goreleaser) | CI |
| 3 | T03 | Compute sha256 for every tarball and write to checksums.sha256
|
CI |
| 4 | T04 | Create GitHub release with body generated from release-body-generator.sh
|
CI |
| 5 | T05 | Anchor sha256 in homebrew-nself formula (Ruby sha256 field) |
homebrew-nself |
| 6 | T06 |
brew audit --strict passes on the updated formula |
CI (homebrew-nself) |
| 7 | T07 | Run sync-changelog.mjs to generate web/org/content/changelog/vN.N.N.mdx
|
web/org |
| 8 | T08 |
web/org predev (sync-sport.mjs) runs clean , no SPORT drift |
web/org |
| 9 | T09 | plugins-pro registry updated (if pro plugins shipped in this release) | plugins-pro |
| 10 | T10 |
ping.nself.org/release endpoint updated with new version metadata |
web/backend CS_1 |
| 11 | T11 | Social comms draft saved to .claude/outbox/release-vN.N.N.md (agent-draft, human-post) |
.claude/agents |
| 12 | T12 | Tag vN.N.N on every sub-repo that shipped, push tags |
CI |
Step T03 and T05 form the sha256 anchor pair. The checksum computed in T03 must match the value written to the homebrew formula in T05. Any mismatch is caught by brew audit in T06 and blocks the release.
The anchor prevents the class of failure where a tarball is re-built after the homebrew formula is updated, resulting in a permanent sha256 mismatch for end users.
The release body is generated by cli/scripts/release-body-generator.sh. Template varies by repo type:
| Repo type | Template sections |
|---|---|
| A , Product (cli, homebrew-nself) | What's new · Breaking changes · Install command · sha256 |
| D , Plugins (plugins, plugins-pro) | Plugins updated · Migration notes · Install command |
| C , Reference apps (nchat, nclaw, ntv, nfamily, clawde) | What's new · Backend bundle required · Self-host docs link |
| E , Infrastructure (web) | Subapps updated · Deploy notes |
- NEVER bump versions autonomously. A version bump requires explicit user instruction.
- Patch bumps (
v1.0.10,v1.0.11, etc.) are the expected vehicle for rolling CI/CD fixes and bug fixes during P94. - Minor bumps (
v1.1.0) require user-visible new commands or breaking changes. - Major bumps (
v2.0.0) are locked until explicitly approved.
-
cli/scripts/sha256-anchor.sh, computes and verifies sha256 for all tarballs -
cli/scripts/release-body-generator.sh, generates release body per repo type -
web/org/scripts/sync-changelog.mjs, generates changelog MDX from CHANGELOG.md entries -
web/org/scripts/sync-sport.mjs, regenerates sport.json for marketing pages -
.claude/docs/MASTER-VERSIONS.md, version truth (updated on T12 only)