How Trails Manages Releases

Trails Release Process

Major Releases

Schedule

Trails releases new major versions every six months, in April and October, to remain in sync with the Node.js Maintenance Cycle. Trails assigns versions according to semver, and "major" version results in the increment of the left-most position in the version. A major version contains potential incompatibilities with previous versions

Pre-Release Considerations

Trails automatically tests itself against all ecosystem modules that are maintained by the Trails team. One important benefit is we can run public continuous integration tests against new Major versions of dependent modules before releasing a new Major version of Trails itself. By employing semver across the Trails ecosystem, the Major versions of ecosystem modules will align with the major version of Trails in order to indicate compatibility.

New Major versions of Trailpacks can be safely released into the wild before a Major release of Trails. When a new project is created using the Trails Generator, the major versions of selected Trailpacks will align with the latest major version available for Trails. Newer major releases of Trailpacks must be explicitly installed by the developer.

Migration Path

Once the changeset for a release has been identified, a verifiable migration process should be documented and tested. Starting with Trails v3.0, major version releases will include migration as part of the continuous integration and testing process.

Release Process

I. Create a Release Candidate

When the maintainers are ready to tag a new major version of Trails, it first must be published as a Release Candidate. Each Release Candidate must pass the Ecosystem CI tests before being promoted to a GA (General Availability) release. To submit a release candidate to testing, the following must occur:

1. Bump version of the trails dependency in the necessary ecosystem modules to v2-latest to indicate they are intended to be compatible with the next version of Trails, and bump the versions of the modules themselves to the next major version, e.g. 2.0.0. The ecosystem modules to which this process applies are currently:

• trails/archetype
• smokesignals
• generator-trails
• trailpack
• trailpack-repl
• trailpack-router
• trailpack-hapi
• trailpack-express

e.g.

  {
    "name": "smokesignals",
    "version": "2.0.0",
    ...
    "devDependencies": {
      "trails": "v2-latest"
    }
  }

Push these changes to the respective repositories and publish the versions per the usual Release Process.

2. Bump the version of Trails itself to Release Candidate and manually publish this version, e.g.

   npm version 2.0.0-rc1
   npm publish
   npm dist-tags add trails@2.0.0-rc1 v2-latest
   

3. Push the new tag to Github

   git push origin master
   git push origin --tags
   

This will trigger a CI build. If issues are found, this process is repeated by creating a new Release Candidate and incrementing the RC number e.g. 2.0.0-rc2.

II. Promote Release Candidate

Once a Release Candidate has passed CI, it can be tagged for General Availability.

1. Promote the tag, trigger another round of CI. When successful, Travis-CI will publish the new release to npm.

npm version 2.0.0
git push origin master
git push origin --tags

2. Publish the Release to npm

npm dist-tags add trails@2.0.0 latest

3. Publish the Release to Github, documenting the changes

https://github.com/trailsjs/trails/releases