256 lines
8.5 KiB
Markdown
256 lines
8.5 KiB
Markdown
# [![NPM version][npm-image]][npm-url] [![Build Status: Linux][travis-image]][travis-url] [![Build Status: Windows][appveyor-image]][appveyor-url] [![Dependency Status][daviddm-image]][daviddm-url] [![Coverage Status][coveralls-image]][coveralls-url]
|
|
|
|
> [conventional-changelog](https://github.com/conventional-changelog/conventional-changelog) core
|
|
|
|
You are probably looking for the [cli](https://github.com/conventional-changelog/conventional-changelog/tree/master/packages/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/conventional-changelog/conventional-changelog/tree/master/packages/gulp-conventional-changelog)/[atom](https://github.com/conventional-changelog/conventional-changelog/tree/master/packages/conventional-changelog-atom).
|
|
|
|
## Usage
|
|
|
|
```sh
|
|
$ npm install --save conventional-changelog-core
|
|
```
|
|
|
|
```js
|
|
var conventionalChangelogCore = require('conventional-changelog-core');
|
|
|
|
conventionalChangelogCore()
|
|
.pipe(process.stdout); // or any writable stream
|
|
```
|
|
|
|
## API
|
|
|
|
### conventionalChangelogCore([options, [context, [gitRawCommitsOpts, [parserOpts, [writerOpts]]]]])
|
|
|
|
Returns a readable stream.
|
|
|
|
*Note:* [`options.transform`](#transform-1), [`options.pkg.transform`](#transform) and [`writerOpts.transform`](https://github.com/conventional-changelog/conventional-changelog-writer#transform) are different. If you have a better naming suggestion, please send a PR.
|
|
|
|
#### options
|
|
|
|
##### config
|
|
|
|
Type: `promise`, `function` or `object`
|
|
|
|
This should serve as default values for other arguments of `conventionalChangelogCore` so you don't need to rewrite the same or similar config across your projects. Any value in this could be overwritten.
|
|
If this is a promise (recommended if async), it should resolve with the config.
|
|
If this is a function, it expects a node style callback with the config object.
|
|
If this is an object, it is the config object. The config object should include `context`, `gitRawCommitsOpts`, `parserOpts` and `writerOpts`.
|
|
|
|
##### 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.
|
|
|
|
##### skipUnstable
|
|
|
|
Type: `boolean` Default: `false`
|
|
|
|
If set, unstable release tags will be skipped, e.g., x.x.x-rc.
|
|
|
|
##### debug
|
|
|
|
Type: `function` Default: `function() {}`
|
|
|
|
A debug function. EG: `console.debug.bind(console)`
|
|
|
|
##### warn
|
|
|
|
Type: `function` Default: `options.debug`
|
|
|
|
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)
|
|
|
|
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.
|
|
|
|
##### outputUnreleased
|
|
|
|
Type: `boolean` Default: `true` if a different version than last release is given. Otherwise `false`.
|
|
|
|
If this value is `true` and `context.version` equals last release then `context.version` will be changed to `'Unreleased'`.
|
|
|
|
**NOTE:** You may want to combine this option with `releaseCount` set to `0` to always overwrite the whole CHANGELOG. `conventional-changelog` only outputs a CHANGELOG but doesn't read any existing one.
|
|
|
|
##### lernaPackage
|
|
|
|
Specify a package in lerna-style monorepo that the CHANGELOG should be generated for.
|
|
|
|
Lerna tags releases in the format `foo-package@1.0.0` and assumes that packages
|
|
are stored in the directory structure `./packages/foo-package`.
|
|
|
|
##### tagPrefix
|
|
|
|
Specify a prefix for the git tag that will be taken into account during the comparison.
|
|
For instance if your version tag is prefixed by `version/` instead of `v` you would specify `--tagPrefix=version/`
|
|
|
|
#### context
|
|
|
|
See the [conventional-changelog-writer](https://github.com/conventional-changelog/conventional-changelog/tree/master/packages/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.
|
|
|
|
##### repoUrl
|
|
|
|
Default: The whole normalized repository url in `package.json`.
|
|
|
|
##### gitSemverTags
|
|
|
|
Type: `array`
|
|
|
|
All git semver tags found in the repository. You can't overwrite this value.
|
|
|
|
##### previousTag
|
|
|
|
Type: `string` Default: previous semver tag or the first commit hash if no previous tag.
|
|
|
|
##### currentTag
|
|
|
|
Type: `string` Default: current semver 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/conventional-changelog/conventional-changelog/tree/master/packages/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: `true` if `options.append` is truthy.
|
|
|
|
##### debug
|
|
|
|
Type: `function` Default: `options.debug`
|
|
|
|
#### parserOpts
|
|
|
|
See the [conventional-commits-parser](https://github.com/conventional-changelog/conventional-commits-parser) docs.
|
|
|
|
##### warn
|
|
|
|
Default: `options.warn`
|
|
|
|
#### writerOpts
|
|
|
|
See the [conventional-changelog-writer](https://github.com/conventional-changelog/conventional-changelog/tree/master/packages/conventional-changelog-writer) docs. There are some defaults:
|
|
|
|
##### finalizeContext
|
|
|
|
Finalize context is used for generating above context.
|
|
|
|
**NOTE:** If you overwrite this value the above context defaults will be gone.
|
|
|
|
##### debug
|
|
|
|
Type: `function` Default: `options.debug`
|
|
|
|
##### reverse
|
|
|
|
Default: `options.append`
|
|
|
|
##### doFlush
|
|
|
|
Default: `options.outputUnreleased`
|
|
|
|
|
|
## Notes for parent modules
|
|
|
|
This module has options `append` and `releaseCount`. However, it doesn't read your previous changelog. Reasons being:
|
|
|
|
1. The old logs is just to be appended or prepended to the newly generated logs, which is a very simple thing that could be done in the parent module.
|
|
2. We want it to be very flexible for the parent module. You could create a readable stream from the file or you could just read the file.
|
|
3. We want the duty of this module to be very minimum.
|
|
|
|
So, when you build a parent module, you need to read the old logs and append or prepend to them based on `options.append`. However, if `options.releaseCount` is `0` you need to ignore any previous logs. Please see [conventional-github-releaser](https://github.com/conventional-changelog/conventional-github-releaser) as an example.
|
|
|
|
Arguments passed to `conventionalChangelogCore` will be mutated.
|
|
|
|
|
|
## License
|
|
|
|
MIT
|
|
|
|
|
|
[npm-image]: https://badge.fury.io/js/conventional-changelog-core.svg
|
|
[npm-url]: https://npmjs.org/package/conventional-changelog-core
|
|
[travis-image]: https://travis-ci.org/conventional-changelog/conventional-changelog-core.svg?branch=master
|
|
[travis-url]: https://travis-ci.org/conventional-changelog/conventional-changelog-core
|
|
[appveyor-image]: https://ci.appveyor.com/api/projects/status/baoumm34w8c5o0hv/branch/master?svg=true
|
|
[appveyor-url]: https://ci.appveyor.com/project/stevemao/conventional-changelog-core/branch/master
|
|
[daviddm-image]: https://david-dm.org/conventional-changelog/conventional-changelog-core.svg?theme=shields.io
|
|
[daviddm-url]: https://david-dm.org/conventional-changelog/conventional-changelog-core
|
|
[coveralls-image]: https://coveralls.io/repos/conventional-changelog/conventional-changelog-core/badge.svg
|
|
[coveralls-url]: https://coveralls.io/r/conventional-changelog/conventional-changelog-core
|