From 304a49f6bef012f1831d9da53fbd43f1a2b098f1 Mon Sep 17 00:00:00 2001 From: Kevin Bost Date: Mon, 27 Apr 2026 13:05:23 -0700 Subject: [PATCH 1/2] Add plugin version sync validation and Copilot instructions - Add CI step to validate plugin.json versions match marketplace.json - Add Copilot instructions for JSON files to keep versions in sync - Add Copilot instructions for plugin edits to prompt for version bumps Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- .../plugin-editing.instructions.md | 12 ++++++ .../plugin-version-sync.instructions.md | 13 ++++++ .github/workflows/validate-plugins.yml | 43 +++++++++++++++++++ 3 files changed, 68 insertions(+) create mode 100644 .github/instructions/plugin-editing.instructions.md create mode 100644 .github/instructions/plugin-version-sync.instructions.md diff --git a/.github/instructions/plugin-editing.instructions.md b/.github/instructions/plugin-editing.instructions.md new file mode 100644 index 0000000..462eb07 --- /dev/null +++ b/.github/instructions/plugin-editing.instructions.md @@ -0,0 +1,12 @@ +--- +applyTo: "plugins/**" +--- + +# Plugin Editing — Version Bump Reminder + +Whenever you edit any file inside a `plugins//` directory, remind the user to bump the plugin version before committing: + +1. Increment the `version` field in `plugins//plugin.json` (follow semver: patch for fixes/content tweaks, minor for new instructions or capabilities, major for breaking changes). +2. Update the matching entry's `version` in `.github/plugin/marketplace.json` to the same value. + +The CI workflow enforces that these two versions match, so both files must be updated together. diff --git a/.github/instructions/plugin-version-sync.instructions.md b/.github/instructions/plugin-version-sync.instructions.md new file mode 100644 index 0000000..93b5ce2 --- /dev/null +++ b/.github/instructions/plugin-version-sync.instructions.md @@ -0,0 +1,13 @@ +--- +applyTo: "plugins/**/plugin.json,.github/plugin/marketplace.json" +--- + +# Plugin Version Sync + +The `version` field in every `plugins//plugin.json` **must always match** the corresponding entry's `version` in `.github/plugin/marketplace.json`. + +When editing either file: +- If you change the `version` in a `plugin.json`, update the matching entry in `.github/plugin/marketplace.json` to the same value. +- If you change a plugin's `version` in `marketplace.json`, update the corresponding `plugin.json` to the same value. + +Both files must be committed together so the CI version-sync check passes. diff --git a/.github/workflows/validate-plugins.yml b/.github/workflows/validate-plugins.yml index e0872bc..fc18807 100644 --- a/.github/workflows/validate-plugins.yml +++ b/.github/workflows/validate-plugins.yml @@ -73,3 +73,46 @@ jobs: print("✓ All plugin names are unique") EOF + + - name: Validate plugin versions match marketplace.json + run: | + python3 << 'EOF' + import json + import glob + import sys + + with open(".github/plugin/marketplace.json", "r") as f: + marketplace = json.load(f) + + marketplace_versions = { + p["name"]: p["version"] for p in marketplace.get("plugins", []) + } + + errors = [] + for plugin_file in glob.glob("plugins/**/plugin.json", recursive=True): + with open(plugin_file, "r") as f: + plugin = json.load(f) + + name = plugin.get("name") + plugin_version = plugin.get("version") + marketplace_version = marketplace_versions.get(name) + + if marketplace_version is None: + errors.append( + f"❌ {plugin_file}: plugin '{name}' not found in marketplace.json" + ) + elif plugin_version != marketplace_version: + errors.append( + f"❌ {plugin_file}: version '{plugin_version}' does not match " + f"marketplace.json version '{marketplace_version}' for plugin '{name}'" + ) + else: + print(f"✓ {plugin_file}: version '{plugin_version}' matches marketplace.json") + + if errors: + for error in errors: + print(error) + sys.exit(1) + + print("\n✓ All plugin versions match marketplace.json") + EOF From aee5b7267626570ebde77abb8618c36b0ebee43e Mon Sep 17 00:00:00 2001 From: Kevin Bost Date: Mon, 27 Apr 2026 13:06:40 -0700 Subject: [PATCH 2/2] Expand semver guidance in plugin-editing instructions Add concrete examples for patch, minor, and major version bumps specific to the plugin content model (instructions, agents, naming). Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- .../plugin-editing.instructions.md | 19 ++++++++++++++++++- 1 file changed, 18 insertions(+), 1 deletion(-) diff --git a/.github/instructions/plugin-editing.instructions.md b/.github/instructions/plugin-editing.instructions.md index 462eb07..18bf71d 100644 --- a/.github/instructions/plugin-editing.instructions.md +++ b/.github/instructions/plugin-editing.instructions.md @@ -6,7 +6,24 @@ applyTo: "plugins/**" Whenever you edit any file inside a `plugins//` directory, remind the user to bump the plugin version before committing: -1. Increment the `version` field in `plugins//plugin.json` (follow semver: patch for fixes/content tweaks, minor for new instructions or capabilities, major for breaking changes). +1. Increment the `version` field in `plugins//plugin.json` using the semver rules below. 2. Update the matching entry's `version` in `.github/plugin/marketplace.json` to the same value. +## Semver guidance for plugins + +**Patch** (`1.0.x`) — backward-compatible fixes and clarifications with no change in scope: +- Fixing typos, grammar, or unclear wording in instructions +- Rewording guidance to improve clarity without changing intent +- Adding or improving examples that illustrate existing rules + +**Minor** (`1.x.0`) — backward-compatible additions that expand what the plugin covers: +- Adding new instruction files or new sections to existing ones +- Adding a new agent, prompt, or capability to the plugin +- Extending keywords or categories in `plugin.json` + +**Major** (`x.0.0`) — changes that alter existing behavior in a way users may need to adapt to: +- Removing or renaming instruction files referenced by the plugin +- Fundamentally changing the guidance or recommendations in a way that conflicts with prior versions +- Changing the plugin `name` field (affects install commands and `@` references) + The CI workflow enforces that these two versions match, so both files must be updated together.