After publishing

Versions never change; yank, deprecate, and undo them

Chapter 18 of 34Current for Gritpack 1.2.63Source: docs/guide/18-after-publishing.md

You published a version, and then you found the bug. You cannot edit the version: its bytes are fixed, and every lock that records it relies on that. What you can do is publish a fix, and tell everyone else about the bad one. A deprecation puts a message on a version. A yank stops new projects from choosing it. Both can be undone, neither deletes anything, and neither breaks a project that already uses the version. This chapter shows each, with what it does to the people who depend on you.

What you will be able to do

  • choose between publishing a fix, deprecating, and yanking;
  • deprecate and undeprecate a version with a message;
  • yank and unyank a version;
  • predict what each does to existing lock files and to new resolutions.

Versions never change

Every published version is immutable. The hub keeps the exact package file, its digest and its metadata: description, README, licence, dependencies. To change any of it, publish a new version. Gritpack refuses to publish different content under a version that exists, as Publish your first package showed.

So the first answer to "I published a mistake" is almost always: fix it and publish the next version. Deprecation and yanking are about the old version that is still out there.

You want toUseNew projectsProjects that already locked it
tell users something about a version, such as "upgrade, this one has a bug"gritpack package deprecatecan still choose itkeep it, unchanged
stop new projects from choosing a versiongritpack package yankskip itkeep it, unchanged
hide a version from everyone, at onceask a hub administrator to quarantine itcannot get itcannot download it either

Quarantine is a moderation tool for things like malware or leaked secrets, and only administrators can do it (Licence rules, quarantine and the audit log).

Naming a version

Every command in this chapter takes the version as name@version:

gritpack package deprecate @ada/textkit@0.1.0 "Use 0.1.1 or later, which fixes trimming"

The storage ID from the publication receipt works too, and is exact when a version has several variants (for several platforms, say):

gritpack package yank 01M7M6M49WF588N9HSAJ439ETP

Only the package's owner can do these things. Another account gets an authorization error, exit code 4:

$ gritpack package yank @ada/textkit@0.1.0
the hub answered HTTP 403: credential is not authorized

A version the hub does not have is "not found", exit code 5:

$ gritpack package yank @ada/nothing@9.9.9
the hub answered HTTP 404: package not found

Deprecate

A deprecation attaches a message to a version, from 1 to 512 bytes. Say what to do instead:

$ gritpack package deprecate @ada/textkit@0.1.0 "Use 0.1.1 or later, which fixes trimming"
deprecated @ada/textkit 0.1.0 storage_id=01M7M6JQKGEVRR9JV079NNEJFR

The version still resolves and installs exactly as before. A project that asks for it gets it:

$ gritpack add @ada/textkit '=0.1.0'
added @ada/textkit and installed 1 packages into ./packages

The message shows where people look at the version:

$ gritpack info @ada/textkit --version 0.1.0
@ada/textkit 0.1.0 (native)
  Small text helpers for C
  deprecated: Use 0.1.1 or later, which fixes trimming
  dialect: c/c23
  ...

and in the JSON every tool can read:

$ gritpack info @ada/textkit --jq '.families[0].family.publications[] | {version, lifecycle}'
{"version":"0.1.1","lifecycle":{}}
{"version":"0.1.0","lifecycle":{"deprecation":{"deprecated_at":1794900667,"message":"Use 0.1.1 or later, which fixes trimming"}}}

gritpack search marks a package's newest version as [deprecated: ...] when that version is deprecated, which is how a renamed package points people to its new name.

Careful. Today add and sync do not print a deprecation message when they install a deprecated version. Users see it in info, in search results and in JSON. Put the important part of your message in the next version's README and release notes too.

gritpack outdated in the project still tells its owner there is something newer:

$ gritpack outdated
@ada/textkit current=0.1.0 wanted=0.1.0 latest=0.1.1 update=false upgrade=true

Remove the message when it no longer applies:

$ gritpack package undeprecate @ada/textkit@0.1.0
removed deprecation from @ada/textkit 0.1.0 storage_id=01M7M6JQKGEVRR9JV079NNEJFR

From npm. This is npm deprecate, with one difference: the message is attached to one exact version, not a range.

Yank

A yank tells resolution to skip a version. Use it for a version that should not be chosen any more: it does not build, it has a security hole, or it was published by mistake.

$ gritpack package yank @ada/textkit@0.1.1
yanked @ada/textkit 0.1.1 storage_id=01M7M6M49WF588N9HSAJ439ETP

Yanking twice is harmless; the second time changes nothing.

Projects that already use it keep working

A project whose gritpack.lock records @ada/textkit 0.1.1 is unaffected. Its lock still names the exact file and digest, and the hub still serves it. Even after deleting the installed packages, a frozen sync restores exactly the yanked version:

$ gritpack sync --frozen
synchronized 1 packages into ./packages status=changed
$ gritpack list
@ada/textkit 0.1.1 dialect=c/c23 direct source=https://packages.example.com:443 dependencies=-

This is the promise that makes yanking safe: nobody's build breaks because you yanked something. A yank is not a recall.

New resolutions skip it

A project that resolves afresh never picks a yanked version. In a new project, add takes the newest version that is not yanked:

$ gritpack add @ada/textkit
added @ada/textkit and installed 1 packages into ./packages
$ gritpack list
@ada/textkit 0.1.0 dialect=c/c23 direct source=https://packages.example.com:443 dependencies=-

Asking for the yanked version by name fails as if it were not there:

$ gritpack add @ada/textkit '=0.1.1'
cannot resolve @ada/textkit: root requires @ada/textkit =0.1.1

gritpack info and gritpack search no longer list it:

$ gritpack info @ada/textkit
@ada/textkit 0.1.0 (native)
  ...
  versions: 0.1.0

Projects that try to move

In the project that locked 0.1.1, the requirement in gritpack.toml is ^0.1.1, and now no version satisfies it: 0.1.1 is yanked and 0.1.0 is too old. sync keeps working from the lock, but anything that looks for a new version fails with "not found", exit code 5:

$ gritpack outdated
cannot resolve @ada/textkit: root requires @ada/textkit ^0.1.1
$ gritpack update
cannot resolve @ada/textkit: root requires @ada/textkit ^0.1.1

The fix is the usual one: publish 0.1.2 with the correction. Then update moves the project forward. This is why a yank should almost always come with a fixed version.

Unyank

If you yanked by mistake, or the problem turned out to be elsewhere:

$ gritpack package unyank @ada/textkit@0.1.1
unyanked @ada/textkit 0.1.1 storage_id=01M7M6M49WF588N9HSAJ439ETP

The version is offered again at once:

$ gritpack outdated
@ada/textkit current=0.1.1 wanted=0.1.1 latest=0.1.1 update=false upgrade=false

From Cargo. gritpack package yank behaves like cargo yank: existing Cargo.lock files and Gritpack locks keep the version, new resolutions skip it, and unyank brings it back. For crates on a Gritpack hub, cargo yank --registry <name> works too (Rust and Cargo).

A short checklist

When a bad version is out:

  1. Fix the problem and publish the next version.
  2. If people should move off the old version but it still works, deprecate it with a message naming the fixed version.
  3. If new projects must not choose it at all, yank it too.
  4. If it is dangerous to anyone who has it, such as malware or a leaked secret, tell the hub's administrator; only quarantine stops existing locks from downloading it.

What just happened

  • A published version never changes; mistakes are fixed with a new version.
  • package deprecate and undeprecate attach and remove a message. The version still resolves.
  • package yank and unyank stop and restart new resolutions choosing a version. Existing locks, including sync --frozen, keep it.
  • All four take name@version or a storage ID, and only the owner may use them.

You can stop here

If you publish one package at a time, you now know the whole lifecycle of a version.

Next

  • Publishing step by step publishes several packages together, all or none, in separate steps you can review.
  • Optional: Evidence and receipts for the signed records the hub keeps of every publication and lifecycle change.