• Version Guide
  • Audience
  • Version Reporting
  • Version Numbering
    • Scope of External API
  • Incrementing Versions

This document describes semantics and processes for providing version numbers for Open MCT, and additionally provides guidelines for dependent projects developed by the same team.

Versions are incremented at specific points in Open MCT's Development Cycle; see that document for a description of sprints and releases.

Individuals interested in consuming version numbers can be categorized as follows:

• Users: Generally disinterested, occasionally wish to identify version to cross-reference against documentation, or to report issues.
• Testers: Want to identify which version of the software they are testing, e.g. to file issues for defects.
• Internal developers: Often, inverse of testers; want to identify which version of software was/is in use when certain behavior is observed. Want to be able to correlate versions in use with “streams” of development (e.g. dev vs. prod), when possible.
• External developers: Need to understand which version of software is in use when developing/maintaining plug-ins, in order to ensure compatibility of their software.

Software versions should be reflected in the user interface of the application in three ways:

• Version number: A semantic version (see below) which serves both to uniquely identify releases, as well as to inform plug-in developers about compatibility with previous releases.
• Revision identifier: While using git, the commit hash. Supports internal developers and testers by uniquely identifying client software snapshots.
• Branding: Identifies which variant is in use. (Typically, Open MCT is re-branded when deployed for a specific mission or center.)

Open MCT shall provide version numbers consistent with Semantic Versioning 2.0.0. In summary, versions are expressed in a "major.minor.patch" form, and incremented based on nature of changes to external API. Breaking changes require a "major" version increment; backwards-compatible changes require a "minor" version increment; neutral changes (such as bug fixes) require a "patch" version increment. A hyphen-separated suffix indicates a pre-release version, which may be unstable or may not fully meet compatibility requirements.

Additionally, the following project-specific standards will be used:

• During development, a "-SNAPSHOT" suffix shall be appended to the version number. The version number before the suffix shall reflect the next expected version number for release.
• Prior to a 1.0.0 release, the minor version will be incremented on a per-release basis; the patch version will be incremented on a per-sprint basis.
• Starting at version 1.0.0, version numbers will be updated with each completed sprint. The version number for the sprint shall be determined relative to the previous released version; the decision to increment the major, minor, or patch version should be made based on the nature of changes during that release. (It is recommended that these numbers are incremented as changes are introduced, such that at end of release the version number may be chosen by simply removing the suffix.)

• The first three sprints in a release may be unstable; in these cases, a unique version identifier should still be generated, but a suffix should be included to indicate that the version is not necessarily production-ready. Recommended suffixes are:

  Sprint | Suffix :------:|:--------: 1 | -alpha 2 | -beta 3 | -rc

"External API" refers to the API exposed to, documented for, and used by plug-in developers. Changes to interfaces used internally by Open MCT (or otherwise not documented for use externally) require only a patch version bump.

At the end of a sprint, the project manager should update (or delegate the task of updating) Open MCT version numbers by the following process:

1. Update version number in package.json
   1. Remove -SNAPSHOT suffix.
   2. Verify that resulting version number meets semantic versioning requirements relative to previous stable version. Increment if necessary.
   3. If version is considered unstable (which may be the case during the first three sprints of a release), apply a new suffix per Version Numbering guidance above.
2. Tag the release.
   1. Commit changes to package.json on the master branch. The commit message should reference the sprint being closed, preferably by a URL reference to the associated Milestone in GitHub.
   2. Verify that build still completes, that application passes smoke-testing, and that only differences from tested versions are the changes to version number above.
   3. Push the master branch.
   4. Tag this commit with the version number, prepending the letter "v". (e.g. git tag v0.9.3-alpha)
   5. Push the tag to GitHub. (e.g. git push origin v0.9.3-alpha).
3. Upload a release archive.
   1. Run npm pack to generate the archive.
   2. Use the GitHub release interface to draft a new release.
   3. Choose the existing tag for the new version (created and pushed above.) Enter the tag name as the release name as well; see existing releases for examples.
   4. Attach the release archive.
   5. Designate the release as a "pre-release" as appropriate (for instance, when the version number has been suffixed as unstable, or when the version number is below 1.0.0.)
4. Restore snapshot status in package.json
   1. Remove any suffix from the version number, or increment the patch version if there is no suffix.
   2. Append a -SNAPSHOT suffix.
   3. Commit changes to package.json on the master branch. The commit message should reference the sprint being opened, preferably by a URL reference to the associated Milestone in GitHub.
   4. Verify that build still completes, that application passes smoke-testing.
   5. Push the master branch.

Projects dependent on Open MCT being co-developed by the Open MCT team should follow a similar process, except that they should additionally update their dependency on Open MCT to point to the latest archive when removing their -SNAPSHOT status, and that they should be pointed back to the master branch after this has completed.