cub variant demote

Undo a change order, restoring the revisions before it

Synopsis

Undo a change order in the spaces it reached, 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.

The spaces are the named space, or those --where-space, --filter-space and --target-stage select among the spaces the change order reached. With none of them, demote takes the change order out of every space it reached, including the one it was made in. A selected space it never reached is reported and left alone.

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 each 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, or in the selected space when no space is named, 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. Each space is restored 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.

A change order with UpdateType Invoke is undone the same way, since what a restore reads is the tags the change left and those are the same tags. The one difference is that nothing carried it: the change was made in place rather than merged from an upstream, so no link records it and none is advanced.

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, by --dry-run before anything is written. To apply exactly what a dry run showed, pass its Plan (-o jq=.Plan) as --expected-plan: nothing is written if the demotion would now do anything different. 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"

  # Undo it everywhere it reached
  cub variant demote --change-order web-base/release-42

  # Undo it in the spaces of one stage of its change workflow
  cub variant demote --change-order web-base/release-42 --target-stage prod

cub variant demote [<variant>] [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
      --changeset string       changeset to record the restored revisions in
      --diff-context           with -o mutations, also show the unchanged paths around each change: every unchanged field and element of each map and list a change is in, up to the resource
      --dry-run                report the units that would be restored, and the later revisions the restore would drop, without changing anything
      --expected-plan string   the Plan a --dry-run of the same demotion returned; nothing is written if the demotion would now do anything different
      --filter-space string    filter over spaces narrowing the spaces the change order reached
  -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.
      --target-stage string    stage of the change order's ChangeWorkflow whose spaces to demote
      --verbose                Detailed output, additive with default output
      --where-space string     where expression narrowing the spaces the change order reached, instead of naming one

Options inherited from parent commands

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

cub variant demote