Based on the current roadmap for v3.0, it will take several months until we will be able to cut the final 3.0.0 release. In the meantime, we need keep improving 2.x series that most customers are running on. This document describes the process.
Note that we are bumping up the major version to 3.0 primarily in order to allow us to make breaking changes, as ruled by semver. This is different from marketing practice of bumping up the major version to create an impression that the product has matured to a next level.
Not all loopback modules have to be bumped to 3.0. We will keep using the current major version (typically 2.x) in all modules where we can preserve backwards compatibility. The major version will be bumped (and a major-version branch will be created) only at the point when we need to land a backwards incompatible (breaking) change.
Branch setup: most patches should be landed on the master branch, the new 3.0 release will be eventually released from master too. In order to allow us to back-port changes to 2.x and make new 2.x releases, each repository affected should create a branch called "2.x". (We already have "1.x" branch for the first major version.)
It is up to the discretion of reviewers to decide which changes to back-port from master to 2.x. Initially, we should probably land all bug fixes and most backwards-compatible enhancements. This rule should be revisited once 3.0.0 was released.
To make it easy for LB developers to test out the upcoming 3.0 version, we should regularly publish pre-release versions to npmjs. However, extra care must be taken to ensure "npm install" keeps downloading the current 2.x series.
When forking off a 2.x branch, we need to change package.json on the master branch and change the version string to "3.0.0-alpha.1" add the following bit: "publishConfig": { "tag": "next" }
Whenever making a new pre-release version, increment the latest number: 3.0.0-alpha.2, 3.0.0-alpha.3, etc. Once get closer to the release date, we can release 3.0.0-beta.1, possibly also 3.0.0-rc.1.
The benefit of this version scheme is that module consumers can use carrot operator to get automatic updates: "^3.0.0-alpha.1" matches all versions in the previous paragraph.
We will need a detailed release notes for 3.0. To make our life easier, we should build them incrementally in a file called "RELEASE-NOTES.md". Each pull request containing a major change must include an update of RELEASE-NOTES describing the change for a user upgrading from 2.x to 3.0.