release-publishing
Skill142 starsChanged 7 days agoApache-2.0View on GitHub
This skill should be used when operating releases or npm publishing in brepjs — cutting or merging a release-please PR, recovering a failed npm publish, or deciding whether a commit may carry a breaking marker. Trigger phrases include "release PR", "release-please", "autorelease: pending", "publish to npm", "npm publish failed", "republish", "ETARGET from a leaf release PR ordered ahead of root", "version bump", "why did the major version bump", "breaking change commit", "trusted publisher", "dry_run", "release tag", "manifest conflict", or editing .github/workflows/publish-*.yml or release-please-config.json.
3 other projects use a version of this.
Adopted by
Most recently taken up by
- FNOSP/fntv-client-multiplatformtheir own version, first seen Oct 8, 2026
- FNOSP/FlyNarwhaltheir own version, first seen Oct 8, 2026
- meteor/agent-skillstheir own version, first seen Aug 26, 2026
Other versions3 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 3
- FNOSP/FlyNarwhal★ 519same name
- FNOSP/fntv-client-multiplatform★ 519same name
- meteor/agent-skills★ 11same name
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository18 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- llms-full.txtllms.txt
- llms.txtllms.txt
- adding-operationsSkill
- architecture-navigationSkill
- assembly-solverSkill
- ci-triageSkill
- companion-packagesSkill
- debugging-geometrySkill
- git-pr-workflowSkill
- kernel-abstractionSkill
- memory-and-disposalSkill
- playground-examplesSkill
- quality-gatesSkill
- result-error-handlingSkill
- shaperef-lineageSkill
- wasm-interopSkill
- writing-testsSkill
The file
We split this skill into the rules it gives an agent
2 rules. About 0 are common, 0 are distinctive, and 2 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈0
Distinctive · estimate
This author's own choices. Worth a look.
2
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 45
Root
brepjspublish failed (release tagged, npm empty): Do NOT re-run the failed push job — release-please would try to re-tag. - Very specific: line 96
Commit format and the ! decision: git-pr-workflow skill.
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Releases and npm publishing
Every release in this repo flows through one workflow: .github/workflows/release-please.yml. Its inline comments are the canonical deep documentation — read them before changing anything. This skill is the operator's playbook: how a normal release flows, the hard rules that prevent outages, and the recovery recipes when a step fails.
Mental model
- release-please, manifest mode. Versions live in
.release-please-manifest.json; managed packages are declared inrelease-please-config.json. On every push tomain, release-please opens/updates a per-package release PR (separate-pull-requests: true), bumping the version and CHANGELOG from Conventional Commits. - Six managed packages, two deliberately unmanaged. Managed: root
.(brepjs),packages/brepjs-opencascade,packages/brepjs-voxel-wasm,packages/brepjs-cad,packages/brepjs-bim,packages/brepjs-sheetmetal. NOT managed by release-please:brepjs-viewer(versioned/published manually — see below) andpackages/brepjs-voxel(unpublished workspace consumer). - node-workspace re-pins cross-deps. The
node-workspaceplugin rewrites each leaf package'sbrepjsdependency to the version of the pending root release. This is the source of the ETARGET hazard (below). - npm auth is OIDC trusted publishers, bound to workflow filenames. Each package's publish authenticates via an npm trusted publisher tied to a specific
.github/workflows/publish-*.ymlfilename. Renaming a publish workflow breaks auth silently.
How a normal release flows
- Commits land on
mainwith Conventional-Commit subjects (enforced by commitlint — seecommitlint.config.js,.husky/commit-msg; format detail lives in the git-pr-workflow skill). - The
release-pleasejob (App token,googleapis/release-please-action@v5) opens or updates release PRs labeledautorelease: pending. - The
auto-mergejob serializes root before leaves: it lists openautorelease: pendingPRs and, per branch name:*--components--brepjs-opencascade→ permanently held (manual, expensive WASM build).- root branch
release-please--branches--main--components--brepjs→gh pr merge --auto --squash(merges first). - any other leaf → held while a root release PR is open; merged on a later run after root lands.
- Root release PR merges. CI passes trivially on release PRs —
ci.ymlskips the paths-filter forrelease-please--*branches, andci-passtreats skipped jobs as pass — so--autocompletes. publish-brepjsruns inline inrelease-please.yml:npm ci && npm run build && npm publish --provenance(OIDC). This is the ONLY package published inline.- Merging bumps
main. The next release-please run regenerates each leaf PR with a now-validbrepjspin, auto-merges them, and each auto-publishing leaf's job dispatches its ownpublish-brepjs-<pkg>.ymlwith-f dry_run=false --ref <release-tag>. (brepjs-opencascadeis the exception — always manual viapublish-opencascade.yml;brepjs-voxel-wasmhas no publish workflow.)
Leaves dispatch against the immutable release tag release-please just created, never main: the dispatch API accepts a tag but rejects a raw SHA, and the tag pin avoids publishing the wrong commit if another push lands mid-window.
Hard rules
| Rule | Why | Where |
Never put !/BREAKING CHANGE on a commit unless intentionally breaking the brepjs public API. | Root is 18.x; any breaking marker majors the library immediately. | .release-please-manifest.json |
Root exclude-paths are apps, tests and every packages/* workspace, so a satellite-only or test-only commit never bumps root. A breaking commit touching root docs/, README.md, scripts/, or .github/ still majors root. | Every non-excluded path attributes to the root component, and attribution uses the PR's changed-file list, not the squash commit's (see publish-pipeline.md). | release-please-config.json:8-22 |
Never rename or move a publish-*.yml file without re-registering the npm trusted publisher for that package. | OIDC auth is bound to the exact filename; a rename makes npm publish fail auth. | comments in each publish-*.yml |
Never merge a leaf release PR while the root brepjs release PR is open. | node-workspace pins the leaf to an unpublished brepjs version → npm install ETARGET → Vercel deploys break. Also conflicts the root PR on the shared manifest. | release-please.yml:57-72 |
| Never cancel an in-flight Release Please run. | Cancelling mid-publish leaves a tagged-but-unpublished release; the concurrency group queues, never cancels. | release-please.yml:17-24 |
Manual publish dispatches default to dry_run: true (build-only). A real publish needs -f dry_run=false and a ref. | A bare dispatch is a safe smoke build. | every publish-*.yml |
brepjs-opencascade is always manual. | ~60-min Docker WASM build from ghcr.io/andymai/opencascade.js:v8 (needs GHCR_TOKEN). | publish-opencascade.yml |
Recovery playbook
Root brepjs publish failed (release tagged, npm empty). Do NOT re-run the failed push job — release-please would try to re-tag. Instead re-dispatch the whole workflow in republish mode:
gh workflow run release-please.yml -f republish=trueThis skips the release-please job and runs only publish-brepjs against the current main package.json version. Republish covers root brepjs only.
A leaf publish failed (brepjs-cad/bim/sheetmetal). Re-dispatch that leaf's own publish workflow against the release tag:
gh workflow run publish-brepjs-<pkg>.yml -f dry_run=false --ref <release-tag>brepjs-opencascade needs publishing. Manual only:
gh workflow run publish-opencascade.yml -f dry_run=false --ref <release-tag>Conflicted release PRs (serializer bypassed — e.g. a human merged a leaf early). Not tooled; manual fix. For each still-open release PR: merge main into its branch, take the union of .release-please-manifest.json (keep every package's highest intended version), resolve CHANGELOG/package.json, push. Then let the auto-merge job re-arm on the next run.
npm install/CI fails with ETARGET after a merge. A leaf on main is pinned to a brepjs version not yet on npm. Confirm root actually published (npm view brepjs version); if root is fine, the leaf pin is ahead — publish root first (republish above), or bump the leaf's pin down to a published version and open a fix PR. Related consumer-side symptoms are covered in ci-triage and companion-packages.
Pack validation failed (prepack). Root npm pack/npm publish runs scripts/validate-pack.sh (wired as prepack, with prepublishOnly: npm run build). It fails on more than 500 files or any .d.ts.map sidecar. Inspect with npm pack --dry-run. .d.ts.map files mean declarationMap got re-enabled — check vite.config.ts.
Package publish matrix
| Package | Managed? | Auto-merge? | Auto-publish? | Publish route |
brepjs (root) | yes | yes (first) | yes, inline | release-please.yml job publish-brepjs (OIDC) |
brepjs-cad | yes | yes (after root) | yes, dispatched | publish-brepjs-cad.yml |
brepjs-bim | yes | yes (after root) | yes, dispatched | publish-brepjs-bim.yml |
brepjs-sheetmetal | yes | yes (after root) | yes, dispatched | publish-brepjs-sheetmetal.yml |
brepjs-opencascade | yes | held (manual) | manual only | publish-opencascade.yml (Docker WASM) |
brepjs-voxel-wasm | yes (bumps Cargo.toml) | yes (after root) | no workflow, not on npm | none |
brepjs-viewer | no | n/a | manual | publish-brepjs-viewer.yml |
brepjs-voxel | no | n/a | not published | none |
Build prerequisites baked into the publish workflows: brepjs-cad restores OCCT WASM (scripts/ensure-wasm.sh, 3× retry) then builds root + brepjs-viewer + itself (viewer is a build-time devDep whose dist is bundled into the brepjs-cad build output). bim and sheetmetal build root brepjs first (their vite-plugin-dts needs root's emitted types). brepjs-viewer uses npm ci --ignore-scripts and publishes --access public.
Notes and gotchas
brepjs-vieweris intentionally de-managed from release-please. node-workspace kept re-pinningbrepjs-cad's build-timebrepjs-viewerdevDep ("brepjs-viewer": "*") to viewer's pending unpublished version, breaking monoreponpm ci. Version and publish it by hand viapublish-brepjs-viewer.yml.- The Claude-plugin marketplace version is independent of the npm version. release-please does not bump
packages/brepjs-cad/.claude-plugin/plugin.json; the plugin version and the npmbrepjs-cadversion move separately. - Docs deploy is not release-triggered.
.github/workflows/docs.ymlchains off successful CI onmain(workflow_run); emergency redeploy is a main-onlyworkflow_dispatch. npm unpublishis never available forbrepjs. The published satellites (brepjs-bim,brepjs-families,brepjs-sheetmetal,brepjs-cad) declarebrepjs >=18.x, and npm refuses to unpublish a version that any registry package depends on, even inside the 72-hour window; onlynpm deprecateis offered. A mistaken release therefore stays: annotate its changelog section and GitHub release notes instead (brepjs 20.0.0, 2026-09-21, was a no-op major kept this way). Rewinding the manifest is not an option either, since the version remains on the registry.scripts/publish-all.shis a legacy manual OTP fallback (opencascade → root only,--no-provenance). The OIDC workflows supersede it; use only as a local last resort, and note it does not cover cad/bim/sheetmetal/viewer.
Additional resources
- Commit format and the
!decision:git-pr-workflowskill. - CI job failure modes (npm ci EUSAGE/ETARGET, release PR won't merge, publish red):
ci-triageskill. - Which package to edit and how a change ripples to consumers:
companion-packagesskill. - Canonical deep reference: the inline comments in
.github/workflows/release-please.yml.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

