release-script

Release tool for npm and bower packages.

---

Description

With this tool there is no need to keep (transpiled) lib, build or distr files in the git repo.

Because Bower keeps its files in the github repo, this tools helps to deal with that too.

Just create new additional github repo for Bower version of your project. This repo will contain only commits generated by this tool.

Say the name of your project is original-project-name then name the bower github repo as original-project-name-bower.

Add 'release-script'.bowerRepo into your package.json:

"release-script": {
  "bowerRepo": "git@github.com:<author>/original-project-name-bower.git"
}

Then add additional step into your building process, which will create bower package files in the amd folder, (basically it is just a process of copying the lib files, README and LICENSE) and that's all.

Now release-script will do all those steps (described next), including bower publishing, for you - automatically.

Initial idea is got from React-Bootstrap release tools ./tools/release, that have been written by Matt Smith @mtscout6

Kind of "migration manual" #23

Documentation pages publishing

If your project generates static documentation pages (as React-Boostrap does) and needs publishing them to a standalone repo (via git push), just create additional github repo for the documentation pages.

E.g. react-bootstrap.github.io.git

Add it as 'release-script'.docsRepo into your package.json:

"release-script": {
  "docsRepo": "git@github.com:<author>/original-project-name-github.io.git"
}

Default folders for documentation pages are:

• "docsRoot": "docs-built" folder where the files will be built to. (by your custom building script)
• "tmpDocsRepo": "tmp-docs-repo" temporary folder. (for the release-script usage)

It is advised to add them both into .gitignore.

You can customize them as you need:

"release-script": {
  "docsRepo": "git@github.com:<author>/original-project-name-github.io.git",
  "docsRoot": "docs-built",
  "tmpDocsRepo": "tmp-docs-repo"
}

If you need to publish only documentation pages (say with some minor fixes), you can do it this way:

> release --only-docs

In this case the package.json version will be bumped with --preid docs as 0.10.0 => 0.10.0-docs.0.

If npm run docs-build script is present, then it will be used instead of npm run build script.

Note: Documentation pages are not published when you are releasing "pre-release" version, (i.e. when you run it with --preid option).

Pre-release versions publishing

Say you need to publish pre-release v0.25.100-pre.0 version with the canary npm tag name (instead of default one latest).

You can do it this way:

> release 0.25.100 --preid pre --tag canary
or
> npm run release 0.25.100 -- --preid pre --tag canary

If your preid tag and npm tag are the same, then you can just:

> release 0.25.100 --preid beta

It will produce v0.25.100-beta.0 and npm publish --tag beta.

changelog generated output will go into CHANGELOG-alpha.md for pre-releases, and with the next release this file will be removed.

Alternative npm package root folder

Say you want to publish the content of your lib folder as an npm package's root folder. Then you can do it as simple as adding the following to your package.json

"release-script": {
  "altPkgRootFolder": "lib"
}

and that's all.

The special case. build step in tests step.

If you run building scripts within your npm run test step, e.g.

"scripts": {
  "test": "npm run lint && npm run build && npm run tests-set",
}

then you can prevent npm run build step from running by setting 'release-script'.skipBuildStep option:

"release-script": {
  "skipBuildStep": "true"
}

Options

All options for this package are kept under 'release-script' node in your project's package.json

• bowerRepo - the full url to github project for the bower pkg files
• bowerRoot - the folder name where your npm run build command will put/transpile files for bower pkg
  • default value: 'amd'
• tmpBowerRepo - the folder name for temporary files for bower pkg.
  • default value: 'tmp-bower-repo'
• altPkgRootFolder - the folder name for alternative npm package's root folder

It is advised to add bowerRoot and tmpBowerRepo folders to your .gitignore file.

Example:

"release-script": {
  "bowerRepo": "git@github.com:<org-author-name>/<name-of-project>-bower.git",
  "bowerRoot": "amd",
  "tmpBowerRepo": "tmp-bower-repo",
  "altPkgRootFolder": "lib"
}

GitHub releases

If you need this script to publish github releases, you can generate a github token at https://github.com/settings/tokens and put it to env.GITHUB_TOKEN this way:

> GITHUB_TOKEN="xxxxxxxxxxxx" && release-script patch

or into your shell scripts

export GITHUB_TOKEN="xxxxxxxxxxxx"

You can set a custom message for github release via --notes CLI option:

> release patch --notes "This is a small fix"

If you need dry-run mode by default

You can setup the release-script to run in dry-run mode by default.

It can be done by setting "true" the defaultDryRun option in your package.json:

"release-script": {
  "defaultDryRun": "true"
}

Then to actually run your commands you will have to add --run.

This script does the following steps:

• ensures that git repo has no pending changes
• ensures that the latest version is fetched
• checks linting and tests by running npm run test command
• does version bumping
• builds all by running npm run build command
  • If there is no build script, then release-script just skips the build step.
• if one of [rf|mt]-changelog is used in 'devDependencies', then changelog is to be generated
• adds and commits package.json with changed version and CHANGELOG.md if it's used
• adds git tag with new version and changelog message if it's used
• pushes changes to github repo
• if github token is present the script publishes the release to the GitHub
• if --preid tag set then npm publish --tag command for npm publishing is used
  • with --tag option one can set npm tag name for a pre-release version (e.g. alpha or canary)
  • otherwise --preid value will be used
• if altPkgRootFolder isn't set it will just npm publish [--tag] as usual. Otherwise:
  • the release-script will npm publish [--tag] from the inside altPkgRootFolder folder
  • scripts and devDependencies will be removed from package.json
• if bowerRepo field is present in the package.json then bower package will be released.
  • the script will clone the bower repo to the tmpBowerRepo folder
  • clean up all files but .git in the tmpBowerRepo folder
  • copy all files from bowerRoot to tmpBowerRepo (they has to be generated by npm run build)
  • add all files to the temporary git repo with git add -A .
  • then it will commit, tag and push. The same as for the npm package.
  • and at the end it will remove the tmpBowerRepo folder
• if docsRepo option is set then documentation pages are being pushed to their repo. It is done the same way as bower publishing process.

If --only-docs command line option is set then github, npm and bower publishing steps will be skipped.

Installation

> npm install -D release-script

If you need bower releases too then add 'release-script'.bowerRepo into your package.json:

"release-script": {
  "bowerRepo": "git@github.com:<org-author-name>/<name-of-project>-bower.git"
}

If you have smth like that in your shell:

# npm
export PATH="./node_modules/.bin:$PATH"

or you had installed release-script globally via npm install -g release-script, then you can release your new versions this way:

> release patch
or
> release minor --preid alpha

Otherwise you need to type in the commands this way:

> ./node_modules/.bin/release minor --preid alpha

You can as well add some helpful script commands to your package.json:

"scripts": {
    ...
    "patch": "release patch",
    "minor": "release minor",
    "major": "release major"

And you can add it like this:

"scripts": {
    ...
    "release": "release",

This way it became possible to run it like that:

> npm run release minor -- --preid alpha
> npm run release patch -- --notes "This is small fix"
> npm run release major --dry-run // for dry run
etc

Notice: You have to add additional double slash -- before any --option. This way additional options get through to release-script.

License

release-script is licensed under the MIT License.