torb deprecate

A deprecated package stays exactly as it is - every release can still be resolved, locked and installed - but torb add tells whoever adds it that its maintainers moved on, and to what. deprecate is for a package that is replaced or no longer kept; a single bad release is torb yank's, and a deprecation withdraws nothing.

Synopsis#

torb deprecate <owner/name>         Flag a whole package as deprecated
  --use <owner/name>                The package to use instead (optional)
  --reason <text>                   Why: `torb add` prints it (optional)
  --undo                            Take the deprecation back instead, without either
  --registry <url>                  The registry, instead of the one the owner is bound to
  --project <directory>             The project whose registry lines bind the owner (default: the working directory's)

What it does#

1. The registry is found as torb owner finds it: --registry, else the owner's registry binding in the project, else the public registry.
2. At a registry on the network deprecate sends POST <registry>/api/1/packages/<owner>/<name>/deprecate with the package to use and the reason, and --undo sends DELETE of the same path, with the token a request to the registry sends: TORB_TOKEN, else the one torb login stored. A member with the yank action may; the registry appends a signed deprecate or undeprecate line to the package's index file.
3. At a file: registry deprecate appends the line itself, as torb publish appends a release: deprecate "<package>", use: "<package>", reason: "<reason>", or undeprecate "<package>". A registry whose index/config.trb lists signing keys is refused, since only its write service can sign a record.

$ torb deprecate acme/http --use acme/http2 --reason "http2 speaks HTTP/2 and keeps the API"
deprecated acme/http
$ torb deprecate acme/http --undo
acme/http is no longer deprecated

The index file only ever grows: the last deprecate or undeprecate line of a package is the one that holds, so a second deprecate replaces the notice of the first. The package to use instead is a name and need not exist yet; it is never the package itself.

What torb add shows#

torb add acme/http resolves, writes the lock and then prints one notice for every package named on the command line, once:

$ torb add acme/http
added acme/http to acme/app
  + acme/http 1.4.0
warning: acme/http is deprecated: http2 speaks HTTP/2 and keeps the API
  use acme/http2 instead

Only the packages named are announced, not the ones they need; torb update and torb install stay silent, and the lock is the one a package without the flag gets. Nothing about the resolution changes.

Pitfalls#

A deprecation is not a yank. Every version resolves as before. To keep a broken release from new resolutions, torb yank it.

The notice is public. It is in the index file anyone reads, and an older torb that does not know the lines skips them and verifies the index all the same.

A refusal of the registry - no such package, --undo of a package that is not deprecated, a token without the yank action - ends with the exit code 1, a command written wrong - no package, --undo with --use or --reason, a --use that is no package name or the package itself - with 2.

Examples#

Deprecate a package in a registry directory a team shares:

$ torb deprecate acme/http --use acme/http2 --registry file:../registry
deprecated acme/http in file:../registry

Related#

• torb yank - withdraws one version instead of flagging the package.
• torb add - prints the notice.
• torb audit - reports the deprecated packages a lock pins.
• torb owner - who may deprecate.
• torb login - stores the token a deprecation sends.