Revision

Every time you make a change to the configuration data in a Config Unit, you create a new revision. ConfigHub keeps track of all changes in the form of a list of all historical revisions. Each revision has some metadata associated with it. There is a reference to who made the change and a short message about what the change was and why and how it was made.

Every Unit starts with an empty revision, revision 1, so a Unit created with content has that content at revision 2, and restoring revision 1 empties it. Refer to revisions by what they are rather than by number where you can: HeadRevisionNum, LastReleasedRevisionNum, a negative number counting back from the head, a tag, or the boundaries of a ChangeSet or a ChangeOrder.

A revision's configuration data, and its DataHash, never change once it is written. What is recorded about it can grow afterwards: the tags that mark it, the Releases that bundled it, the Attestations, such as approvals, that cover it, and the results of validating it.

You may restore a previous revision in order to undo changes. LastReleasedRevisionNum is the revision the Unit was at when it was last published in a Release, so you may easily restore the last released configuration of a Unit. You can also use tags to mark revisions of interest.

Each revision records the operation that made it in Source:

  • CreateUnit, CloneUnit, UpdateUnit, PatchUnit: the Unit was created, cloned from another Unit, or had its data replaced or patched.
  • Invoke: a function changed it, invoked directly or by a Trigger.
  • UpgradeUnit, MergeUnits: a merge from its upstream, or from another Unit or revision range.
  • RestoreRevision: it was restored to an earlier revision.
  • Resolve, NeedsProvides, Insert, Upsert, TransformPaths: a Link updated it.
  • MergeExternal, Import: content from outside ConfigHub, such as cub variant upload, was merged into it or imported.
  • Refresh: for a backing Unit, a write made directly to the entity it backs.
  • SetProtection, SetGuard: its protection or guards changed, with no change to its data.
  • ApplyConflicts, DismissConflicts: conflicts a merge withheld were applied, or dropped without changing the data.

Revisions are further broken down into one or more Mutations, which track the sources of granular changes to the configuration.