@bensandee/tooling 0.79.0 → 0.81.0

package/README.md

@@ -174,7 +174,7 @@ Renovate moves the pinned `node` version, but only within its current major -- a
 
 | Command                          | Description                                                                                                                                                                                                                                                         |
 | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `tooling release:changesets`     | Changesets version/publish for Forgejo CI. Flags: `--dry-run`, `--verbose`. Env: `FORGEJO_SERVER_URL`, `FORGEJO_REPOSITORY`, `RELEASE_TOKEN`.                                                                                                                       |
+| `tooling release:changesets`     | Changesets version/publish for Forgejo CI. A prerelease package moves only its own `<name>@<version>` tag; `<name>@latest`, `<name>@vX` and `<name>@vX.Y` move only for a release (see `release:simple`). Flags: `--dry-run`, `--verbose`. Env: `FORGEJO_SERVER_URL`, `FORGEJO_REPOSITORY`, `RELEASE_TOKEN`.                                                                                                                       |
 | `tooling release:simple`         | Streamlined release using commit-and-tag-version. Flags: `--release-as`, `--first-release`, `--prerelease`, `--verbose`. Env: `RELEASE_TOKEN` (required on every platform).                                                                                         |
 | `tooling release:trigger`        | Trigger a release workflow.                                                                                                                                                                                                                                         |
 | `tooling workflow:dispatch`      | Dispatch a `workflow_dispatch` event for any workflow in any repo on the same git host. Flags: `--repo`, `--workflow` (required), `--ref`, `--input key=value` (repeatable).                                                                                        |
@@ -208,6 +208,8 @@ tooling release:simple --release-as major --prerelease beta  # -> 2.0.0-beta.0
 
 The generated release workflow exposes these as optional `workflow_dispatch` inputs (`bump` and `prerelease`), so bumps can also be controlled from the CI UI.
 
+A prerelease publishes its exact tag (`v2.0.0-beta.0`) and nothing else: `latest`, `vX` and `vX.Y` move only for a release, and each one a prerelease leaves in place is logged with its reason. The forge release created for a prerelease tag is flagged as a prerelease, so the forge's Latest pointer still names the last real release. The same holds for the `<name>@latest`, `<name>@vX` and `<name>@vX.Y` tags `release:changesets` maintains in a monorepo, where a prerelease package moves only its own `<name>@1.2.3-beta.0` tag while a release package published in the same run still advances its three floating tags.
+
 **Authentication:** `release:simple` requires `RELEASE_TOKEN` (a Personal Access Token with write access on the target forge) on every platform -- Forgejo, GitHub, and GitHub Enterprise alike. The runner's auto-injected token (`github.token` / Forgejo Actions' internal auth) is never used: `actions/checkout@v6` writes that token to git config as an `http.<serverUrl>/.extraheader`, which silently overrides URL-embedded credentials and authenticates pushes as the runner pseudo-user. On Forgejo that pseudo-user is `uid=-2`, which fails the pre-receive hook (`Internal Server Error`); on GitHub Enterprise the same shape can mask custom hook rejections. `release:simple` actively unsets the extraheader and rewrites the remote URL with `RELEASE_TOKEN` before pushing.
 
 GitHub consumers that previously relied on `github.token` must mint a PAT (scope: `contents: write`) and store it as the `RELEASE_TOKEN` secret on the repo or org.
@@ -467,9 +469,11 @@ To give individual packages a standalone `image:build` script for local testing:
 
 #### `docker:publish`
 
-Runs `docker:build` for all packages, then logs in to the registry, tags each image with semver variants from its own `version` field, pushes all tags, and logs out.
+Runs `docker:build` for all packages, then logs in to the registry, tags each image with semver variants from its own `version` field, pushes the tags this run is allowed to move, and logs out.
+
+Tags generated per package: `latest`, `vX.Y.Z` (or `vX.Y.Z-<pre>` for a prerelease -- the version as written, with build metadata dropped), `vX.Y`, `vX`
 
-Tags generated per package: `latest`, `vX.Y.Z`, `vX.Y`, `vX`
+A prerelease version (`1.2.3-beta.0`) pushes only its own exact tag, which keeps the suffix -- `v1.2.3-beta.0` -- and moves no floating tag; each skipped ref is logged with that reason. Otherwise a floating tag moves forward only: `docker:publish` leaves `latest`, `vX` or `vX.Y` where the registry has it whenever that version is newer than the one being published.
 
 Each package is tagged independently using its own version, so packages in a monorepo can have different release cadences. Packages without a `version` field are rejected at publish time.