Skip to content

RELEASING.md

Latest commit

 

History

History
66 lines (48 loc) · 5.15 KB

RELEASING.md

File metadata and controls

66 lines (48 loc) · 5.15 KB
Raw

Releasing Compose Packages

This repository publishes 2 npm packages:

  • @perfect-abstractions/compose from src/
  • @perfect-abstractions/compose-cli from cli/

Releases use Changesets and GitHub Actions.

Changelogs

  • Library: CHANGELOG.md at the repo root (also packed into the npm tarball via src/ prepack). The version-packages script syncs Changesets output with this file.
  • CLI: cli/CHANGELOG.md only (not copied to the root).

Release model

  • Branch: main only for production releases.
  • Versioning: independent per package.
  • Selective releases: The Release workflow has a dropdown to choose which packages to release: all, compose only, or compose-cli only. Selecting a single package uses changeset version --ignore to skip the other, so its changesets stay pending for a future release.
  • Batching: Multiple PRs can add .changeset/*.md files; one version bump PR (same PR updated) applies all pending bumps for the selected package(s).
  • Open/update the version PR: Run the Release workflow manually (Actions → Release → Run workflow). It checks out main, runs only the quality gates for the selected package(s), then changesets/action creates or updates a version PR on a target-specific branch:
    • All: changeset-release/main
    • Compose: changeset-release/main-compose
    • Compose-cli: changeset-release/main-cli
  • Publish: Runs automatically when any version bump PR is merged into main (workflow Publish). You can also run Publish manually (workflow_dispatch) to retry or publish without merging from that branch (e.g. hotfix).
  • Publish approval: Jobs that publish to npm use GitHub Environment npm-publish (required reviewers). Approval is requested when those jobs run, including after an automatic trigger.
  • Authentication: Publishes use npm Trusted Publishing (OIDC)
  • Provenance: For public repos, npm generates provenance automatically when publishing via trusted publishing.

Contributor flow

  1. Change code under src/ and/or cli/.
  2. changeset-bot comments on the PR when a release note may be needed. You can run npx changeset locally, use the bot’s add a changeset link on GitHub, or leave it to maintainers before release.
  3. Merge after required CI checks pass.

There is no failing CI check for missing changesets; maintainers batch or add .changeset/*.md when preparing releases as needed.

Maintainer release flow

  1. Go to Actions → Release → Run workflow. Select the target:
    • all — releases both packages together
    • compose — releases only the library (CLI changesets stay pending)
    • compose-cli — releases only the CLI (library changesets stay pending)
  2. Review and merge the chore(release): bump npm versions & changelogs PR. Each release target creates a PR on a different branch (changeset-release/main, changeset-release/main-compose, or changeset-release/main-cli — automatic Publish only runs for merges from branches named changeset-release/*).
  3. Publish starts automatically on that merge. Approve the npm-publish environment when GitHub prompts you.
  4. The plan job fails if any real .changeset/*.md files remain (finish merging the version PR so only .changeset/README.md is left).
  5. The plan job compares each package's package.json version to npm (see .github/publish-packages.json). If every configured package already matches npm, the publish job is skipped (nothing new to ship).
  6. A single publish workflow job runs a matrix: one row per package that is ahead of npm. Rows run in parallel when several packages need a release. Each row publishes to npm, then creates a short git tag and GitHub Release:
    • Library tag: compose@<version> (e.g. compose@0.2.0)
    • CLI tag: compose-cli@<version> (e.g. compose-cli@0.2.0)
  7. Confirm versions on npm and tags/releases on GitHub.

Adding a publishable package

  1. Add the workspace under the repo root package.json workspaces array and ensure the package has a proper package.json (name, version).
  2. Register the package in Changesets (e.g. .changeset/config.json ignore / new package paths as needed).
  3. Add a new entry to .github/publish-packages.json: id, workspace (npm name), versionFile, tagPrefix, needsFoundry (install Foundry before checks when the package needs Forge), and check (shell command, usually npm run … chains from the root package.json).
  4. If you need new check scripts, add them to the root package.json scripts and reference them from the check field.

Manual Publish only

Use Actions → Publish → Run workflow if you need to publish from main without a merge from changeset-release/*

Rollback

Prefer a new patch release with a revert + changeset. Avoid unpublishing except for serious issues.