cub variant demote

Undo a change order in a space, restoring the revisions before it

Synopsis

Undo a change order in one space, restoring each unit it marked to the revision that unit was at before the change.

Aborting a change order says the change is not coming to the spaces still waiting for it. It changes nothing about the ones that already took it, which is what leaves a fleet part-way through a change nobody is going to finish. Demote is what takes it back out, space by space.

The change order must have an AbortedReason. Setting it is the decision that the change is not coming; undoing one nobody has said that about is a race with whoever is still promoting it.

Which units are restored is the change order's answer rather than a selection of your own: the units of this space its start tag marks. A unit it covered but carried no changes for is marked as restored without a revision being made -- there is nothing of it here to undo, and the revisions after it, if any, are somebody else's change.

Undoing a change order in a unit happens once, as promoting it into one does: a unit already carrying the restore tag is left alone, so a demote that landed partway is run again to reach the units it did not, and a unit edited forward since it was undone keeps that work.

Each restore is a new revision holding the earlier content, not an unwinding of the ones between, so the history of what happened stays intact. The change order's own tags stay where they are: the space took the change, whatever has happened since, and the restore tag is what says it was taken back out again. "cub changeorder get" reports where that has reached, as Restored Spaces, and the change order's State reads Restored once every space that took it has been, and RestoreReleased once every space that had released it has released the restored revisions.

The change order is named the way any entity in another space is: a bare slug resolves in the space being demoted, which is where the change order resides only when that space is where the change was made, and a / or a UUID names one anywhere else -- which is what a variant's is, since it lives upstream, possibly several hops up.

Demote does not promote the restored revisions onward, and does not restore the spaces downstream of this one. Each is demoted on its own account, because what it goes back to has to be released where the change was released. What demote does do is advance the merge pointers of the links that follow this space's units onto the restored revisions, so that a later upgrade does not replay the change that was just taken out.

Publishing is separate, as it is for promotion: "cub release publish" is what takes the restored revisions to a cluster.

A unit whose head has moved past where the change order ended has changes the restore will drop, and they are reported before anything is written. Nothing re-applies them: the restored revisions are expected to be released first, and re-applying them is a forward change to make afterwards.

Examples:

  # Undo an aborted change order in the space it was made in
  cub variant demote web-base --change-order release-42

  # Report what would be restored, and what later changes it would drop
  cub variant demote web-base --change-order release-42 --dry-run

  # Undo it in a variant, naming the change order in the space it was made in
  cub variant demote web-prod --change-order web-base/release-42 --change-desc "back out 1.42"

cub variant demote <space> [flags]

Options

      --change-desc string    change description recorded on the restored revisions
      --change-order string   change order to undo (required): a bare slug resolves in the space being demoted, which is where it resides only when that space is where the change was made; a variant's is <space>/<slug> or a UUID
      --dry-run               report the units that would be restored, and the later revisions the restore would drop, without changing anything
  -h, --help                  help for demote
  -o, --output string         Output format. One of: json, yaml, name, wide, mutations, jq=<expr>, yq=<expr>, custom-columns=<spec>
      --quiet                 No default output.
      --verbose               Detailed output, additive with default output

Options inherited from parent commands

      --context string   The context to use for this command
      --debug            Debug output

cub variant demote