Skip to content

RELEASING.md

Latest commit

 

History

History
111 lines (82 loc) · 3.85 KB

RELEASING.md

File metadata and controls

111 lines (82 loc) · 3.85 KB
Raw

Releasing an update

The repeatable flow for shipping a change to npx styleref users. Written for whoever — human or agent — picks this up cold.

If this reached you as a git submodule inside the StyleRef monorepo, work here, in the submodule, not in a copy elsewhere. A commit made outside this repo publishes nothing.

1. Make the change

The package is zero-dependency by design — standard library only. That is what makes npx styleref start fast and stay auditable. Adding a dependency is a deliberate decision, not a convenience; prefer a few more lines in lib/.

Keep the terminal-facing copy in lib/core.mjs (USAGE) in step with what the commands actually do.

2. Bump the version

package.json version only — there is no second place to update. Use semver. The publish workflow rejects a tag that doesn't match this field exactly.

3. Verify locally

node --test
node bin/styleref.mjs --help
node bin/styleref.mjs --version

npm pack --dry-run is worth a look whenever files in package.json changes — the tarball is what users actually get, and a missing entry there is invisible until someone installs a broken build. CI checks this too.

4. Commit and push, in this repo

git add -A
git commit -m "..."
git push origin main

5. Tag the commit you just pushed

git tag -a vX.Y.Z -m "..."
git push origin vX.Y.Z

The tag push fires Publish to npm (.github/workflows/publish.yml): it re-checks the tag against package.json, smoke-tests the entry point, then runs npm publish --provenance --access public with the NPM_TOKEN secret. Watch it in the Actions tab or with gh run watch.

A branch-protection ruleset on main requires status checks a direct push can't have satisfied yet, so the push reports "Bypassed rule violations" — expected, not an error, as long as the pushing account is on the bypass list.

6. Confirm the release landed

A green workflow proves the build succeeded, not that npm serves what you intended:

npm view styleref version
npm view styleref dist.tarball
npx styleref@latest --version

7. Update the docs and the monorepo

  • Public docs: apps/docs/content/for-ai-agents/cli.mdx in the monorepo is the user-facing reference and is deployed separately. A new or changed command is not shipped until that page says so. User-visible new capabilities also need a content/updates/changelog.mdx entry.

  • Submodule pointer: once this package lives in its own repo, a release is invisible to the monorepo until its pointer moves:

    git add packages/styleref-cli
git commit -m "chore(cli): bump to vX.Y.Z (<why>)"

    Skipping this errors nothing — the monorepo just quietly keeps pointing at the old commit.

Standing this up as its own public repo (one-time)

The package is still in-tree in the monorepo. To graduate it the way connectors/styleref-comfyui was graduated, preserving its history:

# 1. From the monorepo root — extract the package with its history intact.
git subtree split --prefix=packages/styleref-cli -b styleref-cli-export

# 2. Create the public repo (github.com/StyleRef/styleref-cli), then push.
git push git@github.com:StyleRef/styleref-cli.git styleref-cli-export:main

# 3. Replace the in-tree directory with a submodule.
git rm -r --cached packages/styleref-cli
rm -rf packages/styleref-cli
git submodule add https://github.com/StyleRef/styleref-cli packages/styleref-cli
git commit -m "chore(cli): move the CLI to its own public repo"

Then, on the new repo: add the NPM_TOKEN secret, and apply the standard public-repo branch ruleset (restrict deletions and force-pushes, require the CI checks, self on the bypass list) — the same convention the ComfyUI connector repo uses. See internal-docs/connectors-repo-graduation.md in the monorepo for the full account of how that was done the first time.