docs: improve parserPreset documentation with examples and options reference by Chessing234 · Pull Request #4700 · conventional-changelog/commitlint

Chessing234 · 2026-04-04T09:32:04Z

Summary

Expanded the "Parser presets" section in docs/reference/configuration.md to explain:
- Which default preset commitlint uses (conventional-changelog-conventionalcommits)
- The three ways to configure parserPreset (npm package, local file, inline parserOpts)
- A table of the most common parserOpts options
- Links to the conventional-changelog-config-spec and conventional-commits-parser
Added a brief explanation to the "Validate for issue/ticket numbers" example in docs/reference/examples.md clarifying what the inline parserOpts does, with a cross-link to the configuration docs

Motivation

The existing parser preset docs were minimal — two examples with no explanation of what parserPreset is, which default is used, or what options are available. Users had to dig through source code to understand configuration.

Test plan

Passed lint-staged and prettier formatting checks
Verified markdown renders correctly

Closes #4532

🤖 Generated with Claude Code

…ons reference Expanded the "Parser presets" section in the configuration docs to clarify which default preset is used, explain the three ways to configure parserPreset (npm package, local file, inline parserOpts), and document the most common parserOpts with links to the conventional-changelog-config-spec. Also added context to the examples page explaining how parserOpts works. Closes #4532 Co-Authored-By: Claude Opus 4.6 (1M context) <[email protected]>

qodo-code-review · 2026-04-04T09:32:17Z

Review Summary by Qodo

Improve parserPreset documentation with examples and options reference

📝 Documentation

Walkthroughs

Description

• Expanded parser preset documentation with default preset clarification
• Added three configuration methods: npm package, local file, inline parserOpts
• Included table of common parserOpts with links to specifications
• Added context to examples page with cross-reference to configuration docs

Diagram

flowchart LR
  A["Parser Preset Docs"] --> B["Default Preset Info"]
  A --> C["Three Config Methods"]
  A --> D["parserOpts Table"]
  C --> E["NPM Package"]
  C --> F["Local File"]
  C --> G["Inline Config"]
  D --> H["Links to Specs"]
  I["Examples Page"] --> J["Issue Validation Example"]
  J --> K["Cross-link to Config Docs"]

File Changes

1. docs/reference/configuration.md 📝 Documentation +41/-6

Expand parser preset documentation with options reference

• Replaced minimal parser preset explanation with comprehensive documentation
• Added default preset information (conventional-changelog-conventionalcommits)
• Documented three configuration approaches with separate subsections
• Added table of common parserOpts options with descriptions
• Included links to conventional-changelog-config-spec and conventional-commits-parser

docs/reference/configuration.md

2. docs/reference/examples.md 📝 Documentation +4/-0

Add context to issue validation example

• Added explanatory text for the issue/ticket validation example
• Clarified how inline parserOpts enables custom issue prefix recognition
• Added cross-reference link to parser presets configuration section

docs/reference/examples.md

qodo-code-review · 2026-04-04T09:32:18Z

Code Review by Qodo

🐞 Bugs (1) 📘 Rule violations (0) 📎 Requirement gaps (1) 🎨 UX Issues (0)

1. Examples omit parserPreset name 📎 Requirement gap ≡ Correctness

Description

The updated issue/ticket example explains inline parserOpts but still does not explicitly name
which parserPreset (e.g. conventional-changelog-conventionalcommits) the example assumes. This
leaves users guessing which preset package/name to configure for consistent parsing behavior.

Code

docs/reference/examples.md[R7-8]

+This example uses inline `parserOpts` to configure the parser to recognize custom issue prefixes (e.g. `PROJ-123`). The `references-empty` rule then enforces that every commit references a ticket.
+

Evidence
PR Compliance ID 1 requires the examples documentation to explicitly name the parserPreset to use;
the newly added explanatory text for the example discusses parserOpts but does not name any
parserPreset package/name.
Documentation clarifies the correct parserPreset name used in examples
docs/reference/examples.md[7-8]
docs/reference/examples.md[30-30]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
The examples page addition explains inline `parserOpts` but does not explicitly state which `parserPreset` users should configure for the example.
## Issue Context
Compliance requires examples docs to name the preset (e.g. `conventional-changelog-conventionalcommits`) and show how to reference it.
## Fix Focus Areas
- docs/reference/examples.md[7-8]
- docs/reference/examples.md[30-30]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

2. presetConfig not documented ☑ 📎 Requirement gap ⚙ Maintainability

Description

The expanded configuration documentation explains parserPreset and inline parserOpts but does
not explain presetConfig or show a configuration example using it. This fails to provide complete
guidance on the related parser/preset configuration options.

Code

docs/reference/configuration.md[R195-202]

+The parser preset controls how commit messages are parsed into their component parts (type, scope, subject, body, footer, etc.). By default, commitlint uses the [`conventional-changelog-conventionalcommits`](https://github.com/conventional-changelog/conventional-changelog/tree/master/packages/conventional-changelog-conventionalcommits) preset, which follows the [Conventional Commits specification](https://www.conventionalcommits.org/).
-This means installed npm packages and local files can be used.
+You can override the parser preset using the `parserPreset` property. It accepts:
-:::tabs
-== npm
+- A **string** referencing an npm package or local file (resolved via Node's module resolution)
+- An **object** with a `parserOpts` property for inline configuration
+
+### Using an npm package

Evidence
PR Compliance ID 2 requires documentation covering parserPreset, parserOpts, and presetConfig
with at least one concrete example; the updated section describes parserPreset and parserOpts
only and provides no presetConfig explanation or example.
Documentation explains how to configure parserPreset, parserOpts, and presetConfig
docs/reference/configuration.md[195-202]
docs/reference/configuration.md[239-255]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
The `Parser presets` documentation does not explain `presetConfig` or demonstrate how to configure it.
## Issue Context
Compliance requires covering `parserPreset`, `parserOpts`, and `presetConfig` and including at least one concrete example.
## Fix Focus Areas
- docs/reference/configuration.md[195-202]
- docs/reference/configuration.md[239-255]
- docs/reference/configuration.md[257-270]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

3. ~~Missing semantic-release parserOpts context~~ ☑ 📎 Requirement gap ≡ Correctness

Description

The docs mention the default preset and list common parserOpts, but they do not add
semantic-release-specific context for how parserOpts and presetConfig relate to the
conventional-changelog-conventionalcommits preset. This leaves users without practical guidance to
keep commitlint and semantic-release behavior consistent.

Code

docs/reference/configuration.md[195]

+The parser preset controls how commit messages are parsed into their component parts (type, scope, subject, body, footer, etc.). By default, commitlint uses the [`conventional-changelog-conventionalcommits`](https://github.com/conventional-changelog/conventional-changelog/tree/master/packages/conventional-changelog-conventionalcommits) preset, which follows the [Conventional Commits specification](https://www.conventionalcommits.org/).

Evidence
PR Compliance ID 5 requires a brief semantic-release-specific explanation (and/or links like
semantic-release/commit-analyzer) describing how semantic-release uses/derives parserOpts and
presetConfig for conventional-changelog-conventionalcommits; the updated preset intro provides
no semantic-release context or related links.
Documentation includes semantic-release context for conventional-changelog-conventionalcommits parserOpts and presetConfig
docs/reference/configuration.md[195-195]
docs/reference/configuration.md[257-270]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
The parser preset documentation lacks semantic-release-specific context for `parserOpts`/`presetConfig` when using `conventional-changelog-conventionalcommits`.
## Issue Context
Compliance requires brief clarification and/or links (e.g. to `semantic-release/commit-analyzer`) explaining how semantic-release uses/derives these options so users can configure consistently.
## Fix Focus Areas
- docs/reference/configuration.md[195-195]
- docs/reference/configuration.md[257-270]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

View more (1)

4. ~~Wrong default preset stated~~ ☑ 🐞 Bug ≡ Correctness

Description

The docs state that commitlint defaults to conventional-changelog-conventionalcommits, but the
codebase shows commitlint has no default parserPreset unless configured (and parsing falls back to
conventional-changelog-angular defaults). This will mislead users about what commitlint uses when
they haven’t explicitly set/extended a config that provides parserPreset.

Code

docs/reference/configuration.md[195]

+The parser preset controls how commit messages are parsed into their component parts (type, scope, subject, body, footer, etc.). By default, commitlint uses the [`conventional-changelog-conventionalcommits`](https://github.com/conventional-changelog/conventional-changelog/tree/master/packages/conventional-changelog-conventionalcommits) preset, which follows the [Conventional Commits specification](https://www.conventionalcommits.org/).

Evidence

The new documentation claims a global default preset, but commitlint’s loader does not set a default
parserPreset (it’s only resolved when the user config provides it), and @commitlint/parse uses
conventional-changelog-angular to obtain its default parser options. Additionally, CLI tests
demonstrate parserPreset: undefined in the printed config for the default fixture, while
@commitlint/config-conventional explicitly sets parserPreset to conventionalcommits (showing
it’s a config default, not commitlint’s unconditional default).

docs/reference/configuration.md[193-200]
@commitlint/load/src/load.ts[54-76]
@commitlint/parse/src/index.ts[8-35]
@commitlint/cli/src/cli.test.ts[672-706]
@commitlint/config-conventional/src/index.ts[7-10]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
`docs/reference/configuration.md` claims commitlint uses `conventional-changelog-conventionalcommits` “by default”, but commitlint’s loader/CLI show no default `parserPreset` is set unless configured, and parsing falls back to `conventional-changelog-angular` defaults.
## Issue Context
- `@commitlint/load` only resolves `parserPreset` when it’s provided in user config.
- `@commitlint/parse` builds default parser options from `conventional-changelog-angular`.
- `@commitlint/config-conventional` sets `parserPreset` to `conventional-changelog-conventionalcommits`, which is a *specific config’s* default, not an unconditional commitlint default.
## Fix Focus Areas
- docs/reference/configuration.md[193-201]
- @commitlint/load/src/load.ts[54-83]
- @commitlint/parse/src/index.ts[8-35]
- @commitlint/config-conventional/src/index.ts[7-10]
## Suggested doc change (direction)
- Rephrase the “By default…” sentence to something explicitly accurate, e.g.:
- “If you extend `@commitlint/config-conventional` (recommended), commitlint uses `conventional-changelog-conventionalcommits`.”
- Optionally add: “Without a configured `parserPreset`, commitlint falls back to its internal parser defaults.”

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

5. Misplaced module-resolution sentence 🐞 Bug ⚙ Maintainability

Description

The sentence “Use ids resolvable by the node resolve algorithm.” appears under the Formatter
section, where it’s unrelated and confusing. This reads like leftover text from the Parser presets
section and should be removed or moved back to the appropriate section.

Code

docs/reference/configuration.md[R273-274]
Commitlint can output the issues encountered in different formats, if necessary.

Evidence

In the current doc, the Formatter section includes an extra sentence about Node resolution that
doesn’t apply to formatter configuration and contradicts the surrounding formatter text.

docs/reference/configuration.md[271-275]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
A sentence about Node module resolution is currently placed under the `## Formatter` section, where it is unrelated.
## Issue Context
The line likely belonged to the `parserPreset` description (module resolution) but is now shown beneath formatter docs.
## Fix Focus Areas
- docs/reference/configuration.md[271-275]
## Suggested fix
- Delete the line `Use ids resolvable by the node resolve algorithm.` from the Formatter section (or move it back under Parser presets if still needed).

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

ⓘ The new review experience is currently in Beta. Learn more

qodo-code-review · 2026-04-04T09:35:04Z

+This example uses inline `parserOpts` to configure the parser to recognize custom issue prefixes (e.g. `PROJ-123`). The `references-empty` rule then enforces that every commit references a ticket.
+


1. Examples omit parserpreset name 📎 Requirement gap ≡ Correctness

The updated issue/ticket example explains inline parserOpts but still does not explicitly name which parserPreset (e.g. conventional-changelog-conventionalcommits) the example assumes. This leaves users guessing which preset package/name to configure for consistent parsing behavior.

Agent Prompt

## Issue description The examples page addition explains inline `parserOpts` but does not explicitly state which `parserPreset` users should configure for the example. ## Issue Context Compliance requires examples docs to name the preset (e.g. `conventional-changelog-conventionalcommits`) and show how to reference it. ## Fix Focus Areas - docs/reference/examples.md[7-8] - docs/reference/examples.md[30-30]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

Copilot

Pull request overview

Improves commitlint documentation around parserPreset/parserOpts to address confusion raised in #4532 by explaining what parser presets are, how to configure them, and where to find relevant option references.

Changes:

Expanded Parser presets documentation with default/purpose explanation and configuration methods (npm package, local file, inline parserOpts).
Added a quick-reference table of common parserOpts and links to upstream specs/projects.
Clarified the “Validate for issue/ticket numbers” example and cross-linked it to the configuration docs.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 2 comments.

File	Description
docs/reference/examples.md	Adds explanation of inline `parserOpts` usage and links readers to parser preset docs.
docs/reference/configuration.md	Expands parser preset section with configuration patterns and an options reference table.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

escapedcat · 2026-04-04T09:52:44Z

Please check if the AI feedback is valid and tackle it if needed

Chessing234 · 2026-04-06T08:34:13Z

@escapedcat Thanks for the review! I've looked through the automated feedback and the key issues are valid:

Wrong default preset — The docs incorrectly state commitlint defaults to conventional-changelog-conventionalcommits. In reality, @commitlint/parse falls back to conventional-changelog-angular defaults when no parserPreset is configured. The conventionalcommits preset is set by @commitlint/config-conventional, not commitlint itself. I'll fix this to clarify the distinction.
Missing presetConfig documentation — I'll add a section covering presetConfig with an example.
Misplaced module-resolution sentence — The "Use ids resolvable by the node resolve algorithm" line ended up under Formatter. I'll remove it from there.
Link text wording — I'll change "full list of available parserOpts" to "common parserOpts" since the docs only cover common options, not an exhaustive list.

I'll push the fixes shortly!

- Fix incorrect default preset claim (angular, not conventionalcommits) - Clarify link text for parserOpts reference - Add presetConfig documentation - Add semantic-release context Signed-off-by: Chessing234 <[email protected]> Co-Authored-By: Claude Opus 4.6 (1M context) <[email protected]>

escapedcat · 2026-04-07T02:57:08Z

Thanks!

qodo-code-review Bot reviewed Apr 4, 2026

View reviewed changes

escapedcat requested a review from Copilot April 4, 2026 09:48

Copilot started reviewing on behalf of escapedcat April 4, 2026 09:48 View session

Copilot AI reviewed Apr 4, 2026

View reviewed changes

Comment thread docs/reference/configuration.md Outdated

Comment thread docs/reference/examples.md Outdated

escapedcat merged commit 8383f1d into conventional-changelog:master Apr 7, 2026
15 checks passed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs: improve parserPreset documentation with examples and options reference#4700

docs: improve parserPreset documentation with examples and options reference#4700
escapedcat merged 2 commits intoconventional-changelog:masterfrom
Chessing234:fix/issue-4532

Chessing234 commented Apr 4, 2026

Uh oh!

qodo-code-review Bot commented Apr 4, 2026

Uh oh!

qodo-code-review Bot commented Apr 4, 2026 •

edited

Loading

Uh oh!

qodo-code-review Bot Apr 4, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

escapedcat commented Apr 4, 2026

Uh oh!

Chessing234 commented Apr 6, 2026

Uh oh!

Uh oh!

escapedcat commented Apr 7, 2026

Uh oh!

Reviewers

Assignees

Labels

Milestone

Development

Uh oh!

3 participants

		This example uses inline `parserOpts` to configure the parser to recognize custom issue prefixes (e.g. `PROJ-123`). The `references-empty` rule then enforces that every commit references a ticket.

Conversation

Chessing234 commented Apr 4, 2026

Summary

Motivation

Test plan

Uh oh!

qodo-code-review Bot commented Apr 4, 2026

Review Summary by Qodo

Walkthroughs

File Changes

Uh oh!

qodo-code-review Bot commented Apr 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Code Review by Qodo

Uh oh!

qodo-code-review Bot Apr 4, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

escapedcat commented Apr 4, 2026

Uh oh!

Chessing234 commented Apr 6, 2026

Uh oh!

Uh oh!

escapedcat commented Apr 7, 2026

Uh oh!

Reviewers

Assignees

Labels

Milestone

Development

Uh oh!

3 participants

qodo-code-review Bot commented Apr 4, 2026 •

edited

Loading