Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

docs(core): Make README.md is more readable #783

Open
wants to merge 2 commits into
base: master
Choose a base branch
from
Open

docs(core): Make README.md is more readable #783

Changes from 1 commit
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
a8fad27
docs(core): Make README.md is more readable
cawa-93 Mar 28, 2021
a55906a
Merge branch 'master' into patch-2
cawa-93 Jul 20, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
247 changes: 124 additions & 123 deletions packages/conventional-changelog-core/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -19,210 +19,211 @@ conventionalChangelogCore()

## API

### conventionalChangelogCore([options, [context, [gitRawCommitsOpts, [parserOpts, [writerOpts]]]]])

```js
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
### options

Type: `function` Default: pass through.
- #### config

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.
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`.

##### append
- #### pkg

Type: `boolean` Default: `false`
Type: `object`

Should the log be appended to existing data.
- ##### path

##### releaseCount
Type: `string` Default: [closest package.json](https://github.com/sindresorhus/read-pkg-up).

The location of your "package.json".

Type: `number` Default: `1`
- ##### transform

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.
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.

##### skipUnstable
- #### append

Type: `boolean` Default: `false`
Type: `boolean` Default: `false`

Should the log be appended to existing data.

If set, unstable release tags will be skipped, e.g., x.x.x-rc.
- #### releaseCount

##### debug
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.

Type: `function` Default: `function() {}`
- #### skipUnstable

A debug function. EG: `console.debug.bind(console)`
Type: `boolean` Default: `false`

If set, unstable release tags will be skipped, e.g., x.x.x-rc.

##### warn
- #### debug

Type: `function` Default: `options.debug`
Type: `function` Default: `function() {}`

A debug function. EG: `console.debug.bind(console)`

A warn function. EG: `grunt.verbose.writeln`
- #### warn

##### transform
Type: `function` Default: `options.debug`

A warn function. EG: `grunt.verbose.writeln`

Type: `function` Default: get the version (without leading 'v') from tag and format date.
- #### transform

###### function(commit, cb)
Type: `function` Default: get the version (without leading 'v') from tag and format date.

A transform function that applies after the parser and before the writer.
- ##### function(commit, cb)

This is the place to modify the parsed commits.
A transform function that applies after the parser and before the writer.

This is the place to modify the parsed commits.

####### commit
- commit

The commit from conventional-commits-parser.

- cb

Callback when you are done.

- this

`this` arg of through2.

The commit from conventional-commits-parser.
- #### outputUnreleased

####### cb
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.

Callback when you are done.
- #### lernaPackage

####### this
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`.

`this` arg of through2.
- #### tagPrefix

##### outputUnreleased
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/`

Type: `boolean` Default: `true` if a different version than last release is given. Otherwise `false`.
### context

If this value is `true` and `context.version` equals last release then `context.version` will be changed to `'Unreleased'`.
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:

**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.
- #### host

##### lernaPackage
Default: normalized host found in `package.json`.

Specify a package in lerna-style monorepo that the CHANGELOG should be generated for.
- #### version

Lerna tags releases in the format `foo-package@1.0.0` and assumes that packages
are stored in the directory structure `./packages/foo-package`.
Default: version found in `package.json`.

##### tagPrefix
- #### owner

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/`
Default: extracted from normalized `package.json` `repository.url` field.

#### context
- #### repository

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:
Default: extracted from normalized `package.json` `repository.url` field.

##### host
- #### repoUrl

Default: normalized host found in `package.json`.
Default: The whole normalized repository url in `package.json`.

##### version
- #### gitSemverTags

Default: version found in `package.json`.
Type: `array`

All git semver tags found in the repository. You can't overwrite this value.

##### owner
- #### previousTag

Default: extracted from normalized `package.json` `repository.url` field.
Type: `string` Default: previous semver tag or the first commit hash if no previous tag.

##### repository
- #### currentTag

Default: extracted from normalized `package.json` `repository.url` field.
Type: `string` Default: current semver tag or `'v'` + version if no current tag.

##### repoUrl
- #### packageData

Default: The whole normalized repository url in `package.json`.
Type: `object`

Your `package.json` data. You can't overwrite this value.

##### gitSemverTags
- #### linkCompare

Type: `array`
Type: `boolean` Default: `true` if `previousTag` and `currentTag` are truthy.

Should link to the page that compares current tag with previous tag?

All git semver tags found in the repository. You can't overwrite this value.
### gitRawCommitsOpts

##### previousTag
See the [git-raw-commits](https://github.com/conventional-changelog/conventional-changelog/tree/master/packages/git-raw-commits) docs. There are some defaults:

Type: `string` Default: previous semver tag or the first commit hash if no previous tag.
- #### format

##### currentTag
Default: `'%B%n-hash-%n%H%n-gitTags-%n%d%n-committerDate-%n%ci'`

Type: `string` Default: current semver tag or `'v'` + version if no current tag.
- #### from

##### packageData
Default: based on `options.releaseCount`.

Type: `object`
- #### reverse

Your `package.json` data. You can't overwrite this value.
Default: `true` if `options.append` is truthy.

##### linkCompare
- #### debug

Type: `boolean` Default: `true` if `previousTag` and `currentTag` are truthy.
Type: `function` Default: `options.debug`

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
### parserOpts

See the [conventional-commits-parser](https://github.com/conventional-changelog/conventional-commits-parser) docs.

##### warn
- #### warn

Default: `options.warn`
Default: `options.warn`

#### writerOpts
### 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.
- #### finalizeContext

**NOTE:** If you overwrite this value the above context defaults will be gone.
Finalize context is used for generating above context.

**NOTE:** If you overwrite this value the above context defaults will be gone.

##### debug
- #### debug

Type: `function` Default: `options.debug`
Type: `function` Default: `options.debug`

##### reverse
- #### reverse

Default: `options.append`
Default: `options.append`

##### doFlush
- #### doFlush

Default: `options.outputUnreleased`
Default: `options.outputUnreleased`


## Notes for parent modules
Expand Down