openmct/docs/src/process/version.md

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; 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. 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 should update (or delegate the task of updating) Open MCT version numbers by the following process:

1. Update version number in package.json
2. Checkout branch created for the last sprint that has been successfully tested.
3. Remove a -SNAPSHOT suffix from the version in package.json.
4. Verify that resulting version number meets semantic versioning requirements relative to previous stable version. Increment the version number if necessary.
5. 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.
6. Tag the release.
7. Commit changes to package.json on the new branch created in the previous step. The commit message should reference the sprint being closed, preferably by a URL reference to the associated Milestone in GitHub.
8. Verify that build still completes, that application passes smoke-testing, and that only differences from tested versions are the changes to version number above.
9. Push the new branch.
10. Tag this commit with the version number, prepending the letter "v". (e.g. git tag v0.9.3-alpha)
11. Push the tag to GitHub. (e.g. git push origin v0.9.3-alpha).
12. Upload a release archive.
13. Use the GitHub release interface to draft a new release.
14. 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. (e.g. Open MCT v0.9.3-alpha)
15. 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.)
16. Add release notes including any breaking changes, enhancements, bug fixes with solutions in brief.
17. Publish the release.
18. Publish the release to npm
19. Login to npm
20. Checkout the tag created in the previous step.
21. In package.json change package to be public (private: false)
22. Test the package before publishing by doing npm publish --dry-run if necessary.
23. Publish the package to the npmjs registry (e.g. npm publish --access public) NOTE: Use the --tag unstable flag to the npm publishj if this is a prerelease.
24. Confirm the package has been published (e.g. https://www.npmjs.com/package/openmct)
25. Update snapshot status in package.json
26. Create a new branch off the master branch.
27. Remove any suffix from the version number, or increment the patch version if there is no suffix.
28. Append a -SNAPSHOT suffix.
29. 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.
30. Verify that build still completes, that application passes smoke-testing.
31. Create a PR to be merged into 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.