Skip to content

Commit dc9d084

Browse files
authored
docs(release): correct the tap_migrations.json format and document the hand-off (#134)
Squash-merged per CONTRIBUTING.md.
1 parent 2f185bc commit dc9d084

2 files changed

Lines changed: 33 additions & 10 deletions

File tree

‎docs/installation.md‎

Lines changed: 11 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -47,9 +47,17 @@ holds the cask and is auto-pushed by GoReleaser on every
4747
> **Upgrading from the old formula:** `nodeup` shipped as a Homebrew
4848
> formula up to v1.2.1 and switched to a cask in v1.2.2. The command
4949
> is unchanged (`brew install dipto0321/tap/nodeup` still works), but
50-
> Homebrew treats a formula and a cask as different packages — so if
51-
> you installed the formula, run `brew uninstall --formula nodeup`
52-
> after upgrading the tap.
50+
> Homebrew treats a formula and a cask as different packages. The tap
51+
> carries a `tap_migrations.json`, so **`brew update` performs the
52+
> hand-off for you**: it unlinks the old keg, installs the cask, and
53+
> tells you to run
54+
> `brew uninstall --formula --force nodeup` to clean up the old keg.
55+
> If you'd rather do it by hand:
56+
>
57+
> ```bash
58+
> brew uninstall --formula --force nodeup
59+
> brew install dipto0321/tap/nodeup
60+
> ```
5361
5462
**Tradeoffs:** upgrades happen via `brew upgrade`, which all Homebrew
5563
users already run on a schedule. The install lives in Homebrew's

‎docs/release-checklist.md‎

Lines changed: 22 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -54,24 +54,39 @@ prefers casks for "download a binary and put it on PATH" distributions.
5454
Homebrew treats a formula and a cask of the same name as two
5555
different packages, so the old formula has to be removed from the tap
5656
by hand, and the tap needs a `tap_migrations.json` so Homebrew can
57-
perform the hand-off automatically on `brew update`:
57+
perform the hand-off automatically on `brew update`.
58+
59+
The file is a **flat** `{old_name: new_name}` hash (not a nested
60+
`{"Formula": {...}}` object — Homebrew's `Tap#tap_migrations` parses
61+
it with `JSON.parse(...read)` and looks the name up directly):
5862

5963
```json
6064
{
61-
"Formula": {
62-
"nodeup": "Cask",
63-
"nodeup@1.2.1": "Cask"
64-
}
65+
"nodeup": "nodeup"
6566
}
6667
```
6768

6869
- [ ] `tap_migrations.json` present in `dipto0321/homebrew-tap` with
69-
the `Formula → Cask` mapping for `nodeup`
70+
the flat `{"nodeup": "nodeup"}` mapping
7071
- [ ] The old `nodeup.rb` formula removed from the tap (GoReleaser
7172
pushes the cask but does not delete the formula)
73+
- [ ] The formula removal, the `tap_migrations.json`, and the cask all
74+
land in the **same** update cycle — with the formula still
75+
present, `brew install dipto0321/tap/nodeup` resolves to the
76+
*formula* (Homebrew prints "Treating ... as a formula"), so the
77+
cask's quarantine-stripping hook would never reach users
7278
- [ ] `brew install dipto0321/tap/nodeup` verified on a scratch tap
7379
- [ ] Existing formula installs get the hand-off on `brew update`
74-
(Homebrew tells them to `brew uninstall --formula --force nodeup`)
80+
(Homebrew unlinks the old keg, installs the cask, and tells the
81+
user to `brew uninstall --formula --force nodeup`)
82+
83+
> **Checksum trap.** Do not hand-edit the sha256 values in the cask
84+
> from a local `goreleaser --snapshot` render — Go builds are not
85+
> byte-reproducible, so the snapshot hashes will not match the
86+
> published release assets and the install fails with "Cask nodeup
87+
> reports different checksum". Generate the cask from the release's own
88+
> `checksums.txt`, or let GoReleaser push it at tag time (which is
89+
> what actually happens for every release after v1.2.2).
7590
7691
### Publishing `nodeupx` (`nodeup-npm/`) to the npm registry
7792

0 commit comments

Comments
 (0)