# Version Guide

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](cycle.md); see that document for a description of
sprints and releases.

## Audience

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.

## Version Reporting

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.)

## Version Numbering

Open MCT shall provide version numbers consistent with
[Semantic Versioning 2.0.0](http://semver.org/). 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`

### Scope of External API

"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.

## Incrementing Versions

At the end of a sprint, the [project manager](cycle.md#roles)
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](#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](https://github.com/nasa/openmct/releases)
     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.
