From 26ff8eeb231a21cc9361ccdf753a3fb2bda06459 Mon Sep 17 00:00:00 2001 From: Sebastian Iancu Date: Tue, 25 Aug 2026 16:13:52 +0300 Subject: [PATCH] docs(versioning): a release is not live until the marketplace entry moves The catalog pins entries to a release tag, so tagging here ships nothing until version and source.ref move. Added as release step 8. Co-authored-by: Cursor --- AGENTS.md | 2 +- CHANGELOG.md | 5 +++++ docs/versioning.md | 19 +++++++++++++++++-- 3 files changed, 23 insertions(+), 3 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index efda3ac..7ada582 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -160,4 +160,4 @@ Use feature branches and pull requests. Validation runs on every push/PR. - **Don't duplicate the `sdd` plugin.** This plugin owns prose and content; requirements, RFC-2119 specifications, ADRs, and traceability belong to `sdd`. When extending, resist adding a spec-authoring or traceability skill that competes. - **`claude plugin ` prints the general help and exits 0.** It does not error, so a non-existent command reads as working in a script or a doc review. `claude plugin add` does not exist and never did — the real subcommands are `details disable enable eval init install list marketplace prune tag uninstall update validate`. Verify a CLI invocation by running it and checking behaviour, not just the exit code. - **There is no local-path *install*.** `claude --plugin-dir ` loads a working copy for **one session** (repeatable; also takes a `.zip`), and is the dogfooding path. `claude plugin install` resolves names from a configured marketplace, and `claude plugin marketplace add ` needs a `.claude-plugin/marketplace.json`, which a single-plugin repo does not have. A persistent install therefore goes through the marketplace. -- **Register in the marketplace separately.** Public availability requires an entry in the `cadasto` marketplace (`cadasto/plugin-marketplace`); the plugin is registered there independently of this repo. +- **Register in the marketplace separately — and repin it on every release.** Public availability requires an entry in the `cadasto` marketplace, maintained in `Cadasto/plugin-marketplace`. That entry is pinned to a release tag, so tagging here ships nothing until the entry's `version` and `source.ref` are bumped; see [docs/versioning.md](docs/versioning.md#marketplace). diff --git a/CHANGELOG.md b/CHANGELOG.md index 6a5d93a..7c87eb7 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,6 +7,11 @@ The format is based on Keep a Changelog, and this project adheres to Semantic Ve - Keep a Changelog: https://keepachangelog.com/en/1.1.0/ - Semantic Versioning: https://semver.org/spec/v2.0.0.html +## [Unreleased] + +### Changed +- Docs: `docs/versioning.md`, `AGENTS.md` — the `cadasto` catalog pins each entry to a release tag, so a tag here ships nothing until the entry's `version` and `source.ref` move. Repinning is now release step 8. + ## [0.2.0] - 2026-08-25 Tightens the plugin to a single prose linter and makes its always-on surface cheap: markdownlint is gone, the agents are honestly described as report-only, and every skill description is rewritten for the skill-listing budget. diff --git a/docs/versioning.md b/docs/versioning.md index ac058f7..c0e9ac7 100644 --- a/docs/versioning.md +++ b/docs/versioning.md @@ -19,11 +19,26 @@ While on the `0.x` line, treat the plugin as pre-stable: a breaking change may s 5. Sync the docs surface (AGENTS.md, README.md) with what shipped. The router body and `hooks/session-start.sh` are checked mechanically by the validator, so a missed component fails CI rather than shipping quietly. 6. Commit (`chore(release): vX.Y.Z`) and tag: `git tag -a vX.Y.Z -m "docs-editing-plugin vX.Y.Z"`. 7. Push commits and the tag: `git push origin main --follow-tags`. +8. **Update the marketplace entry** — the release is not live until this lands. See below. ## Coupling to external tooling The reference linter config (`references/vale.ini`) pins no tool version, but it does name **style packages** (`Google`, `write-good`, `alex`, `proselint`) whose rule sets change upstream. When a package renames or removes a rule the config disables or escalates, the config breaks silently — `vale` warns but exits 0 for an unknown rule name. Re-check the named rules when bumping a package, and treat a rule rename as a **patch** fix. -## No MCP or marketplace coupling +## No MCP coupling -This plugin has **no companion MCP server**, so there is no server-compatibility version to align. It is listed in the **Cadasto marketplace** (`cadasto/plugin-marketplace`); the marketplace tracks the repo's default branch, so update that entry only when `name`, `description`, or `repository` changes — there is no version pin to bump there. +This plugin has **no companion MCP server**, so there is no server-compatibility version to align. + +## Marketplace + +Public install is via the [Cadasto marketplace](https://github.com/Cadasto/plugin-marketplace) as `docs-editing@cadasto`. The catalog **pins every entry to a release tag**, so tagging and pushing a release here does not ship it — users see nothing until the marketplace entry moves. + +After step 7, update the entry in `Cadasto/plugin-marketplace`: + +1. Bump that entry's `version` to `X.Y.Z` and `source.ref` to `vX.Y.Z` together (validation there rejects a mismatch). +2. Bump the catalog's own `metadata.version` — a plugin minor/major is a catalog **minor**, a plugin patch is a catalog **patch**. +3. Add a dated `## [X.Y.Z] - YYYY-MM-DD` section in the catalog `CHANGELOG.md`, then run `python3 scripts/validate.py --fix`. + +See the catalog's [docs/versioning.md](https://github.com/Cadasto/plugin-marketplace/blob/main/docs/versioning.md). + +The catalog copies `description`, `version`, and `keywords` verbatim from `.claude-plugin/plugin.json`. Fix those in this repo and copy them into the catalog when the next release is pinned.