A tool for automating the release of libraries in the spirit of semantic-release.
- Automatically tags pull requests with
semver-{patch,minor,major,none}
based on the commit history - All information is also part of the git history
- Smart
CHANGELOG.md
generator that incorporates pull request data - Adds license headers for JavaScript and CoffeeScript files
- A Github access token with
repo
scope. This is required for creating version commits, releases, and tagging issues. Github has a instructions for creating an access token. - A valid repository field in your
package.json
. E.g.https://github.mycorp.net/myorg/repo.git
orhttps://github.com/myorg/repo.git
. - The repository field should point to an existing project on Github.
- Run
npm install --save-dev nlm
. - Enter the Github token when prompted. This will be used to create the required labels on the repository.
nlm
will offer to write the properposttest
script if your repository doesn't contain one yet. It will also write apublishConfig.registry
field, defaulting to your current npm registry setting.
After this you should have nlm release
in your posttest
script and 4 semver-*
labels in your Github project.
nlm
will automatically look for well-known environment variables during CI builds like CI=true
, BRANCH=branch-name
, etc..
It should work out-of-the-box for both Travis and DotCI.
For Github and npm interactions to work, it requires the following additional environment variables:
GH_TOKEN
: The access token from above.NPM_TOKEN
: An npm access token. You can find this in~/.npmrc
as_authToken
.
For registries that don't support _authToken
,
it's possible to configure NPM_USERNAME
, NPM_EMAIL
, and NPM_PASSWORD_BASE64
instead.
Those values can be found in your ~/.npmrc
as username
, email
, and _password
.
All tokens and passwords should be set up as encrypted environment variables.
For Travis you can follow the official Travis docs:
travis encrypt GH_TOKEN=your_github_token --add env
If you want to publish from CI, you can either use the official Travis feature or nlm
itself.
The latter gives you support for managing different dist-tag
s based on branches.
If you want to use nlm
to publish, you'll have to add NPM_TOKEN
:
travis encrypt NPM_TOKEN=your_npm_token --add env
DotCI lacks native support for encrypted environment variables. But the EnvInject Plugin provides an option called "Inject passwords to the build as environment variables" which can fill the same role.
You should also enable builds of pull requests for pushes against the same repository. Otherwise the automated tagging of PRs won't work.
Finally enable publishing by adding the following to .ci.yml
:
build:
<% if (DOTCI_BRANCH == 'master') { %>
after:
- ./node_modules/.bin/nlm publish
<% } %>
Most nlm
configuration happens via native npm options in package.json
:
repository
: This field is parsed to detect Github API baseUrl and repository name.nlm
supports both public Github and Github Enterprise instances. For Github Enterprise, it assumes the API to be athttps://<hostname>/api/v3
.files
: By defaultnlm
will add license headers to everything listed here.
In most cases these settings are enough to make nlm
do the right thing.
For more customization, you can use .nlmrc
or an nlm
section in package.json
:
channels
: A map of branch name to npmdist-tag
. When publishing, this will determine what will be published and how it's tagged. By default there's one entry in this map:{ master: 'latest' }
. Which means that a publish frommaster
updates thelatest
tag and publish from any other branch does nothing.license.files
: List of files and/or directories to add license headers to.license.exclude
: List of files to exclude that would otherwise be included.nlm
will always exclude anything innode_modules
.
If there's no file named LICENSE
in the repository, nlm
won't attempt to add the headers.
Intended use: Run once in a project.
Parses an existing package.json
and makes changes to support nlm
.
- Ask for a Github API token.
- Add the
semver-patch
,semver-minor
, andsemver-major
labels. - Add
nlm release
as aposttest
script. - Set
publishConfig.registry
(default: read from npm config).
Intended use: posttest
script for matrix builds.
Verify that the current state is valid and could be released. Will also add license headers where they are missing.
- Add missing license headers.
- Verify that the checkout is clean.
- Collect change log items and determine what kind of change it is.
Intended use: deploy
script, or posttest
script if not running matrix builds.
Verify that the current state is valid and could be released. Will also add license headers where they are missing.
- Everything
nlm verify
does. - If there are unreleased changes:
- Create a new CHANGELOG entry and update
package.json#version
. - Commit and tag the release.
- Push the tag and the release branch (e.g. master).
- Create a Github release.
- Publish the package to npm or update
dist-tag
if required.
By default nlm release
will not do anything unless it's running on CI.
You can force a release by running nlm release --commit
.
Preview the changelog that would be generated by the commits between the last version tag and the current HEAD
.
If there are no unreleased commits, the output will be empty.