Fast: Versioning and release strategy

[janechu]

Versioning

• Current situation: Synced versions on all packages
• Issue: This means we are major version bumping all packages whether they contain breaking changes or not, this is unneccessary and will cause the user issues when trying to get latest, we already ensure correct version of peer dependencies via lerna
• Solution: Switch to independent mode, this will result in Lerna splitting the conventional commits for each package and properly bumping to the right version.

Next steps

1. Add package-lock.json files to the .gitignore and package-lock=false to all .npmrc files to avoid generating them - if this is not done it will result in false positives from other pull requests, eg. a pull request is merged in that is a breaking change on package "a" but includes an updated package-lock.json from package "b". Since the package-lock.json has updated from a breaking change commit a major version bump will occur on both package "a" and "b". We will also be able to remove the clean script at root level.
2. Bump a patch version in fixed version mode, this should add all the relevent git tags for individual packages. For clarification git tags are added when using the lerna version --conventional-commits and lerna publish --conventional-commits commands. On independent mode a tag will be added for each package denoting its version eg. @microsoft/[email protected]
3. Update the lerna.json and mark the version as "independent"

Major features, new packages and breaking changes

• Current situation: No strategy for large scale changes such as major features and breaking changes
• Issue: We should be isolating unstable major features and breaking changes before allowing them into master
• Solution: Add documentation for creating a branch for major features and breaking changes, this will give us the opportunity to have various prereleases be published

Proposal

Create prerelease branches for our major features and breaking changes. This will mean that master is always stable and can release, thus fixes and smaller features can continue to go in and be released.

The conventional approach for larger frameworks and libraries is to use stable release branches. Smaller libraries such as lodash will follow the prelease branch strategy, as FAST-DNA is essentually a collection of smaller libraries it seems more maintainable to go with the same approach.

Npm tagging

Important Note: An issue may arise where we want to create a release candidate, alpha or beta while developing a major feature, new package or implementing breaking changes. Currently the user expects to be able to use npm i package-name and this will install the latest. Unfortunately unless specified otherwise the latest tag will be applied to all packages. What this means is that if a package is published with an appended -alpha.*, -beta.* or -rc.* it will be installed by default if its the latest. This requires the use of an npm tag, one of the most commonly used for this purpose is next. See npm documentation.

Next steps

Add to the wiki the strategy for creating alpha/beta/release candidate branch which should include:

• Branch naming conventions (this will allow us to protect branches using globbing patterns):
  
  
  
  • major feature - feature/new-package-for-foo
  
  
  • breaking change - eg. release-candidate/update-form-generator-to-use-non-executable-code
  
  
• Tagging for npm as noted above

Going forward these steps should:

1. Ensure our versioning is always correct and up to date with each package
2. Remove issues regarding major or minor version bumps occuring on packages that have had no updates
3. Remove a long-standing issue with package-locks
4. Allow proper automated tagging for commits which has been missing
5. Provide documentation for any major changes going forward which require alpha/beta/rc prerelease semver

[nicholasrice]

@janechu in addition to adding package-locks to the .gitignore, we should also add package-lock=false to all .npmrc files to avoid generating them in the first place.

[janechu]

@nicholasrice agreed, updated.

[chrisdholt]

Removing package locks seem great when isolated to our versioning story - are there potential side effects though for users? Perhaps expand a bit more on why we are removing them altogether rather than managing them as this could raise some eyebrows.

[nicholasrice]

According to https://docs.npmjs.com/files/package-lock.json this change will be transparent to all consumers because package-lock.json files cannot be published, meaning they never had any effect to begin with.

[nalogiudice]

"3. Remove a long-standing issue with package-locks" thank you x100

[chrisdholt]

Regarding "4" above - I might be missing these, but do we have a definition of when to use certain NPM tags (alpha, beta, rc) and how it is automated as part of this proposal?

[awentzel]

Agree with @chrisdholt, our documentation on the wiki should clearly describe our strategy as well as define key terminology or link to where it is defined. Alpha, beta, etc.

[janechu]

@chrisdholt I was referring to git commits in 4, the method previously used on lerna and the way in which pull requests were being merged in was removing the git tags that lerna was adding, that is why the conventional commit logs were always wrong. Lerna basically looks back to the last git tag it recognizes and counts the commits from there to the present, looks at the files that were changed and updates the changelogs based on that. I investigated with @nicholasrice who then fixed our handling of that for the same version mode we were doing, the steps outlined above are what need to happen to switch to independent mode.

Npm tagging would have to be manual, as it should for any prerelease because there's no way to automatically identify what you would want as a prerelease.

@awentzel this proposal outlines a strategy which includes adding said documentation to the wiki.

[awentzel]

I approve this approach.

[chrisdholt]

Thanks for clarifying @janechu. Since I'm just getting back to if after a vacation, I'm at the mercy of the details on here. :)

This looks good to me.

[janechu]

All related issues have been closed.