Skip to content

Versioning rules ​

Every release requires you to choose a version number, and sometimes to deprecate or yank an old version. This page shows how to do all three. All resources use semver MAJOR.MINOR.PATCH.

Choose a version number ​

BumpWhenExamples
MAJORA change that breaks existing usageRename an agent or skill, remove an MCP tool, change a function's parameters in a contract, remove a field
MINORA backward-compatible new featureAdd a skill to a harness, add an MCP tool, add a capability group to a kit
PATCHA fix that doesn't change usageFix a typo in instructions, fix a code bug, update docs

Here is a quick test. If someone on the old version can upgrade without changing anything and everything runs as before, it isn't a MAJOR change.

A harness version reflects changes to the whole set of resources. A harness uses ~ for agents, so it receives only patches automatically. To move an agent to a new minor version, release a new minor version of the harness.

Requirements ​

The version field in plugin.json must have the form MAJOR.MINOR.PATCH, and CHANGELOG.md must have a ## <version> section for that exact number. Use each number only once. A submission that was returned or failed a check has still used its number, so you must bump the number next time. A released version is immutable. There is no way to fix it in place.

The following command sets the version number and adds a changelog entry at the same time.

bash
ph tara bump ./resource-directory 1.2.0 --changelog "Add a template for paginated APIs"

If you work in the Portal, the new-version editor suggests a number based on the kind of change (bug fix, feature, major change) and shows you the diff before you submit.

Write the changelog ​

Each entry should say what users need to know to decide whether to upgrade. Put major changes first and describe how to migrate, because Phillip uses this section to notify users of a new version.

markdown
## 2.0.0 - 2026-11-01

- Rename agent `dev` to `developer`. Update every call to `agent-x:dev`.
- Remove the `list_checks` tool; use `get_pull_request`.

## 1.3.0 - 2026-10-20

- Add a template for paginated APIs.

When to deprecate a version ​

Deprecate a resource or a version when it should no longer be chosen for new use but is still safe to use.

bash
ph tara deprecate resource-name@1.0.0 --reason "Replaced by 2.x"
ph tara undeprecate resource-name@1.0.0

A deprecated version is hidden from the latest channel and from default search results. Existing locks can still install it, with a warning. To replace the whole resource, set metadata.forge.status to deprecated and point replacedBy to the replacement name. An Admin or Owner of the organization (or platform staff, for the official catalog) runs this command, so if you're the author, ask one of them.

"Deleting" a resource is also deprecation in practice. The package isn't deleted, so projects that have locked it can still install it.

When to yank a version ​

Yank a version only when it has a security vulnerability or a serious bug.

bash
ph tara yank resource-name@1.0.1 --reason "Data leak in the sample instructions"

The reason is required. After this command, Tara re-signs the yank list, and Phillip and the services that hold the trust key refuse to load that version, even if it's already in the cache. ph tara list warns about projects that have locked it. The owner of a personal resource can yank it without an admin session.

After yanking, release a patch (PATCH) or a new version and tell projects to run ph tara upgrade.

A version that contains malware gets harsher treatment: in addition to yanking, Tara removes the package so no one can download it. The mechanism is described in Version locking and digital signatures.

Further reading ​