Versioning Cages and Stacksets

How Nucleator and git work together to enable strong versioning of Nucleator Cages and Stacksets, as well as the Nucleator environments that are created from them.

Nucleator is designed for flexibility and extensibility. Users will often have very specific requirements regarding the types and versions of Stacksets they need to use.

A best practice for public or private publishers of Nucleator Stacksets is to publish a Stackset as a managed repository (Git, BitBucket) and to tag incremental releases of a Stackset as functionality is added over time.

By convention, stable releases should be tagged release-X.Y.Z where X is a major version number, Y is a minor version number, and Z is an incremental bug-fix release number. Incrementing the major version number indicates significant new functionality, and possible backward incompatibilities with previous major versions. Incrementing the minor version number should denote the addition of new functionality, but authors are encouraged to avoid breaking changes when publishing new minor versions. Incrementing the bug-fix version indicates the addition of one or more fixes but should generally not introduce new features or breaking changes.

The ansible-galaxy based YAML format used in the .nucleator/sources.yml file in a Nucleator installation allows the owner of the installation to point to specific versions (scm branches or tags) of required Stacksets. This allows for stable, repeatable behavior even as Stacksets evolve over time. The version: field in sources.yml entries can be used to select a particular version of a Stackset to be used by your Nucleator installation.