[FIX] Pin marketplace install to the v0.2.0 release tag#24
Conversation
The git-subdir source had no ref, so /plugin install fhenix-toolkit pulled whatever was on main's HEAD instead of the tagged release. The version in Discover was just a label with no tie to the installed code. v0.2.0 is byte-identical to main right now, so pinning ref to v0.2.0 makes installs deterministic without changing what anyone gets today, and closes the 'install floats on HEAD' known flaw. While testing the pin locally, found that the bare owner/repo shorthand in the source url resolves to an SSH clone, so installs failed with 'Permission denied (publickey)' for anyone without GitHub SSH keys. Switched the url to the full HTTPS form, which installs cleanly. Tested with a local marketplace add against the real GitHub repo: fresh install lands on the exact sha of v0.2.0 (f6f2e51), and after a ref change, /plugin marketplace update + /plugin update moves the install to the new tag's sha. No remove + re-add needed. Update detection keys off the plugin version though, so a ref bump only propagates when the version bumps with it. The release process bumps both together, and the docs now say so. Also added the ref bump as a fourth version-sync step in the release process, with a note that the ref only resolves once the tag is pushed.
|
Nice catch on the SSH-url resolution - that one bites silently. One suggestion: pin v0.2.0 is an annotated tag that peels to "source": {
"source": "git-subdir",
"url": "https://github.com/FhenixProtocol/fhenix-toolkit.git",
"path": "plugins/fhenix-toolkit",
"ref": "v0.2.0",
"sha": "f6f2e511bb4194c393c4f32829b5b0172eb01782"
}The release process would then bump both together, which fits the version-sync step you already documented. |
A tag can be force-moved, so ref on its own isn't a hard integrity guarantee. Pinning the sha next to it means the install resolves to one exact commit no matter what happens to the tag later. f6f2e51 is the commit v0.2.0 points at, same as main's HEAD right now, so this doesn't change what anyone gets today. It also lines up with what claude-plugins-official does, every git-subdir entry there carries both ref and sha. The thing to watch is the release process. With both set the sha is the effective pin, so a future ref bump that leaves a stale sha would quietly keep installs on the old release. The tagged commit doesn't exist yet when the release PR is written, so the docs now say to bump ref at cut time, pin the sha right after tagging, and move the two together. marketplace.json still parses and the pinned sha matches what v0.2.0 resolves to.
|
Yeah, ref on its own still floats if the tag ever gets force-moved, so pinning the commit is worth doing. Added it as f6f2e51, which is what v0.2.0 points at and where main's HEAD sits right now, so nothing changes about what installs today. Pinning the sha did surface one thing on the release side: with both set the sha is the effective pin, so a future ref bump that leaves a stale sha would quietly keep everyone on this commit instead of the new tag. The tagged commit doesn't exist yet when the release PR goes up, so I wrote the docs to bump ref at cut time and pin the sha right after tagging, and to keep the two moving together. Pushed in 45b0a85. marketplace.json still parses and the sha matches what v0.2.0 resolves to. |
Closes #21
What this does
Adds
ref: "v0.2.0"to thegit-subdirsource inmarketplace.json, so/plugin install fhenix-toolkitresolves to the exact tagged commit instead of floating onmain's HEAD. Went with pinning to the existing v0.2.0 tag rather than waiting for a v0.2.1 cut, since v0.2.0 is byte-identical to main right now. That closes the gap immediately without changing what anyone gets today.Also:
docs/release-process.md: bumpingrefis now the fourth version-sync step on each release cut, with a note that the ref is dangling until the tag is pusheddocs/known-flaws.md: removed the "default install floats on default-branch HEAD" entryCHANGELOG.md: entries under Unreleased for both fixesOne extra find: installs were failing for HTTPS-only users
While testing the pin I hit
Permission denied (publickey)on install. The bareFhenixProtocol/fhenix-toolkitshorthand in the source url gets resolved to an SSH clone (git@github.com:...), so anyone without GitHub SSH keys configured couldn't install at all, independent of this change. Switched the url to the full HTTPS form and installs work cleanly. Worth knowing this was already broken on main for that set of users.Answer to the open question (does
marketplace updatere-read a new ref?)Yes. Tested locally against the real GitHub repo:
ref: "v0.2.0"lands on commitf6f2e51, which is exactlygit rev-list -n1 v0.2.0. The pin works./plugin marketplace updatefollowed by/plugin update fhenix-toolkit. The install moved to the new tag's exact sha (verified againstgit rev-list -n1again). No remove + re-add needed.One caveat that's documented behavior in Claude Code: update detection keys off the plugin version, not the ref. A ref bump with an unchanged version string is silently skipped for existing installs. Not a problem for the release flow since version and ref bump together in the same cut, and the release doc now calls this out explicitly.