Versions

Versions consist of a value and a schema. Each schema has its own value pattern and bumping rules. Different schemas are also good for different types of nodes, for example:

Schema	Example use case	Example value
SemVer	APIs, Apps, Systems	0.1.0, 1.2.3
Incremental	Resources, Solutions, Documents	1, 100
Custom	Tests, Deployments	alpha, static
Hash	Groups, Containers	12345678, a127befd
Random	Tests, Documents	ab76218d, 986351af

Versions should preferably help you keep track of a node’s history by providing a clear red thread from revision to revision. Therefore, picking the correct schema can help you audit changes later on.

Note

Version schemas can always be changed later on.

Examples

Following are some examples of bumping versions:

Type	Previous version	Value	Next version
SemVer	1.2.3	patch	1.2.4
SemVer	1.2.3	minor	1.3.0
SemVer	1.2.3	major	2.0.0
SemVer	1.2.3	2.3.4	2.3.4
Incremental	1	(empty)	2
Incremental	10	20	20
Custom	alpha	beta	beta
Hash	12345678	a127befd	a127befd
Random	382be47a	N/A	382be47a

Propagation

Note

Note that propagation only applies when bumping a node’s version. If you change a node or set of nodes without syncing, propagation will not take place.

Bumping a node’s version will in most cases propagate the version bumping “upwards” through the tree, from the target node to the root node. What follows is an illustration of how propagation works when bumping a node. The figures show:

• No bumping is performed.
• Node A is bumped, no other nodes are bumped.
• Node B is bumped, node A is also bumped.
• Node C is bumped, node A is also bumped.
• Node D is bumped, nodes A and B are also bumped.
• Node E is bumped, nodes A and B are also bumped.

Propagation when bumping nodes (colored orange)

SemVer

Note

Currently the Constellation tool doesn’t support paragraph 4 of the v1.0.0 Semantic Versioning specification.

Follows the v1.0.0 Semantic Versioning specification, which you can read more about here. Semantic Versioning can be useful when you have a public API that must follow major, minor, and patch standards. Nodes with the SemVer schema must only have child nodes that also have the SemVer schema. This way, bumping a descendant allows the Constellation tool to automatically calculate what version all ancestors should become. Bumping can be done with legal SemVer values or one of the following keywords: patch, minor, and major.

When bumping a node with the SemVer schema the parent will run the following algorithm:

• If any child node’s SemVer value has a major change, the parent will increment its major by one and reset its minor and patch to zero; else
• if any child node’s SemVer value has a minor change, the parent will increment its minor by one and reset its patch to zero; else
• if any child node’s SemVer value has a patch change, the parent will increment its patch by one; else
• no change is made to the parent’s SemVer value

Let’s look at an example where we bump a node in a Constellation and see how the changes propagates from the leaf node (C) up the tree, to the root node (A). Consider the following Constellation (figure 1):

Bumping with relative SemVer value

When bumping node C with value patch, the Constellation changes to figure 2. When bumping node C with value minor, after which the Constellation changes to figure 3. Finally, when bumping node C with value major, the Constellation changes to figure 4. Note how the changes propagate from node C, through node B, to node A. You can also bump a node with SemVer schema by supplying an absolute value. Bumping node B in figure 1 (see below) with value 2.1.2 will change the Constellation into figure 2 (as seen below). Note that node C remains unchanged as the bump was applied to a node further up.

Bumping with absolute SemVer value

Playground

^\d+\.\d+\.\d+$

Caution

The playground does not check if the version is equal to 0.0.0, which is not a valid SemVer version.

Incremental

The Incremental schema is good for nodes that don’t represent public APIs and/or have changes that don’t nicely fit into the patch, minor, and major structure that Semantic Versioning provides. Nodes with the Incremental schema can have child nodes with any schema, making the Incremental schema a good candidate for the root node.

When nodes with Incremental schemas are bumped (either directly or through propagation) their values are incremental by one, thus the schema name. Bumping Incremental schemas can be done either with no value at all, in which case the count just increases by one, or by providing a positive non-zero integer which will become the new value. For example, consider the following Constellation (figure 1):

Bumping Incremental versions

Node B is bumped with value minor (1.2.3 to 1.3.0) which propagates to the root node (A) and increases its count by one, resulting in figure 2. Propagation will always increment by one for nodes with the Incremental schema, regardless of bumping value. Then node C is bumped with an empty value, which increase node C’s value by one (5 to 6) and propagates to the root node (A), which makes the Constellation look like figure 3. Finally, node C is bumped with value 10 which also propagates to the root node (A), then making the Constellation look like figure 4.

Playground

^\d+$

Caution

The playground does not check if the version is equal to 0, which is not a valid Incremental version.

Custom

The Custom schema is a great fit when other schemas just don’t cut it. The Custom schema accepts any value that when encoded to UTF8 occupies no less than 1 byte and no more than 100 bytes. Nodes with the Custom schema are not allowed to have any child nodes. However, bumping is still allowed. Take the following Constellation (figure 1):

Bumping Custom version

In figure 2, we’ve bumped node C’s version from alpha to beta, which also propagated the change up to the root node (A) and bumped it from 100 to 101.

Playground

.* Length (UTF8): 0 Min: 1 Max: 100

Caution

The playground does not check if the version is white space only, which is not a valid Custom version.

Hash

The Hash schema is useful when grouping nodes or when the versions of the child nodes are more important than the version of the parent node. The hash is calculated by getting the bytes from each child node’s ID (value as raw integer and variant as UTF8), version value (UTF8 for Custom), and version schema, then running the bytes through SHA256. The first 4 bytes of the produced SHA256 hash are then extracted and used as the new version value. See the following example:

How Hash version is calculated (propagation triggering node colored orange)

Following is an example of a Constellation with the root node (A) having the Hash version schema (see figure 1). Node B is then bumped from 1.2.3 to 1.2.4, which results in node A being bumped (hash recalculated) to another value, going from 48f59dc1 to 51072d25, which is depicted in figure 2.

Bumping Hash version

Playground

^[0-9a-f]{8}$

Random

The Random schema is just a random hash with 8 hexadecimal characters. It can be used for nodes that aren’t versioned and are more useful as status indicators, such as for tests. Nodes with the Random schema can’t be bumped and can only have child nodes that have the Random schema.

Node with Random schema

Playground

^[0-9a-f]{8}$