Repository Public MIT
1---2title: Versioning and safe updates3description: Immutable releases, semantic versions, dependency pinning, bundles, permissions, deprecation and revocation.4order: 225section: Publish6---78# Versioning and safe updates910## Releases are immutable1112Once `@ns/slug@1.2.0` is published, its archive, manifest, file list and SHA-256 never change. The database refuses updates and deletions of release content, independently of the application. Publishing the same version again returns `409 version_exists`.1314What can change after publication:1516| Thing | Who | Notes |17|---|---|---|18| Release notes | Publisher (`releases:update`) | Metadata only; the edit is audited |19| Release state | Publisher with `releases:revoke`, or a moderator | `published` to `revoked`, with a public reason |20| Listing metadata (summary, links, keywords, visibility) | Publisher (`artifacts:update`) | Belongs to the artifact, not to a release |2122To correct a release, publish a new version.2324## Version numbers2526Strict semantic versioning, without build metadata.2728- `MAJOR` — existing users must change something: removed or renamed behaviour, new required permissions or secrets.29- `MINOR` — additions that do not break existing use.30- `PATCH` — fixes.31- Prereleases (`2.0.0-beta.1`) are published like any version but never become `latest` while a stable version exists.3233`latest` is the highest stable published version. Revoking it moves `latest` back to the best remaining one.3435A change in what a package may do — new scripts, new network use, a new declared permission — deserves at least a minor bump and a line in the release notes. Installers compare what they agreed to before with what they are getting now.3637## Dependencies3839```json40"dependencies": [41 { "name": "@research/citation-check", "version": "^1.2.0" },42 { "name": "@research/latex-tools", "version": "1.0.3", "optional": true }43]44```4546- `version` is a semver range (`^1.2.0`, `~1.2.0`, `>=1.0.0 <2.0.0`, or an exact version).47- At publication, each required dependency must exist in the registry and have at least one published version that satisfies the range. Otherwise the release is rejected (`dependency-unknown`, `dependency-unsatisfied`). Optional dependencies produce a note instead.48- A package cannot depend on itself or list a dependency twice.49- The registry records dependencies and shows them. It does not resolve or install dependency trees for you in this version; install each one deliberately.5051For reproducible work, pin exact versions. A range that was safe yesterday can match a new release tomorrow.5253## Bundles5455A `bundle` is a named set of other artifacts. Because its purpose is reproducibility, every dependency must be an **exact version**:5657```json58{59 "type": "bundle",60 "dependencies": [61 { "name": "@research/citation-check", "version": "1.2.0" },62 { "name": "@research/latex-tools", "version": "1.0.3" }63 ]64}65```6667A range in a bundle is a blocking error (`bundle-unlocked-dependency`). To move a bundle forward, publish a new bundle version with new pins.6869## Permissions7071`permissions` in the manifest states what the package needs: `filesystem:read`, `filesystem:write`, `network`, `shell`, `env`, `mcp`, `browser`, `credentials`. They are shown on the artifact page and before install.7273The scanner adds a finding when scripts appear to use the network or spawn processes but the manifest does not declare `network` or `shell`. Declare honestly: an under-declared package looks worse than one that asks for what it uses.7475## Updating safely, as a user76771. Read the release notes of the new version.782. Compare: file list, declared permissions and findings are on each version's page.793. Install the specific version: `skills update @ns/slug --client claude-code` or `skills install @ns/slug@1.3.0 …`. The CLI verifies the checksum, shows the destination, keeps the previous copy in `~/.skills-registry/backups/`, and runs nothing.804. If something is wrong, restore the backup or install the earlier version by number. Earlier versions stay downloadable unless revoked.8182The `.skills-registry.json` file in an installed directory records which version and checksum you have.8384## Deprecation8586Deprecating says "this still works, but use something else". It requires a reason, which is shown on the page, and confirmation. Downloads continue. It can be undone.8788```bash89skills deprecate @ns/slug --reason "Superseded by @ns/new-slug, which supports the 2026 citation styles."90```9192Archiving closes an artifact to new releases and removes it from listings; existing versions stay reachable by link.9394Both need the `artifacts:deprecate` scope, which the default publisher token does not carry.9596## Revocation9798Revoke a version that is harmful: a leaked secret, a malicious dependency, a destructive bug.99100```bash101skills revoke @ns/slug@1.2.0 --reason "Shipped a script that deletes the wrong directory. Use 1.2.1."102```103104- Downloads of that version return `410 Gone` with your reason.105- The version stays in the history, marked revoked, with its checksum and metadata.106- `latest` moves to the best remaining version.107- It cannot be undone. Publish a fixed version.108109If the revoked version contained a secret, revocation does not un-leak it. Rotate the secret.110111## History112113Every artifact has a public history: creation, each publication, deprecation, revocation, with the publisher's display name and the time. It is drawn from an append-only audit log.114