GHC plugins marketplace plugin versioning

[mikirothman]

🏷️ Discussion Type

Question

💬 Feature/Topic Area

VS Code

Body

Hello,

My SW group created copilot plugins marketplace, which is superb solution to share the extensions as plugins.
The issue we are facing:

let's say we have a tool named nice_tool version 1.0.
we created a plugin nice_tool-plugin version 1.0 on top of it's CLI (contain agents, skills, hooks and whatever).

now, the tool progressed due to clients needs and provides new major changes which require rewriting massive amount of it's CLI interface (version 2.0) - so we had to also update the plugin with the new CLI capabilities to version 2.0.

we still want to enable users of version 1.0 of the tool to install using the marketplace.

something like /plugin install nice_tool-plugin@my-marketplace --version 1.0
instead of the latest version.

is it something that a marketplace addresses?
any best practice on how to handle those kind of use-cases?

[MakiBuu]

In this kind of scenario, the usual approach is to rely on proper versioning and let the marketplace handle multiple published versions instead of overwriting them. Ideally, you’d keep both nice_tool-plugin v1.x and v2.x available, and allow users to install a specific version (e.g. --version 1.0) so it matches their CLI version. If the marketplace supports version pinning or compatibility metadata, that’s the cleanest solution. Otherwise, you may need to implement version resolution yourself or clearly document which plugin version works with each CLI version.

[mikirothman]

thanks for your reply,

does the marketplace registry needs to hold both versions at the same time (as demonstrated in the example below)? meaning all versions of the plugins will leave together on the main branch?

{
  "name": "my-marketplace",
  "owner": {
    "name": "My Organization",
    "email": "plugins@example.com"
  },
  "metadata": {
    "description": "Curated plugins for our team",
    "version": "1.0.0"
  },
  "plugins": [
    {
      "name": "nice_tool-plugin",
      "description": "Nice tool plugin",
      "version": "1.0",
      "source": "./plugins/nice_tool-plugin-v1"
    },
    {
      "name": "nice_tool-plugin",
      "description": "Nice tool plugin",
      "version": "2.0",
      "source": "./plugins/nice_tool-plugin-v2"
    }
  ]
}

[MakiBuu]

I wouldn’t structure it that way though.

In most registries, you don’t list the same plugin multiple times just to represent different versions. The plugin is defined once, and the registry handles multiple versions (releases) behind the scenes.

So yes, both v1.0 and v2.0 should exist at the same time, but not as separate entries like in your example — that tends to get messy pretty quickly and is harder to maintain.

The more common approach is to have a single plugin (nice_tool-plugin) with multiple published versions (1.0, 2.0, etc.), and then let the installer resolve either the latest version by default or a specific one via --version.

If you’re working with a file-based setup like that JSON, it’s cleaner to group versions under the same plugin rather than duplicating entries.

Also, a couple of best practices that usually help:

don’t overwrite old versions (treat them as immutable)
make compatibility clear (e.g. plugin v1.x works with CLI v1.x)
allow users to pin a version when needed

So overall: keep multiple versions, just model them as versions of a single plugin, not separate plugin entries.

[mikirothman]

those are really outstanding inputs.
though, I don't think I know / understand how to construct the plugin directory structure to support those remarks.
do you have any examples? I really want to follow
the docs doesn't describe this kind of version management stuff

[Gecko51]

Yes, that structure looks right. Both versions live in the registry at the same time, each pointing to its own source directory, and the marketplace resolves which one to pull based on the version field when a user specifies --version 1.0.

One thing to keep in mind: the source paths are relative (e.g. ./plugins/nice_tool-plugin-v1), so make sure those directories are committed to the same repo/branch as the registry manifest. If you're managing this in a monorepo, keeping both plugin versions as subdirectories alongside the manifest is the cleanest setup.

For users who don't specify a version, the marketplace will typically resolve to the latest (highest version number), so v2.0 in this case. Depending on how your marketplace implementation handles version sorting, you may want to document this behavior explicitly for your users.

If you're seeing issues with the --version flag not working as expected, also double-check that the CLI calling the marketplace is actually passing the version through to the registry lookup — that's where it usually breaks, not in the registry itself.