UNOFFICIAL/EXPERIMENTAL. A promotion review lives or dies on how it presents differences. This page defines the four classes every entry in a variant diff falls into, states the presentation each class deserves, and walks one committed promotion through them. Issue #152 asked for this vocabulary; the promotion pages and any future product UI should use it rather than inventing another.
The four classes
| Class | Meaning | How to present it |
|---|---|---|
| inherited | The value is identical in the variant and its base. Nothing departed and nothing arrived. | Keep it out of the way. Inherited content is the bulk of every diff, and a reviewer who scrolls past forty inherited objects stops reading before the entry that matters. |
| overridden | The variant departs from the base on purpose, and the departure survives the promotion. | Show it as a kept difference with its origin: which environment set it and what it protects. Survival is not a change, and presenting it as one teaches reviewers to ignore the diff. |
| upstream-added | The base moved and the variant has not yet absorbed the change. This is what a promotion actually moves. | Give it the headline. Name the object, the field path, and both values. This class carries the risk and deserves most of the screen. |
| no-op | The text differs but the object does not: reordered keys, defaulted fields, formatting. | Suppress it by default behind a count and a toggle. Twelve visible no-ops bury the one real change. |
One committed promotion, walked
Before the promote, staging's diff against its base held two kinds of entries. Its own deliberate departures were the overridden class, and they protect staging-only decisions. The reviewed replica change, spec.replicas moving from 3 to 4, sat on the base side as the upstream-added class: approved, tested in development, and not yet absorbed.
The promote moved exactly the upstream-added entry. The receipt records pendingUpstreamChanges: 0 afterwards, which is the machine form of "nothing approved is still waiting". The overridden entries survived unchanged, and the rest of both object sets stayed inherited and identical.
A reader of that promotion needed one headline (replicas 3 to 4), one kept-differences list (staging's departures, untouched), and silence about everything else. That is the whole presentation contract.
Four object sets show where a field came from
A source-aware review compares four exact object sets:
- the old source render;
- the old accepted configuration after later edits;
- the new source render;
- the proposed accepted configuration.
The first pair shows existing post-render edits. The second pair shows the proposed ones. Comparing the two source renders identifies chart, values, AICR, or other source changes. This prevents a review from calling every changed field a Helm change or every retained field a ConfigHub change.
When the new source and a later edit both affect the same field, the review marks an overlap. A retained override may still be correct, but it must be reviewed against the new source behavior before promotion. One field must not have two silent owners.
Formatting, comments, and mapping key order remain no-ops because the comparison uses parsed YAML objects rather than raw text.
The server preview and the independent comparison
The current Redis receipt records that cub variant promote --dry-run -o mutations returned mutation detail for both development and staging. It also checked that each dry run left stored data unchanged before the real promotion ran.
The Workshop still compares the exact object sets itself. That gives a useful review before a ConfigHub Space exists and provides an independent check of the later server preview. The browser result is not evidence that ConfigHub performed a promotion; the live Redis receipt supplies that separate evidence.