Skip to content

Commit

Permalink
Format docs
Browse files Browse the repository at this point in the history
  • Loading branch information
@webpro
webpro committed Oct 29, 2024
1 parent 5e0af0c commit 73e212c
Showing 1 changed file with 76 additions and 54 deletions.
130 changes: 76 additions & 54 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@ npm install --save-dev @release-it/conventional-changelog

## Configuration

In the [release-it](https://github.com/release-it/release-it) config, for example:
In the [release-it][1] config, for example:

```json
"plugins": {
Expand All @@ -21,27 +21,25 @@ In the [release-it](https://github.com/release-it/release-it) config, for exampl
}
```

The plugin is a wrapper around conventional-changelog packages
[conventional-recommended-bump](https://github.com/conventional-changelog/conventional-changelog/tree/master/packages/conventional-recommended-bump#readme),
[conventional-changelog-core](https://github.com/conventional-changelog/conventional-changelog/tree/master/packages/conventional-changelog-core#api)
and more.
The plugin is a wrapper around conventional-changelog packages [conventional-recommended-bump][2],
[conventional-changelog-core][3] and more.

## Contents

- [`preset`](#preset)
- [`preset`][4]
- Bump
- [`commitsOpts`](#commitsopts)
- [`tagOpts`](#tagopts)
- [`whatBump`](#whatbump)
- [`ignoreRecommendedBump`](#ignorerecommendedbump)
- [`strictSemVer`](#strictsemver)
- [`commitsOpts`][5]
- [`tagOpts`][6]
- [`whatBump`][7]
- [`ignoreRecommendedBump`][8]
- [`strictSemVer`][9]
- Changelog
- [`infile`](#infile)
- [`header`](#header)
- [`context`](#context)
- [`gitRawCommitsOpts`](#gitrawcommitsopts)
- [`parserOpts`](#parseropts)
- [`writerOpts`](#writeropts)
- [`infile`][10]
- [`header`][11]
- [`context`][12]
- [`gitRawCommitsOpts`][13]
- [`parserOpts`][14]
- [`writerOpts`][15]

### `preset`

Expand Down Expand Up @@ -82,34 +80,27 @@ Use an object with `name` and `types` to use a custom preset:
}
```

This is passed as the first argument to
[`bumper.loadPreset`](https://github.com/conventional-changelog/conventional-changelog/blob/master/packages/conventional-recommended-bump/README.md#api)
(in both bumper and changelog writer).
This is passed as the first argument to [`bumper.loadPreset`][16] (in both bumper and changelog writer).

See the
[Conventional Changelog Configuration Spec (v2.1.0)](https://github.com/conventional-changelog/conventional-changelog-config-spec/blob/master/versions/2.1.0/README.md)
for the configuration object to pass as `preset`.
See the [Conventional Changelog Configuration Spec (v2.1.0)][17] for the configuration object to pass as `preset`.

## Bump

### `tagOpts`

- This option will be passed as the first argument to
[`bumper.tag`](https://github.com/conventional-changelog/conventional-changelog/blob/master/packages/conventional-recommended-bump/README.md#api)
- [Type definition for `tagOpts` → look for `GetSemverTagsParams`](https://github.com/conventional-changelog/conventional-changelog/blob/master/packages/git-client/src/types.ts)
- This option will be passed as the first argument to [`bumper.tag`][16]
- [Type definition for `tagOpts` → look for `GetSemverTagsParams`][18]

### `commitsOpts`

- This option will be passed as the first argument to
[`bumper.commits`](https://github.com/conventional-changelog/conventional-changelog/blob/master/packages/conventional-recommended-bump/README.md#api)
- [Type definition for `commitsOpts` → look for `GetCommitsParams`](https://github.com/conventional-changelog/conventional-changelog/blob/master/packages/git-client/src/types.ts)
- This option will be passed as the first argument to [`bumper.commits`][16]
- [Type definition for `commitsOpts` → look for `GetCommitsParams`][18]

### `whatBump`

- This option will be passed as the first argument to
[`bumper.bump`](https://github.com/conventional-changelog/conventional-changelog/blob/master/packages/conventional-recommended-bump/README.md#api)
- [Type definition for `whatBump` → look for `Preset['whatBump']`](https://github.com/conventional-changelog/conventional-changelog/blob/master/packages/conventional-recommended-bump/src/types.ts)
- Use the `false` Boolean value to skip releasing a new version.
- This option will be passed as the first argument to [`bumper.bump`][16]
- [Type definition for `whatBump` → look for `Preset['whatBump']`][19]
- Use `false` to skip releasing a new version:

```json
{
Expand Down Expand Up @@ -149,8 +140,8 @@ Default value: `undefined`

- Set a filename as `infile` to write the changelog to. If this file does not exist yet, it's created with the full
history.
- When `infile` is not set, the changelog generated by this plugin will still be used as release notes for e.g.
[GitHub Releases](https://github.com/release-it/release-it/blob/master/docs/github-releases.md).
- When `infile` is not set, the changelog generated by this plugin will still be used as release notes for e.g. [GitHub
Releases][20].
- Set `infile: false` to disable the changelog writing (and only use the recommended bump for the next version).

### `header`
Expand All @@ -175,9 +166,7 @@ Set the main header for the changelog document:

Default value: `undefined`

This option will be passed as the second argument (`context`) to
[conventional-changelog-core](https://github.com/conventional-changelog/conventional-changelog/tree/master/packages/conventional-changelog-core#context),
for example:
This option will be passed as the second argument (`context`) to [conventional-changelog-core][21], for example:

```json
"plugins": {
Expand All @@ -193,9 +182,8 @@ for example:

Default value: `undefined`

Options for
[`git-raw-commits`](https://github.com/conventional-changelog/conventional-changelog/tree/master/packages/git-raw-commits#api).
For example, you can use the following option to include merge commits into changelog:
Options for [`git-raw-commits`][22]. For example, you can use the following option to include merge commits into
changelog:

```json
{
Expand All @@ -212,11 +200,9 @@ For example, you can use the following option to include merge commits into chan
### `parserOpts`

- Default value: `undefined`
- Options for
[`conventional-commits-parser`](https://github.com/conventional-changelog/conventional-changelog/tree/master/packages/conventional-commits-parser#api)
- This option will also be passed as the second argument to
[`bumper.parserOptions`](https://github.com/conventional-changelog/conventional-changelog/blob/master/packages/conventional-recommended-bump/README.md#api)
- [Type definition for `parserOpts` → look for `ParserOptions`](https://github.com/conventional-changelog/conventional-changelog/blob/master/packages/conventional-commits-parser/src/types.ts)
- Options for [`conventional-commits-parser`][23]
- This option will also be passed as the second argument to [`bumper.parserOptions`][16]
- [Type definition for `parserOpts` → look for `ParserOptions`][24]

For example, you can use the following option to set the merge pattern during parsing the commit message:

Expand All @@ -235,9 +221,8 @@ For example, you can use the following option to set the merge pattern during pa
### `writerOpts`

- Default value: `undefined`
- Options for
[`conventional-changelog-writer`](https://github.com/conventional-changelog/conventional-changelog/tree/master/packages/conventional-changelog-writer#api)
- [Type definition for `writerOpts` → look for `Options`](https://github.com/conventional-changelog/conventional-changelog/blob/master/packages/conventional-changelog-writer/src/types/options.ts)
- Options for [`conventional-changelog-writer`][25]
- [Type definition for `writerOpts` → look for `Options`][26]

For example, you can use the following option to group the commits by 'scope' instead of 'type' by default.

Expand Down Expand Up @@ -289,8 +274,45 @@ Depending on your shell or OS this may differ.

## GitHub Actions

When using this plugin in a GitHub Action, make sure to set
[`fetch-depth: 0`](https://github.com/actions/checkout#fetch-all-history-for-all-tags-and-branches) so the history is
available to determine the correct recommended bump and changelog.

Also see https://github.com/release-it/release-it/blob/master/docs/ci.md#github-actions
When using this plugin in a GitHub Action, make sure to set [`fetch-depth: 0`][27] so the history is available to
determine the correct recommended bump and changelog.

Also see [https://github.com/release-it/release-it/blob/master/docs/ci.md#github-actions][28]

[1]: https://github.com/release-it/release-it
[2]:
https://github.com/conventional-changelog/conventional-changelog/tree/master/packages/conventional-recommended-bump#readme
[3]:
https://github.com/conventional-changelog/conventional-changelog/tree/master/packages/conventional-changelog-core#api
[4]: #preset
[5]: #commitsopts
[6]: #tagopts
[7]: #whatbump
[8]: #ignorerecommendedbump
[9]: #strictsemver
[10]: #infile
[11]: #header
[12]: #context
[13]: #gitrawcommitsopts
[14]: #parseropts
[15]: #writeropts
[16]:
https://github.com/conventional-changelog/conventional-changelog/blob/master/packages/conventional-recommended-bump/README.md#api
[17]: https://github.com/conventional-changelog/conventional-changelog-config-spec/blob/master/versions/2.1.0/README.md
[18]: https://github.com/conventional-changelog/conventional-changelog/blob/master/packages/git-client/src/types.ts
[19]:
https://github.com/conventional-changelog/conventional-changelog/blob/master/packages/conventional-recommended-bump/src/types.ts
[20]: https://github.com/release-it/release-it/blob/master/docs/github-releases.md
[21]:
https://github.com/conventional-changelog/conventional-changelog/tree/master/packages/conventional-changelog-core#context
[22]: https://github.com/conventional-changelog/conventional-changelog/tree/master/packages/git-raw-commits#api
[23]:
https://github.com/conventional-changelog/conventional-changelog/tree/master/packages/conventional-commits-parser#api
[24]:
https://github.com/conventional-changelog/conventional-changelog/blob/master/packages/conventional-commits-parser/src/types.ts
[25]:
https://github.com/conventional-changelog/conventional-changelog/tree/master/packages/conventional-changelog-writer#api
[26]:
https://github.com/conventional-changelog/conventional-changelog/blob/master/packages/conventional-changelog-writer/src/types/options.ts
[27]: https://github.com/actions/checkout#fetch-all-history-for-all-tags-and-branches
[28]: https://github.com/release-it/release-it/blob/master/docs/ci.md#github-actions

0 comments on commit 73e212c

Please sign in to comment.