From 8e9970c9b8240e49f0a07ef384e81271f564cbf3 Mon Sep 17 00:00:00 2001 From: Michael Magan Date: Sun, 23 Aug 2026 11:19:55 -0700 Subject: [PATCH] Document that merging to main doesn't publish anything MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Just watched a skills/** change (the product-context line, then the app-building-guide rewrite) merge to main and sit unpublished on ClawHub for a day, because clawhub-publish.yml only really syncs on a release event — a PR merge only runs its dry-run branch. Nothing on main said so anywhere a contributor would see it before hitting it. Add a "Releasing" section to CONTRIBUTING.md spelling out the tag-push flow (npm + GitHub release + ClawHub sync in one shot), and flag the gap directly in the workflow's own header comment. Co-Authored-By: Claude Sonnet 5 --- .github/workflows/clawhub-publish.yml | 6 ++++++ CONTRIBUTING.md | 12 ++++++++++++ 2 files changed, 18 insertions(+) diff --git a/.github/workflows/clawhub-publish.yml b/.github/workflows/clawhub-publish.yml index 146e303..9a956b6 100644 --- a/.github/workflows/clawhub-publish.yml +++ b/.github/workflows/clawhub-publish.yml @@ -16,6 +16,12 @@ name: ClawHub publish # Skills have no OIDC/trusted-publisher option yet, so this uses # CLAWHUB_TOKEN, a token from `clawhub login` + `clawhub token`, scoped to # the charming publisher (clawhub.ai/settings?view=organizations). +# +# IMPORTANT: merging a PR to main does NOT publish anything here — only +# `pull_request` (dry-run, no token) or `release: published` (real sync) +# trigger a run, and nothing on main fires a release event by itself. A +# skills/** change sits unpublished on ClawHub until someone tags a +# release. See "Releasing" in CONTRIBUTING.md. on: pull_request: diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 681bab7..b4f8a21 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -9,3 +9,15 @@ Issues and pull requests are welcome. 5. Explain the user-visible effect in the pull request. Do not edit `src/generated/operations.ts` directly. If the API contract changed, update `openapi.json` and run `bun run openapi:gen`. + +## Releasing + +Merging a PR to `main` does not publish anything. In particular, a `skills/**` change sits unpublished on ClawHub until a release ships — `clawhub-publish.yml` only runs a `--dry-run` on a pull request; the real `sync` (with `CLAWHUB_TOKEN`) runs on the `release: published` event only, and nothing on `main` fires that automatically. + +To ship a release (npm + GitHub release + ClawHub sync, in one shot): + +1. Bump `version` in `package.json`. +2. Commit and merge that change to `main`. +3. Tag the merge commit and push the tag: `git tag vX.Y.Z && git push origin vX.Y.Z`. The tag must match `package.json`'s version exactly, or `release.yml` fails its verification step. + +The tag push runs `bun run check`, publishes to npm (trusted publishing, no manual token), creates the GitHub release, and — because that release triggers `clawhub-publish.yml`'s `publish` job — syncs `skills/charming` to ClawHub. If you only need the ClawHub side (no npm-worthy change), run the `ClawHub publish` workflow manually instead: **Actions → ClawHub publish → Run workflow**.