ruact 0.0.11 → 0.0.13

data/RELEASING.md

@@ -1,209 +1,195 @@
 # Releasing ruact
 
-This document describes the complete release process for `ruact`. Following these steps in order enables any maintainer to cut a release independently.
+A release publishes exactly one artifact: the `ruact` gem, to RubyGems.
 
-The gem and the `vite-plugin-ruact` npm package share the same version number and are **always released together** as a single operation.
+The Vite plugin is not a second artifact. It ships **inside** the gem, under `vendor/javascript/`, together with
+the browser runtime; a generated app imports the plugin by filesystem path off the installed gem. Neither
+bundled package is published, so neither is co-versioned with anything — whatever version number their
+`package.json` files carry is internal to the gem and is not a release. The standalone `vite-plugin-ruact`
+package on npm is a superseded artifact from before the plugin was vendored; no ruact release touches it, and
+nothing this document describes puts anything there.
 
----
+**The pull request is the release.** You write the version into `lib/ruact/version.rb` and stamp the CHANGELOG
+in the same pull request; merging it is what publishes. There is no switch to turn on beforehand and none to
+remember afterwards, and a merge that carries no new version publishes nothing — its content accumulates under
+`[Unreleased]` until somebody decides to cut a release.
+
+That is the whole of this document, and it is why almost every hand step this file used to prescribe has been
+deleted rather than corrected: the workflow builds, uploads and tags, and it writes nothing you would otherwise
+write yourself.
 
-## Pre-Release Checklist
+See [CONTRIBUTING.md](CONTRIBUTING.md) for the checks that run on every push and pull request and how to run
+them locally — this document deliberately describes none of them, so the two cannot drift apart.
+
+---
 
-Before starting, confirm all of the following:
+## Who owns what
 
-- [ ] All CI jobs are green on `main` (rspec matrix, rubocop, yard, benchmark, e2e)
-- [ ] No open issues or PRs labelled `release-blocker`
-- [ ] `gem/ruact.gemspec` has no TODO placeholder values (`summary`, `homepage_uri`, `source_code_uri`, `allowed_push_host` must all be set to real values before `gem build` will succeed)
-- [ ] You have a RubyGems account with push access to `ruact` and an OTP authenticator configured (MFA is required — `rubygems_mfa_required: true`)
-- [ ] You have an npm account with publish access to `vite-plugin-ruact`
-- [ ] You have GPG or SSH commit signing configured (recommended)
+| | Owner |
+|---|---|
+| Whether this merge publishes | you — by putting a new version in the pull request, or not |
+| The version number | you — typed, in `lib/ruact/version.rb` |
+| What the CHANGELOG entry says | you, in the same pull request |
+| The build, the upload to RubyGems, the tag | the `release` job, on the push to `main` |
+| Anything committed to `main` | nobody but a merge — the job pushes a tag and nothing else |
 
 ---
 
-## Version Decision (SemVer)
+## 1. Decide the version
 
-Given the current version `X.Y.Z`, choose the next version:
+SemVer, against the public API: a breaking change to what consumers call (a renamed public method, a changed
+signature, a removed configuration option, an incompatible change to the Flight wire format) is a major; a
+backwards-compatible feature is a minor; everything else is a patch.
 
-| Change type | Version bump | Example |
-|---|---|---|
-| Breaking change (see below) | Major: `X+1.0.0` | `0.1.0` → `1.0.0` |
-| New feature, backwards-compatible | Minor: `X.Y+1.0` | `0.1.0` → `0.2.0` |
-| Bug fix, patch | Patch: `X.Y.Z+1` | `0.1.0` → `0.1.1` |
+Nothing computes this for you and nothing defaults. That is deliberate: the number used to be derived from a
+default plus a marker in a commit message, which meant a minor could arrive as a side effect of how a merge was
+worded — and the first one would have landed on the version this project has reserved for a milestone it has
+not reached.
 
-**What counts as a breaking change**: any change to the public API that requires consumers to update their code — e.g. renaming a public method, changing method signatures, removing a configuration option, or changing the Flight wire format in a non-backwards-compatible way.
+A minor or a major also moves the supported-versions table in [SECURITY.md](SECURITY.md). Do it in the same
+pull request; nothing checks it.
 
 ---
 
-## Release Steps
-
-### 1. Create a release branch
+## 2. Prepare the release
 
 ```bash
-git checkout -b release/v{X.Y.Z}
+bin/release X.Y.Z
 ```
 
-### 2. Bump the gem version
+It refuses a dirty checkout, and one that is not `main` exactly as the remote has it — a branch is never
+*behind* `main` either, and cutting a release from one would put whatever it carries into the release. It
+refuses a version that is not one step from the current one, and one that is already tagged. Then it writes `lib/ruact/version.rb`, re-resolves `Gemfile.lock` against
+it, moves the accumulated `[Unreleased]` content in [CHANGELOG.md](CHANGELOG.md) under a dated heading, opens a
+fresh empty `[Unreleased]`, rewrites both link references, proves the result against the changelog checks and
+the release gate, commits, pushes, and opens the pull request.
 
-Edit `gem/lib/ruact/version.rb`:
+**The pull-request body it writes is the checklist**, with the version already substituted. There is no
+checklist document in this repository on purpose: a checklist is a second copy of the process in the
+imperative, and it rots the way every other second copy does. This one is generated by the thing that performs
+the process, on every release.
 
-```ruby
-module Ruact
-  VERSION = "{X.Y.Z}"
-end
-```
+You can do all of it by hand — the script performs no step you could not — but then you own the parts it
+proves, and the gate on the pull request is where you find out.
 
-### 3. Bump the npm package version
+CHANGELOG.md deserves one warning of its own, because it has three readers who share no directory: this
+repository, a `.gem` unpacked on somebody's disk, and the generated changelog page on the documentation site.
+An entry may name a file but must not **link** one relatively, because a target that resolves here 404s in the
+other two. Absolute URLs only, or no link at all.
 
-Edit `packages/vite-plugin-ruact/package.json`:
+---
 
-```json
-{
-  "version": "{X.Y.Z}"
-}
-```
+## 3. Merge
 
-### 4. Update `gem/CHANGELOG.md`
+On the resulting push to `main`, the `release` job — which waits on every other job in the workflow — asks one
+question: **does `lib/ruact/version.rb` name a version that has no tag?**
 
-1. Move all items under `## [Unreleased]` into a new section `## [{X.Y.Z}] - {YYYY-MM-DD}`.
-2. Add a new empty `## [Unreleased]` section at the very top (above the new release section).
-3. Add or update the link footer at the bottom:
-   ```
-   [Unreleased]: https://github.com/luizcg/ruact/compare/v{X.Y.Z}...HEAD
-   [{X.Y.Z}]: https://github.com/luizcg/ruact/compare/v{PREV}...v{X.Y.Z}
-   ```
-4. If this release contains breaking changes, ensure the section includes a `[BREAKING]` subsection with a **Migration Guide** (see "Breaking Changes" section below).
+If it does not, the job reports that there is nothing to publish and ends green. That is the ordinary case;
+most merges are not releases.
 
-### 5. Update `packages/vite-plugin-ruact/CHANGELOG.md`
+If it does, the job authenticates to RubyGems through Trusted Publishing (OIDC) — a short-lived credential
+minted for that run, no stored secret, nothing interactive — then builds the gem, uploads it, and **tags last**.
 
-Same format as step 4 for the npm package changelog.
+**Why the tag comes last.** The tag is the record of a publish that finished. An upload that fails leaves no
+tag, so the version is still untagged, so the next green push to `main` tries again — automatically, with
+nothing to unwind and nobody to remember. The cost of that order is a re-run that meets a version already on
+RubyGems, which is why a duplicate-version rejection is treated as *already done* rather than as a failure.
 
-### 6. Commit the release
+**Why a question about state rather than about this push.** A trigger that fired on "the version changed in
+this push" would be lost forever whenever no run is created for a push — which happens, merge commits
+included. The version would then say one thing, RubyGems another, and the next release would skip the number
+entirely. Asking about state instead makes the job idempotent and self-healing: run it twice and the second
+does nothing; miss it once and the next green push repairs it.
 
-```bash
-git add gem/lib/ruact/version.rb \
-        packages/vite-plugin-ruact/package.json \
-        gem/CHANGELOG.md \
-        packages/vite-plugin-ruact/CHANGELOG.md
-git commit -m "Release v{X.Y.Z}"
-```
+---
 
-### 7. Push the release branch and open a PR
+## 4. Verify
 
 ```bash
-git push origin release/v{X.Y.Z}
+curl -s https://rubygems.org/api/v1/versions/ruact/latest.json
 ```
 
-Open a PR from `release/v{X.Y.Z}` → `main`. Wait for CI to go green before continuing.
+Use that endpoint. The other one — `/gems/ruact.json` — is CDN-cached and keeps serving the previous version
+for minutes after a successful publish, which reads exactly like a release that did not happen.
 
-### 8. Merge, verify CI, and tag
-
-Merge the PR. Confirm all CI jobs pass on the merge commit, then tag the verified merge commit:
+---
 
-```bash
-git checkout main
-git pull origin main
-git tag v{X.Y.Z}
-git push origin v{X.Y.Z}
-```
+## 5. When nothing was published and nothing said so
 
-> **Why tag after merge?** Tagging after CI passes on the merge commit ensures the tag always points to a verified, releasable commit. Tagging the branch commit before merge risks tagging code that fails CI after merge.
+From the outside, a release that did not happen and one that did look identical until you check RubyGems. Every
+case below shares one recovery, and it is the reason the trigger has the shape it has: **the version is still
+untagged, so the next green push to `main` publishes it.** Nothing has to be unwound and nothing has to be
+remembered.
 
-### 9. Publish the gem to RubyGems
+**A job the `release` job waits on went red on the push to `main`.** The release job never ran, the merge has
+landed, and no error anywhere says "no release happened". The run that matters is the one on `main`, not the
+one on the pull request:
 
 ```bash
-cd gem
-gem build ruact.gemspec
-gem push ruact-{X.Y.Z}.gem
-# Enter OTP when prompted (MFA is required)
-rm ruact-{X.Y.Z}.gem
+gh run list --branch main -L 3
+gh run rerun <run-id> --failed
 ```
 
-> **Note**: `spec.files` in the gemspec is populated via `git ls-files -z`. The files `CHANGELOG.md`, `RELEASING.md`, and `SECURITY.md` must be committed to git to appear in the gem tarball. Verify with:
-> ```bash
-> gem contents ruact-{X.Y.Z} | grep -E 'CHANGELOG|RELEASING|SECURITY'
-> ```
+**No run was created for the push at all.** Same state, same repair; there is simply no run to re-run. Push
+something green to `main` — the next merge does it on its own.
 
-### 10. Publish the npm package
+**The upload failed, or Trusted Publishing rejected the run.** Nothing was tagged, because the tag is written
+after the upload. Fix the cause and let the next green push reconcile it.
 
-```bash
-cd packages/vite-plugin-ruact
-npm publish
-```
+**The version is on RubyGems but the API still shows the old one.** CDN cache; see §4.
 
-### 11. Create a GitHub Release
+**A release was prepared and should not go out.** If it has not merged, close the pull request — nothing was
+released and nothing has to be undone. If it has, see §6.
 
-1. Go to [Releases](https://github.com/luizcg/ruact/releases/new)
-2. Select tag `v{X.Y.Z}`
-3. Title: `v{X.Y.Z}`
-4. Body: paste the `## [{X.Y.Z}]` section from `gem/CHANGELOG.md`
-5. Publish
+**The suite is red on `main` because the record and the code disagree.** The changelog checks run in a job the
+release job waits on, so once `lib/ruact/version.rb` and `CHANGELOG.md` stop naming the same version, **every**
+later release waits too. The failure names which of the two moved.
 
 ---
 
-## Breaking Changes
-
-When a release contains a breaking change:
+## 6. Stopping a release that has already merged
 
-1. Bump the **major** version (e.g. `0.1.0` → `1.0.0`).
-2. Mark the CHANGELOG entry with `[BREAKING]` and include a **Migration Guide** sub-section:
+Publication is irreversible, so there is a stop — a repository variable, read by the job itself:
 
-   ```markdown
-   ## [1.0.0] - YYYY-MM-DD
+```bash
+gh variable set RUACT_RELEASE_HALT -b stop -R luizcg/ruact
+```
 
-   ### Changed
-   - [BREAKING] `Ruact::Serializable.ruact_props` now rejects non-Symbol arguments at class-load time
+Any non-empty value stops it. Unset — the normal, permanent state — publishes.
 
-   #### Migration Guide
+**A halted run fails red, naming the version it refused.** That is the point of it: the stop is a state
+somebody has to undo, and a stop that produced a quiet, successful-looking run would suppress every later
+release invisibly. This one reddens `main` on the next merge instead, which is a thing you find out about.
 
-   **Before:**
-   ```ruby
-   class Post
-     include Ruact::Serializable
-     ruact_props "id", "title"   # strings silently coerced
-   end
-   ```
-   **After:**
-   ```ruby
-   class Post
-     include Ruact::Serializable
-     ruact_props :id, :title     # must be Symbols
-   end
-   ```
-   ```
+```bash
+gh variable delete RUACT_RELEASE_HALT -R luizcg/ruact
+```
 
-3. Announce the breaking change prominently in the GitHub Release body.
+The version is still untagged while the halt is in place, so clearing it does not require another bump: the
+next green push publishes what was held.
 
 ---
 
-## Rollback
+## 7. Rollback
 
-If a release contains a critical defect and must be pulled:
+If a published version has a critical defect:
 
-**RubyGems** (within 30 days):
 ```bash
-gem yank ruact -v {X.Y.Z}
+gem yank ruact -v X.Y.Z
 ```
 
-**npm** (within 72 hours):
-```bash
-npm unpublish vite-plugin-ruact@{X.Y.Z}
-```
+This is the one RubyGems command still run by a person rather than by the workflow, and it is the one place the
+"nothing interactive" of §3 does not apply: the gem declares `rubygems_mfa_required`, so yanking needs your own
+RubyGems credential and a one-time code. The workflow's OIDC credential is minted for its own run and is no
+help here.
 
-After yanking, cut a patch release (`{X.Y.Z+1}`) with the fix immediately. Do not leave the version yanked without a replacement.
+Then cut a patch release with the fix immediately. A yanked version with no replacement leaves anyone who
+pinned it with nothing to move to. There is nothing to unpublish anywhere else — this process publishes to
+RubyGems only.
 
 ---
 
-## Troubleshooting
-
-**`gem push` fails with "MFA required"**: Run `gem signin` first and ensure your OTP authenticator is set up at https://rubygems.org/settings/edit.
+## Where this ends
 
-**Files missing from gem tarball**: The gemspec uses `git ls-files -z`. Ensure all new files (e.g. `CHANGELOG.md`) are committed to git before running `gem build`.
-
-**CI fails on release branch**: Fix the issue on the release branch and push the fix. Wait for CI to pass before tagging. If you already pushed a tag pointing to a broken commit, delete it and recreate after the fix:
-```bash
-git tag -d v{X.Y.Z}                        # delete local tag
-git push origin :refs/tags/v{X.Y.Z}        # delete remote tag
-# fix the issue, merge, then re-tag from the correct commit
-git checkout main && git pull origin main
-git tag v{X.Y.Z} && git push origin v{X.Y.Z}
-```
-Do not use `git push --force` on tags — force-pushing a tag rewrite history for anyone who has already fetched it.
+The gem is published and verified. The rest of a release — the private planning side — is outside this
+repository and outside this document.