docs: describe shared build-specific snapshot publishing

Co-Authored-By: Codex <noreply@openai.com>
2026-10-22 05:15:25 -05:00
2 changed files with 65 additions and 54 deletions
@@ -1,12 +1,19 @@
-# npm publishing
-
-CircleCI publishes `@qrunio/qqq-frontend-core` with npm Trusted Publishing using `kingsrook/qqq-orb@0.6.8` and `cimg/node:24.21`. In the package Settings on npmjs.com, add a **CircleCI** trusted publisher with the values below and explicitly allow **npm publish** (the staged-only default does not run this pipeline). Existing workflow branch filters and dist-tags remain in place.
-
-| npm field | Value |
-| --- | --- |
-| Organization ID | `bb329fea-03cd-4fb5-b530-15e85703598d` |
-| Project ID | `5bd1e544-282a-4080-afc1-36ffdebf5487` |
-| Pipeline definition ID | `3bd87740-26e6-5f18-8600-10685a13a81e` |
-| VCS origin | `github.com/QRun-IO/qqq-frontend-core` |
-
-These are public identifiers, not credentials. The job obtains a short-lived npm-audience OIDC identity only for publication, so no new `NPM_TOKEN` is needed. Do not use `npm whoami` or a publish dry run as proof: verify the real immutable version at npm and install it in a clean consumer. Once that succeeds, remove obsolete token access only after checking its other consumers. CircleCI Trusted Publishing currently does not attach npm provenance attestations. See [npm documentation](https://docs.npmjs.com/trusted-publishers/).
+# npm publishing
+
+CircleCI publishes `@qrunio/qqq-frontend-core` with npm Trusted Publishing through the shared `frontend-core` profile in `.qqq-ci.yml`. The canonical caller tracks `kingsrook/qqq-orb@0.8` and uses `cimg/node:24.21`. Publishing logic lives in the orb, not in a repository-specific workflow. In the package Settings on npmjs.com, add a **CircleCI** trusted publisher with the values below and explicitly allow **npm publish** (the staged-only default does not run this pipeline).
+
+Develop snapshots use build-specific versions such as `0.40.28-SNAPSHOT.1234`
+and the npm `snapshot` dist-tag. The version is calculated in the publishing
+workspace; the job does not push a version-only `[skip ci]` commit back to
+`develop`. Required checks therefore stay attached to the source head being
+published. See [version management](version-management.md) and the
+[shared orb policy](https://github.com/QRun-IO/qqq-orb/blob/main/docs/GENERATED-PIPELINES.md#node-snapshot-versions).
+
+| npm field | Value |
+| --- | --- |
+| Organization ID | `bb329fea-03cd-4fb5-b530-15e85703598d` |
+| Project ID | `5bd1e544-282a-4080-afc1-36ffdebf5487` |
+| Pipeline definition ID | `3bd87740-26e6-5f18-8600-10685a13a81e` |
+| VCS origin | `github.com/QRun-IO/qqq-frontend-core` |
+
+These are public identifiers, not credentials. The job obtains a short-lived npm-audience OIDC identity only for publication, so no new `NPM_TOKEN` is needed. Do not use `npm whoami` or a publish dry run as proof: verify the real immutable version at npm and install it in a clean consumer. Once that succeeds, remove obsolete token access only after checking its other consumers. CircleCI Trusted Publishing currently does not attach npm provenance attestations. See [npm documentation](https://docs.npmjs.com/trusted-publishers/).
@@ -1,42 +1,46 @@
-# Version Management
-
-## Current Versions (as of 2026-01-12)
-
-| Package | Version | Registry |
-|---------|---------|----------|
-| `@qrunio/qqq-frontend-core` | 0.40.1-SNAPSHOT | npm |
-| `qqq-frontend-material-dashboard` | 0.40.1-SNAPSHOT | Maven Central |
-| `qqq` (backend) | 0.40.0-SNAPSHOT | Maven Central |
-
-## Frontend vs Backend Versioning
-
-Frontend repos can version independently from the backend. In `qqq-frontend-material-dashboard`:
-
-```xml
-<properties>
-  <revision>0.40.1-SNAPSHOT</revision>      <!-- This artifact's version -->
-  <qqq.version>0.40.0-SNAPSHOT</qqq.version> <!-- Backend dependency version -->
-</properties>
-```
-
-This allows frontend-only releases without requiring a full backend release.
-
-## Version Bump Process
-
-### qqq-frontend-core (npm)
-1. Update `version` in `package.json`
-2. Push to develop branch
-3. CI automatically publishes to npm
-
-### qqq-frontend-material-dashboard (Maven)
-1. Update `revision` property in `pom.xml`
-2. Optionally update `qqq.version` if backend changes needed
-3. Push to develop branch
-4. CI runs Playwright tests + publishes to Maven Central
-
-## CI/CD Orb Behavior
-
-The `kingsrook/qqq-orb` `calculate_version.sh` script:
- For develop branch with existing SNAPSHOT: keeps current version
- Only bumps version on release merges or RC versions
- Each repo manages its own version independently
+# Version Management
+
+## Historical Versions (2026-01-12)
+
+| Package | Version | Registry |
+|---------|---------|----------|
+| `@qrunio/qqq-frontend-core` | 0.40.1-SNAPSHOT | npm |
+| `qqq-frontend-material-dashboard` | 0.40.1-SNAPSHOT | Maven Central |
+| `qqq` (backend) | 0.40.0-SNAPSHOT | Maven Central |
+
+## Frontend vs Backend Versioning
+
+Frontend repos can version independently from the backend. In `qqq-frontend-material-dashboard`:
+
+```xml
+<properties>
+  <revision>0.40.1-SNAPSHOT</revision>      <!-- This artifact's version -->
+  <qqq.version>0.40.0-SNAPSHOT</qqq.version> <!-- Backend dependency version -->
+</properties>
+```
+
+This allows frontend-only releases without requiring a full backend release.
+
+## Version Bump Process
+
+### qqq-frontend-core (npm)
+1. Merge a verified source change to `develop` through the shared required checks.
+2. The orb calculates `MAJOR.MINOR.NEXT_PATCH-SNAPSHOT.CIRCLE_BUILD_NUM` from the source package version and the unique CircleCI job number. For example, source `0.40.27-SNAPSHOT` in job 1234 publishes `0.40.28-SNAPSHOT.1234`.
+3. CI builds and publishes that immutable npm version under the `snapshot` dist-tag. It keeps the source branch unchanged; no snapshot version commit or manual per-build version bump is needed.
+4. Verify the published version and install it in a clean consumer before claiming publication success. CI-only declaration updates may run verification without publishing.
+
+Stable, RC and hotfix publication keep their existing shared orb policies. A
+snapshot publication is not a stable release.
+
+### qqq-frontend-material-dashboard (Maven)
+1. Update `revision` property in `pom.xml`
+2. Optionally update `qqq.version` if backend changes needed
+3. Push to develop branch
+4. CI runs Playwright tests + publishes to Maven Central
+
+## CI/CD Orb Behavior
+
+For Maven projects, the shared orb's `calculate_version.sh` script:
+- For develop branch with existing SNAPSHOT: keeps current version
+- Only bumps version on release merges or RC versions
+- Each repo manages its own version independently