cub variant promote

Promote a variant space to match its upstream space

Synopsis

Promote a variant space to match changes in its upstream space.

The space must have been created by "cub variant create", which stamps an "UpstreamSpaceID" annotation recording the upstream space it was cloned from. Promote reconciles the variant with that upstream in three steps:

Upgrade every unit whose upstream unit has advanced (the unit's UpstreamRevisionNum is behind the upstream unit's HeadRevisionNum), merging the upstream changes. Equivalent to "cub unit update --patch --upgrade --where 'UpstreamRevisionNum < UpstreamUnit.HeadRevisionNum'".
Clone any units added to the upstream space since the variant was created or last promoted, linking each clone to its upstream unit.
Copy the new units' non-UpgradeUnit links, retargeting a link to its downstream copy when it points at another unit in the upstream space. A link that already points into this variant is left alone rather than copied into it.

Promote waits for triggers to complete. Use --dry-run to preview: the units that would be upgraded (add -o mutations to see the changes) and the units that would be added.

An upgrade re-runs the upstream's recorded function invocations against each unit where it can -- so a change lands where the unit's own structure puts it -- and records one revision per upstream revision that has an effect, carrying that revision's change description. The variant's history then reads as the upstream's does rather than as a series of promotions. --squash gives up both: the range arrives as one rebased diff in one revision.

--change-order promotes a named change rather than everything the upstream has reached. The change order fixed its range when it was created, so the upgrade stops where it ends, a unit it does not cover is passed over, and a unit that is not where it starts is an error rather than a merge of a different range. Two things follow from what a change order is:

The steps run in the other order, clone first. A unit the variant does not have yet is cloned at the revision the change order starts from, and then upgraded through the change with everything else, so it ends up with the revisions the change made everywhere else rather than arriving whole with the change already in it. A unit created upstream after the change order was fixed is outside it: those are listed rather than cloned, and promoting without --change-order adds them.
The promotion is undone in one step, however many revisions it made: "cub unit update --patch --space --where \"Slug LIKE '%'\" --restore Before:ChangeOrder:/".

--target-stage promotes a whole stage rather than one space, and takes no positional space. A promotion is defined over a stage -- the spaces a change reaches together -- and naming one space is the narrower case. The stage's membership is not a label search of its own: --change-order supplies the change order, the change order records the ChangeWorkflow it was created under, and that workflow's stage of this name carries the selector naming the spaces. So --target-stage requires --change-order, whose bare slug resolves in the selected space here rather than in an upstream, there being no variant yet to take an upstream from; a change order created without a workflow is an error rather than a guess.

Naming a stage says where the change is headed, not that it may skip what precedes it. The entry gates are the stage's own, evaluated once over the whole membership of the stage ahead of it, so naming a later stage while an earlier one is unsatisfied is refused.
A stage is promoted one variant at a time and can land partway. A variant that fails is reported and the ones after it are still promoted, and what comes back says how many of them landed. Promoting again is what repairs a partial stage: a variant that already took the change is no longer behind its upstream, so it is not selected again.

Without --target-stage, --change-order alone advances the change one stage: into the first stage it has not reached, which is where it is going next. Reaching a stage is having reached every space that stage selects, so the stage the change was authored in is passed over -- the change order lives there -- and a stage that has taken the change but not released it leaves the stage after it as the next, whose gates then refuse the promotion naming what is missing. Once every stage has the change, that is reported and nothing is changed.

Examples:

  # Promote a variant to match its upstream
  cub variant promote web-prod

  # Preview the changes, including the mutations
  cub variant promote web-prod --dry-run -o mutations

  # Promote, recording the whole range as one revision per unit
  cub variant promote web-prod --squash

  # Promote one named change, leaving later upstream changes behind
  cub variant promote web-prod --change-order release-42

  # Promote that change into every variant of a stage of its change workflow
  cub variant promote --change-order web-base/release-42 --target-stage staging

  # Preview what promoting the whole stage would do
  cub variant promote --change-order web-base/release-42 --target-stage staging --dry-run

  # Advance the change to the next stage it has not reached
  cub variant promote --change-order web-base/release-42

  # Promote within a changeset, with a change description
  cub variant promote web-prod --changeset release-2024-06 --change-desc "Promote to prod"

cub variant promote [<space>] [flags]

Options

      --change-desc string    change description recorded on the upgraded and cloned units
      --change-order string   change order to promote instead of everything the upstream has reached: it supplies the range, units it does not cover are passed over, and a unit that is not where it starts is an error. A bare slug resolves in the upstream space, or in the selected space with --target-stage. Units the variant does not have yet are cloned at the change order's start and then upgraded through it; ones created upstream after the change order was fixed are outside it and are listed rather than cloned
      --changeset string      changeset to associate the upgraded and cloned units with
      --dry-run               preview the units that would be upgraded and added without changing anything
  -h, --help                  help for promote
  -o, --output string         Output format. One of: json, yaml, name, wide, mutations, jq=<expr>, yq=<expr>, custom-columns=<spec>
      --quiet                 No default output.
      --squash                merge each unit's range as one rebased diff in one revision instead of walking it: by default a promotion re-runs the upstream's recorded function invocations against each unit where it can, and records one revision per upstream revision that has an effect there
      --target-stage string   stage of the change order's ChangeWorkflow to promote into, promoting every variant the stage selects instead of one named space: it requires --change-order and takes no positional space, the gates of the stage ahead are checked once for the whole stage, and a variant that fails is reported without stopping the ones after it. Without it, --change-order alone advances the change into the first stage it has not reached
      --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 promote