[Documentation] Add Version Guide

Migrate relevant information from existing version guide;
add instructions for incrementing versions per #725

docs/src/process/cycle.md

@@ -151,11 +151,9 @@ emphasis on testing.
   ensuring software passes that testing in order to ship on time;
   may prefer to disable malfunctioning components and fix them
   in a subsequent sprint, for example.
-* __Ship.__ Tag a code snapshot that has passed acceptance
+* [__Ship.__](version.md) Tag a code snapshot that has passed release/sprint
-  testing and deploy that version. (Only true if acceptance
+  testing and deploy that version. (Only true if relevant
-  testing has passed by this point; if acceptance testing has not
+  testing has passed by this point; if testing has not
   been passed, will need to make ad hoc decisions with stakeholders,
   e.g. "extend the sprint" or "defer shipment until end of next
   sprint.")
-
-

docs/src/process/index.md

@@ -3,8 +3,10 @@
 The process used to develop Open MCT Web is described in the following
 documents:
 
-* [Development Cycle](cycle.md): Describes how and when specific
+* The [Development Cycle](cycle.md) describes how and when specific
   process points are repeated during development.
+* The [Version Guide](version.md) describes version numbering for
+  Open MCT (both semantics and process.)
 * Testing is described in two documents:
   * The [Test Plan](testing/plan.md) summarizes the approaches used
     to test Open MCT Web.

docs/src/process/version.md

@@ -0,0 +1,142 @@
+# 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.