iolaus

Iolaus is an opinionated versioning system built to support large monorepos using lerna with independently versioned sub-components. Named after the hero who assisted Heracles in the fight against the Hydra of Lerna.

How it Works

1. uses your existing lerna configuration to find all packages in your repo
2. looks back in history to find all commits since your latest release on github
3. creates a list of packages which should update, and the semantically correct verions to bump them to along
4. commits the updated versions and updated dependencies along with a changelog for the changed packages
5. creates appropriate github releases
6. creates appropriate npm releases

Getting Started

Install iolaus a dev dependency in your project as well as lerna and semantic-release which it relies on to run.

npm install -D iolaus lerna semantic-release
# or
yarn add -D iolaus lerna semantic-release

Add a release script to your package.json.

{
  "scripts": {
    "release": "iolaus"
  }
}

Now you can simply run the release script in your CI whenever you want to check for and then perform a release. Note that releases will only be generated when it is required based on analysis of commit messages.

Formatting Commit Messages

Commit messages must indicate whether a patch, minor or major release needs to occur to satisfy semantic versioning. They also have to specify which packages are affected by the commit.

To accomplish this we currently support the format generated by commitizen when using the cz-lerna-changelog plugin. See the commitizen documentation for how to add it to your workflow.

Environment Variables

In order to authenticate with Github and npm you need to supply the following environment variables.

• NPM_TOKEN: the token used for authenticating with npm to release packages
• GH_TOKEN: a github token with repo privelages for pushing commits and tags generated during release

Configuration

You can provide configuration for iolaus using a configuration file like .iolausrc, .iolausrc.yml or anything supported by cosmiconfig.

Configuration Options

• branch: the branch to run a release on, defaults to 'master'
• dryRun: skip the release and tag generation when true. CHANGELOG.md and package.json files will be modified
• initial: create initial releases for all packages with no previous git tag when true
• npmRegistry: the npm registry to push to, defaults to 'https://registry.npmjs.org/'
• releaseAssets: an array of file globs for files to include as release assets, defaults to []

CLI Arguments

When running iolaus you can pass a number of flags to change its functionality.

• --config, -c: the configuration file to read from, otherwise uses cosmiconfig to search from the working directory
• --branch, -b: the branch to run a release on, defaults to 'master'
• --registry, -r: the npm registry to push to, defaults to 'https://registry.npmjs.org/'
• --dry-run, -d: skip the release and tag generation. CHANGELOG.md and package.json files will be modified
• --initial, -i: create initial releases for all packages with no previous git tag