# release-script

Release tool for npm and bower packages.

[![Build Status](https://travis-ci.org/AlexKVal/release-script.svg)](https://travis-ci.org/AlexKVal/release-script)

---
#### 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`:
```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](https://github.com/mtscout6)_

_Kind of "migration manual"_ https://github.com/AlexKVal/release-script/issues/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](https://github.com/react-bootstrap/react-bootstrap.github.io)

Add it as `'release-script'.docsRepo` into your `package.json`:
```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:
```json
"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`
```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.
```json
"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:
```json
"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:
```json
"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:
```sh
> GITHUB_TOKEN="xxxxxxxxxxxx" && release-script patch
```
or into your shell scripts
```sh
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`:
```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

```sh
> npm install -D release-script
```

If you need `bower` releases too then add `'release-script'.bowerRepo` into your `package.json`:
```json
"release-script": {
  "bowerRepo": "git@github.com:<org-author-name>/<name-of-project>-bower.git"
}
```

If you have smth like that in your shell:
```sh
# 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:
```sh
> release patch
or
> release minor --preid alpha
```

Otherwise you need to type in the commands this way:
```sh
> ./node_modules/.bin/release minor --preid alpha
```

You can as well add some helpful `script` commands to your `package.json`:
```json
"scripts": {
    ...
    "patch": "release patch",
    "minor": "release minor",
    "major": "release major"
```

And you can add it like this:
```json
"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](https://github.com/alexkval/release-script/blob/master/LICENSE).