After publishing
Versions never change; yank, deprecate, and undo them
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 to | Use | New projects | Projects that already locked it |
|---|---|---|---|
| tell users something about a version, such as "upgrade, this one has a bug" | gritpack package deprecate | can still choose it | keep it, unchanged |
| stop new projects from choosing a version | gritpack package yank | skip it | keep it, unchanged |
| hide a version from everyone, at once | ask a hub administrator to quarantine it | cannot get it | cannot 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
addandsyncdo not print a deprecation message when they install a deprecated version. Users see it ininfo, 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 yankbehaves likecargo yank: existingCargo.lockfiles and Gritpack locks keep the version, new resolutions skip it, andunyankbrings 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:
- Fix the problem and publish the next version.
- If people should move off the old version but it still works, deprecate it with a message naming the fixed version.
- If new projects must not choose it at all, yank it too.
- 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 deprecateandundeprecateattach and remove a message. The version still resolves.package yankandunyankstop and restart new resolutions choosing a version. Existing locks, includingsync --frozen, keep it.- All four take
name@versionor 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.