mirror of
https://github.com/Fission-AI/OpenSpec.git
synced 2026-09-14 20:16:53 +08:00
Tabish Bidiwale
807b9d32a6
* Clarify release automation proposal * chore(release): phase 1 – wire up changesets action (dry-run publish) and GitHub release drafting * ci(release): phase 1 – add NODE_AUTH_TOKEN alias and registry/auth config for npm (dry-run)
50 lines
4.3 KiB
Markdown
50 lines
4.3 KiB
Markdown
## Why
|
||
Today’s process requires maintainers to merge the Changesets PR, cut a tag, and draft the GitHub release by hand. npm publish then runs from our existing workflow after the GitHub release is published. The human-in-the-loop steps (versioning, tagging, release notes) slow us down and risk drift between npm, tags, and changelog.
|
||
|
||
## What Changes
|
||
- Use the single `changesets/action` on pushes to `main` to either open/update the version PR or, when the release PR is merged, run our publish command automatically using repository secrets.
|
||
- Add a `release` script that builds and runs `changeset publish` so the action handles version bumps, changelog commits, npm publish, and GitHub releases end-to-end.
|
||
- Enable `createGithubReleases: true` so GitHub releases are created from the changeset data right after publishing.
|
||
- Document the automated flow, required secrets, guardrails, and recovery steps (rollback, hotfixes).
|
||
|
||
## Two-Phase Rollout (Two PRs)
|
||
1) Phase 1 — Dry run (no publish)
|
||
- Update the existing `release-prepare.yml` to wire up `changesets/action` with `createGithubReleases: true` and a no-op `publish` command (e.g., `echo 'dry run'`).
|
||
- Keep `.github/workflows/release-publish.yml` intact. This avoids any publish path changes while we verify that the version PR behavior and permissions are correct.
|
||
- Add a repository guard (`if: github.repository == 'Fission-AI/OpenSpec'`) and a concurrency group for safety.
|
||
|
||
2) Phase 2 — Enable publish and consolidate
|
||
- Add `"release": "pnpm run build && pnpm exec changeset publish"` to `package.json`.
|
||
- Change `release-prepare.yml` to use `with: publish: pnpm run release` and `env: NPM_TOKEN: \\${{ secrets.NPM_TOKEN }}` plus the default `GITHUB_TOKEN`.
|
||
- Remove `.github/workflows/release-publish.yml` to avoid double-publish. Publishing now happens when the version PR is merged.
|
||
|
||
## Guardrails
|
||
- Concurrency: `concurrency: { group: release-\\${{ github.ref }}, cancel-in-progress: false }` on the workflow to serialize releases.
|
||
- Repository/branch guard: run publish logic only on upstream `main` (`if: github.repository == 'Fission-AI/OpenSpec' && github.ref == 'refs/heads/main'`).
|
||
- Permissions: ensure `contents: write` and `pull-requests: write` for opening/updating the version PR; `packages: read` optional.
|
||
|
||
## Rollback and Hotfixes
|
||
- Rollback: revert the release PR merge (which reverts version bumps/changelog); if a tag or GitHub release was created, delete the tag and release; deprecate the npm version if necessary (`npm deprecate @fission-ai/openspec@x.y.z 'reason'`).
|
||
- Hotfix (urgent, no pending changesets): create a changeset for the fix and merge the release PR; in emergencies, run a manual bump/publish but reconcile with Changesets by adding a follow-up changeset to align versions.
|
||
|
||
## Required Secrets
|
||
- `NPM_TOKEN` with publish rights for the `@fission-ai` scope.
|
||
- Default `GITHUB_TOKEN` (provided by GitHub) for opening/updating the version PR and creating GitHub releases.
|
||
|
||
## How the Maintainer Flow Changes
|
||
| Step | Current process | Future process |
|
||
| --- | --- | --- |
|
||
| Prepare release | Merge changeset PR, then manually draft release notes and tags | Merge release PR; action updates versions and handles changelog automatically |
|
||
| Publish npm package | Happens automatically after GitHub release | Happens automatically via `changeset publish` invoked by the action |
|
||
| GitHub release | Draft manually and sync with changelog | Action creates GitHub releases from changeset data |
|
||
| Docs/process | Follow manual tagging/release steps | Docs describe automated flow + recovery and hotfix paths |
|
||
|
||
## Impact
|
||
- Automation: reuse `.github/workflows/release-prepare.yml` (phase 1: dry-run, phase 2: publish) and remove `.github/workflows/release-publish.yml` in phase 2.
|
||
- Package metadata: add `release` script to `package.json`.
|
||
- Docs: update README or `/docs` to show the automated flow, secrets, guardrails, and recovery steps.
|
||
|
||
## Acceptance Criteria
|
||
- Phase 1: merges to `main` open/update a version PR; on merge, the action’s `publish` step is a no-op; no npm publish occurs; logs confirm intended behavior; GitHub releases creation is wired but inert due to no publish.
|
||
- Phase 2: merges to `main` run `pnpm run release` from the action; npm package publishes successfully; GitHub release is created automatically; `.github/workflows/release-publish.yml` is removed; no duplicate publishes occur.
|