diff --git a/README.md b/README.md index 6b1a06645..38b37fc08 100644 --- a/README.md +++ b/README.md @@ -2,67 +2,10 @@ > Generate a changelog from git metadata -[Synopsis of Conventions](conventions) +You are probably looking for the [cli](https://github.com/stevemao/conventional-changelog-cli) module. Or use one of the plugins if you are already using the tool: [grunt](https://github.com/btford/grunt-conventional-changelog)/[gulp](https://github.com/stevemao/gulp-conventional-changelog)/[atom](https://github.com/stevemao/atom-conventional-changelog). -## Quick start - -```sh -$ npm install -g conventional-changelog -$ cd my-project -$ conventional-changelog -p angular -i CHANGELOG.md -w -``` - -This will *not* overwrite any previous changelog. The above generates a changelog based on commits since the last semver tag that match the pattern of a "Feature", "Fix", "Performance Improvement" or "Breaking Changes". - -If you first time use this tool and want to generate all previous changelog, you could do - -```sh -$ conventional-changelog -p angular -i CHANGELOG.md -w -r 0 -``` - -This *will* overwrite any previous changelog if exist. - -All available command line parameters can be listed using [CLI](#cli) : `conventional-changelog --help`. - -**Hint:** You can alias your command or add it to your package.json. EG: `"changelog": "conventional-changelog -p angular -i CHANGELOG.md -w -r 0"`. - -Or use one of the plugins if you are already using the tool: [grunt](https://github.com/btford/grunt-conventional-changelog)/[gulp](https://github.com/stevemao/gulp-conventional-changelog)/[atom](https://github.com/stevemao/atom-conventional-changelog) - - -## Recommended workflow - -1. Make changes -2. Commit those changes -3. Make sure Travis turns green -4. Bump version in `package.json` -5. `conventionalChangelog` -6. Commit `package.json` and `CHANGELOG.md` files -7. Tag -8. Push - -The reason why you should commit and tag after `conventionalChangelog` is that the CHANGELOG should be included in the new release, hence `gitRawCommitsOpts.from` defaults to the latest semver tag. - -Please use this [gist](https://gist.github.com/stevemao/280ef22ee861323993a0) to make a release or change it to your needs. - - -## Example output - -- https://github.com/ajoslin/conventional-changelog/blob/master/CHANGELOG.md -- https://github.com/karma-runner/karma/blob/master/CHANGELOG.md -- https://github.com/btford/grunt-conventional-changelog/blob/master/CHANGELOG.md - - -## Why - -- Used by AngularJS and related projects. -- Ignoring reverted commits, templating with [handlebars.js](https://github.com/wycats/handlebars.js) and links to references, etc. Open an [issue](../../issues/new) if you want more reasonable features. -- Intelligently setup defaults but yet fully configurable with presets of popular projects. -- Everything internally or externally is pluggable. -- A lot of tests and actively maintained. - - -## Programmatic usage +## Usage ```sh $ npm install --save conventional-changelog @@ -86,148 +29,13 @@ Returns a readable stream. #### options -##### preset - -Type: `string` [Possible values](presets) - -It's recommended to use a preset so you don't have to define everything yourself. The preset values can be overwritten. - -##### pkg - -Type: `object` - -###### path - -Type: `string` Default: [closest package.json](https://github.com/sindresorhus/read-pkg-up). - -The location of your "package.json". - -###### transform - -Type: `function` Default: pass through. - -A function that takes `package.json` data as the argument and returns the modified data. Note this is performed before normalizing package.json data. Useful when you need to add a leading 'v' to your version or modify your repository url, etc. - -##### append - -Type: `boolean` Default: `false` - -Should the log be appended to existing data. - -##### releaseCount - -Type: `number` Default: `1` - -How many releases of changelog you want to generate. It counts from the upcoming release. Useful when you forgot to generate any previous changelog. Set to `0` to regenerate all. - -##### warn - -Type: `function` Default: `function() {}` - -A warn function. EG: `grunt.verbose.writeln` - -##### transform - -Type: `function` Default: get the version (without leading 'v') from tag and format date. - -###### function(commit, cb) +See the [conventional-changelog-core](https://github.com/stevemao/conventional-changelog-core) docs. The API is exactly the same with some additions: -A transform function that applies after the parser and before the writer. - -This is the place to modify the parsed commits. - -####### commit - -The commit from conventional-commits-parser. - -####### cb - -Callback when you are done. - -####### this - -`this` arg of through2. - -#### context - -See the [conventional-changelog-writer](https://github.com/stevemao/conventional-changelog-writer) docs. There are some defaults or changes: - -##### host - -Default: normalized host found in `package.json`. - -##### version - -Default: version found in `package.json`. - -##### owner - -Default: extracted from normalized `package.json` `repository.url` field. - -##### repository - -Default: extracted from normalized `package.json` `repository.url` field. - -##### gitSemverTags - -Type: `array` - -All git semver tags found in the repository. You can't overwrite this value. - -##### previousTag - -Type: `string` Default: previous tag or the first commit hash if no previous tag. - -##### currentTag - -Type: `string` Default: current tag or `'v'` + version if no current tag. - -##### packageData - -Type: `object` - -Your `package.json` data. You can't overwrite this value. - -##### linkCompare - -Type: `boolean` Default: `true` if `previousTag` and `currentTag` are truthy. - -Should link to the page that compares current tag with previous tag? - -#### gitRawCommitsOpts - -See the [git-raw-commits](https://github.com/stevemao/git-raw-commits) docs. There are some defaults: - -##### format - -Default: `'%B%n-hash-%n%H%n-gitTags-%n%d%n-committerDate-%n%ci'` - -##### from - -Default: based on `options.releaseCount`. - -##### reverse - -Default: only `true` if `options.append` is truthy. - -#### parserOpts - -See the [conventional-commits-parser](https://github.com/stevemao/conventional-commits-parser) docs. - -#### writerOpts - -See the [conventional-changelog-writer](https://github.com/stevemao/conventional-changelog-writer) docs. There are some defaults: - -##### reverse - -Default: same as `options.append`. +##### preset -### CLI +Type: `string` Possible values: `'angular', 'atom', 'codemirror', 'ember', 'eslint', 'express', 'jquery', 'jscs', 'jshint'` -```sh -$ npm install --global conventional-changelog -$ conventional-changelog --help # for more details -``` +It's recommended to use a preset so you don't have to define everything yourself. The preset values can be overwritten. This value is case insensitive. ## Notes for parent modules diff --git a/cli.js b/cli.js deleted file mode 100755 index a88d435eb..000000000 --- a/cli.js +++ /dev/null @@ -1,172 +0,0 @@ -#!/usr/bin/env node -'use strict'; -var addStream = require('add-stream'); -var conventionalChangelog = require('./'); -var fs = require('fs'); -var meow = require('meow'); -var tempfile = require('tempfile'); -var _ = require('lodash'); -var resolve = require('path').resolve; - -var cli = meow({ - help: [ - 'Usage', - ' conventional-changelog', - '', - 'Example', - ' conventional-changelog -i CHANGELOG.md --overwrite', - '', - 'Options', - ' -i, --infile Read the CHANGELOG from this file', - ' -o, --outfile Write the CHANGELOG to this file. If unspecified, it prints to stdout', - ' -w, --overwrite Overwrite the infile', - ' -p, --preset Name of the preset you want to use', - ' -k, --pkg A filepath of where your package.json is located', - ' -a, --append Should the generated block be appended', - ' -r, --release-count How many releases to be generated from the latest', - ' -v, --verbose Verbose output', - ' -c, --context A filepath of a javascript that is used to define template variables', - ' --git-raw-commits-opts A filepath of a javascript that is used to define git-raw-commits options', - ' --parser-opts A filepath of a javascript that is used to define conventional-commits-parser options', - ' --writer-opts A filepath of a javascript that is used to define conventional-changelog-writer options' - ] -}, { - alias: { - i: 'infile', - o: 'outfile', - w: 'overwrite', - p: 'preset', - k: 'pkg', - a: 'append', - r: 'releaseCount', - v: 'verbose', - c: 'context' - } -}); - -var flags = cli.flags; -var infile = flags.infile; -var outfile = flags.outfile; -var overwrite = flags.overwrite; -var append = flags.append; -var releaseCount = flags.releaseCount; - -if (infile && infile === outfile) { - overwrite = true; -} else if (overwrite) { - if (infile) { - outfile = infile; - } else { - console.error('Nothing to overwrite'); - process.exit(1); - } -} - -var options = _.omit({ - preset: flags.preset, - pkg: { - path: flags.pkg - }, - append: append, - releaseCount: releaseCount -}, _.isUndefined); - -if (flags.verbose) { - options.warn = console.warn.bind(console); -} - -var templateContext; -var gitRawCommitsOpts; -var parserOpts; -var writerOpts; - -var outStream; - -try { - if (flags.context) { - templateContext = require(resolve(process.cwd(), flags.context)); - } - - if (flags.gitRawCommitsOpts) { - gitRawCommitsOpts = require(resolve(process.cwd(), flags.gitRawCommitsOpts)); - } - - if (flags.parserOpts) { - parserOpts = require(resolve(process.cwd(), flags.parserOpts)); - } - - if (flags.writerOpts) { - writerOpts = require(resolve(process.cwd(), flags.writerOpts)); - } -} catch (err) { - console.error('Failed to get file. ' + err); - process.exit(1); -} - -var changelogStream = conventionalChangelog(options, templateContext, gitRawCommitsOpts, parserOpts, writerOpts) - .on('error', function(err) { - if (flags.verbose) { - console.error(err.stack); - } else { - console.error(err.toString()); - } - process.exit(1); - }); - -function noInputFile() { - if (outfile) { - outStream = fs.createWriteStream(outfile); - } else { - outStream = process.stdout; - } - - changelogStream - .pipe(outStream); -} - -if (infile && releaseCount !== 0) { - var readStream = fs.createReadStream(infile) - .on('error', function() { - noInputFile(); - }); - - if (overwrite) { - if (options.append) { - changelogStream - .pipe(fs.createWriteStream(outfile, { - flags: 'a' - })); - } else { - var tmp = tempfile(); - - changelogStream - .pipe(addStream(readStream)) - .pipe(fs.createWriteStream(tmp)) - .on('finish', function() { - fs.createReadStream(tmp) - .pipe(fs.createWriteStream(outfile)); - }); - } - } else { - if (outfile) { - outStream = fs.createWriteStream(outfile); - } else { - outStream = process.stdout; - } - - var stream; - - if (options.append) { - stream = readStream - .pipe(addStream(changelogStream)); - } else { - stream = changelogStream - .pipe(addStream(readStream)); - } - - stream - .pipe(outStream); - } -} else { - noInputFile(); -} diff --git a/conventions/angular.md b/conventions/angular.md deleted file mode 100644 index 9fb433836..000000000 --- a/conventions/angular.md +++ /dev/null @@ -1,89 +0,0 @@ -#### Examples - -Appears under "Features" header, pencil subheader: - -``` -feat(pencil): add 'graphiteWidth' option -``` - -Appears under "Bug Fixes" header, graphite subheader, with a link to issue #28: - -``` -fix(graphite): stop graphite breaking when width < 0.1 - -Closes #28 -``` - -Appears under "Performance Improvements" header, and under "Breaking Changes" with the breaking change explanation: - -``` -perf(pencil): remove graphiteWidth option - -BREAKING CHANGE: The graphiteWidth option has been removed. The default graphite width of 10mm is always used for performance reason. -``` - -The following commit and commit `667ecc1` do not appear in the changelog if they are under the same release. If not, the revert commit appears under the "Reverts" header. - -``` -revert: feat(pencil): add 'graphiteWidth' option - -This reverts commit 667ecc1654a317a13331b17617d973392f415f02. -``` - -### Commit Message Format - -A commit message consists of a **header**, **body** and **footer**. The header has a **type**, **scope** and **subject**: - -``` -(): - - - -