draft-release

name	draft-release
description	Cut a new release of this Spicetify extension — work out the version bump from what has merged since the last tag, write the release notes in this repo's house style, commit the version bump, then tag and draft the GitHub release. Use when the user wants to release, cut a version, bump the version, or draft release notes.

Drafting a release

The thing users actually install is hidePodcasts.js committed at the repo root on main. push.yml rebuilds it on every push to main and auto-commits it as "Built new version", and the README tells people to copy that file into their Extensions folder; Marketplace reads manifest.json from main too. So main is released the moment anything merges — the tag and the GitHub release are documentation written after the fact, not the mechanism.

There is no dist branch, despite push.yml being titled "Push new version to dist branch". Do not go looking for one.

One practical consequence: there is no "unrelease". If the notes are wrong you edit them; if the code is wrong you ship another commit.

The shape of it

1	Gather the facts
2	Propose the version, confirm with the user
3	Draft the notes, show them to the user
4	Commit the version bump, ask before pushing to main
5	Verify the committed bundle matches main
6	Tag vX.Y.Z
7	gh release create --draft
—	The user publishes

One hard stop: never publish the release. That is the user's call. Step 4 pushes straight to main, so confirm before doing it.

1. Gather the facts

./.claude/skills/draft-release/gather.sh

Read-only, safe to run any time. It prints the last tag, every commit and PR since it, each PR's author and labels, detected new contributors, and the Spotify/Spicetify versions from the running client.

If it warns that package.json disagrees with the last tag, stop and work out why before bumping — usually it means a bump was committed but never tagged, and the fix is to tag the existing commit rather than bump again.

2. Propose the version

Semver against what the PRs actually do, not against their fix:/feat: prefixes:

• minor — any new user-facing capability. 3.2.0 was a minor for hiding podcasts and audiobooks in search results.
• patch — fixes, dependency bumps, internals only. 3.1.1–3.1.4 were all patches.
• major — a breaking change to how the extension is configured or installed. 3.0.0 was the last one. Ask before assuming it.

A Spotify-breakage fix is a patch even though it is the whole reason for the release — that is what 3.1.2 and 3.1.3 were.

Say which PRs drove the call, then confirm the number with the user before touching anything.

3. Draft the notes

This is the part that takes judgement — everything else is mechanical. Read the actual PRs. Do not just reformat PR titles.

The current format is hand-written prose sections, with GitHub's generated list appended below a rule. gh release view v3.2.0 is the model:

Spotify 1.2.94 renamed and restructured several things the extension relied on, and
podcasts had started reappearing on the search pages. This release restores that, and
extends hiding to search results.

## Fixed

* **Podcast and audiobook category cards on the Search page were showing again.** Spotify
  replaced the class those rules targeted with a generated one, so they silently stopped
  matching. They're now matched on URL, which has stayed stable across releases.

## Added

* **Podcasts and episodes are now hidden in search results**, not just the filter pill.

## Internal

* Toolchain modernized: ESLint 10 (flat config), pnpm 11, Node 24.

## Known limitations

Home page shelves are unchanged in this release. If podcasts still appear there, try
**aggressive mode** in the profile menu, and please include your shelf IDs in an issue.

---

## What's Changed
...generated by GitHub...

Note this is a deliberate step up from 3.1.0–3.1.4, which shipped the bare generated list with no prose at all. Do not copy that older pattern from gh release view; the shape above is the current convention.

The rules that actually matter:

An unheaded opening paragraph saying what the release is for. A reader deciding whether to update should need nothing else. Where the cause is Spotify's doing rather than ours, say so — it explains why a working extension broke on its own.

Group under ## Fixed / ## Added / ## Internal, and drop any section with nothing in it. ## Known limitations is worth keeping whenever something obvious is still broken — it heads off duplicate issues, which is what it did for home shelves in 3.2.0.

Bullets are per user-visible symptom, not per PR. #208 produced several bullets in 3.2.0 because it fixed several distinct symptoms. One PR can be several bullets; several PRs can collapse into one.

Lead each bullet with a bold sentence naming the symptom, then explain the cause. "Nothing was being hidden on either search page. The extension waits for a page to finish loading, and the markers it waited on no longer exist" — the reader knows the extension, not the codebase.

## Internal gets one rolled-up line, not a bullet per chore PR. Dependabot bumps collapse into it, or vanish entirely if that is the whole release. Do not give the version bump itself a line.

Do not hand-write per-bullet by @author in <url> credits. GitHub's generated ## What's Changed section already credits every PR and its author, including Dependabot, and duplicating it in the prose is what 3.2.0 avoided. Mention a contributor by name in the prose only when the story warrants it.

There is no standing "Tested against" line — 3.2.0 cites the Spotify version inline in the sentence about what broke. gather.sh prints the running client's versions for you to work in where relevant.

Because the hiding rules depend on Spotify's DOM, a release that fixes breakage is worth verifying in a live client before the notes claim it is fixed. That is the spicetify-drive skill — and note its hard rule: never play a podcast or audiobook while testing.

Show the user the draft and take edits before committing anything.

4. Commit the version bump

Only package.json changes. manifest.json carries no version, and hidePodcasts.js is regenerated by CI.

Bumps land as a direct commit to main whose entire message is the version number — 3.2.0, 3.1.4, 3.1.3. Not a chore: prefix, not a PR:

git checkout main && git pull
# edit "version" in package.json
git commit -am "X.Y.Z"

Ask before pushing — this goes straight to main with no review, and pushing is what makes it a release.

git push origin main

Then wait for push.yml to finish before step 5.

5. Verify the committed bundle is current

The tag should point at something users can already install.

./.claude/skills/draft-release/verify-build.sh

It ends in a single PASS — safe to tag. / FAIL — do not tag… verdict, matching its exit code. Read that line rather than the section above it: the content check can legitimately print "the committed bundle matches" while an earlier check has already failed, so a mid-script pass is not an all-clear.

Do not judge this by whether a "Built new version" commit followed the bump. push.yml ends in git-auto-commit-action, which only commits when the built output changes. The version is not embedded in the bundle, so a bump changes nothing and the workflow succeeds while committing nothing. v3.2.0 is exactly this: 8546bb7 is a lone one-line package.json change with no rebuild after it, and the bundle was correct the whole time.

So the script checks content: it confirms a successful push.yml run for main's current SHA, rebuilds out-of-tree with spicetify-creator --minify, and diffs against the artifact committed on origin/main. The build is byte-reproducible, so a match is exact and any difference is a real problem — stop and work out why before tagging.

It builds to a temp directory on purpose. pnpm build:local writes to the repo root and would overwrite the tracked artifact you are trying to compare against.

6. Tag

Tag what users can actually install — the commit whose build is on main. Usually that is the version bump, because the bump is usually the last thing to land.

It is not a rule. If anything merged after the bump, tag that instead:

git log --oneline -5 origin/main

Recent history has both: v3.1.4 and v3.2.0 sit on their bump commits, while v3.1.2 and v3.1.3 sit on the "Built new version" commit that followed.

git fetch origin
git tag vX.Y.Z <sha>
git push origin vX.Y.Z

Plain lightweight tags. v prefix on the tag — v3.1.0 through v3.2.0 all carry it. Older tags (3.0.0, 2.8.0) do not, and v.2.7.2 has a stray dot; ignore both, gather.sh already handles them.

7. Create the draft

The release title is the bare version, without the v — tag v3.2.0, title 3.2.0. gh defaults the title to the tag, so pass --title explicitly or you will publish a v3.2.0-titled release that breaks the pattern.

Write the prose to notes.md in the scratchpad, not the repo — this project keeps no CHANGELOG, and the release body is the only changelog there is.

gh release create vX.Y.Z --draft --title "X.Y.Z" \
  --notes "$(cat notes.md)" --generate-notes

--generate-notes appends GitHub's ## What's Changed, ## New Contributors and **Full Changelog** below your prose, which is how 3.2.0's body was built. Use --notes, not --notes-file: gh documents the prepending behaviour for --notes only.

No release assets. Unlike the sibling name-that-tune repo, no release here has ever carried a zip — 3.0.0 through 3.2.0 all have none. Users copy hidePodcasts.js from main or install through Marketplace. Do not invent one.

Confirm the body came out right before handing over:

gh release view vX.Y.Z --json isDraft,name,body --jq '{isDraft, name, hasGenerated: (.body | contains("What'"'"'s Changed"))}'

If hasGenerated is false, the flags did not combine — recreate with the prose and gh api-generated notes pasted together by hand.

Give the user the URL and let them publish.

Gotchas

• gather.sh reads origin/main, not your local main. It fetches first, so a stale local checkout will not silently produce short notes.
• "Built new version" commits are noise in the commit range. They are CI committing the bundle; they never get a bullet.
• Version bump commits land in the next release's commit range — a bare 3.2.0 message with no PR number — and must be excluded from its notes.
• New-contributor detection assumes lowest PR number = first contribution. True for this repo's history; it would misfire on someone whose first PR was closed and reopened.
• Squash merges renumber history. Confirm the squashed content matches (git diff <old-commit> origin/main should be empty) and then rebase, rather than resolving by hand.