Releases and dependency updates

A document about the release and dependency update timelines and about how to make a release.

Release and package update timelines

• One release every 2 months (after each planning session of the work for the next two months for the core committers)
• Dependency updates:
  • Dependency update right after the release
  • Dependency update ~1 month after the release (when a new three.js version is released)
• Core committers take turns making releases

Release process

Submit a release

To submit a release, one needs to:

• checkout from iTowns' master branch on a new local branch
• run npm run bump locally
• run npm install (to increase itowns version number in package-lock.json)
• submit the automatically generated commit - without changing its name - in a pull request

The bump script is the following:

if [ -z $npm_config_level ]; then grunt bump:minor; else grunt bump:$npm_config_level; fi && npm run changelog && git add -A && git commit --amend --no-edit"

It:

• uses grunt-bump framework to change the version number in package.json, package-lock.json and src/Main.js. These changes are saved in a commit named release vX.X.X. By default, a minor version update is made. It can be changed by setting an environment variable named npm_config_level prior to running bump script. grunt-bump documentation provides the supported values for npm_config_level. For instance, to push a major version bump, the following should be run:

export npm_config_level="major"
npm run bump

• uses conventional-changelog-cli to update changelog.md file with all commits pushed since the latest published version. The configuration file for this framework is at config/conventionalChangelog/config.js. The modifications to changelog.md are added to the previously created commit.

Publish a release

The publication of a release is a process of three independent steps, that is automated in the integration/deployment script. This process is launched each time a commit with a name like release vX.X.X (like the one automatically generated when running the bump script) is merged into master branch.

The three steps are:

• The publication of iTowns package in npm public registry
• The deployment of iTowns package in itowns examples and documentation website
• The creation of a GitHub release published on iTowns' GitHub releases page with the appropriate tag

These three steps should not require any human action under normal conditions, with the exception of the third one (the publication of a GitHub release). When publishing a release, GitHub describes the changes it brings with all that is contained within changelog.md file. Yet this file contains changes for all previous iTowns versions. Therefore, the changelog published on iTowns' GitHub releases page should be manually edited to remove changes from previous versions.