Docs: parserOpts and headerPattern need detailed docs

[vitonsky]

We use modified version of conventional commits standard on the project and we start use commitlint.

Today i've found problem with config of commitlint and tried to found any info about how to fix it, i've read docs site https://commitlint.js.org and i totally can't found nothing useful information. This site just list availavle option names and examples, but not explain meaning of each option.

It seems that we need to configure parserOpts object and set headerPattern regular expression to parse our commit message, but commitlint just not provide explaining what is this, how it works and how we can use it for our purposes.

We have to improve docs and add descriptions about this, otherwise this powerful tool just useless for developers, because instead of safe our time, it's just take away our time to explore source code of this tool. Right now this tool looks not reliable.

Could you please tell us how many time you need to improve docs?

[escapedcat]

If you have time to dig into this and provide a PR that would be great.
Maybe have a look into other issues related to parserOpts and headerPattern and see if you find info there.
See i.e. #607

[samayer12]

This guide is a great starting point for documentation: https://strdr4605.com/commitlint-custom-commit-message-with-emojis

[vitonsky]

@samayer12 thank you, but we decide to stop use tool that no have docs.

It sad that users a forced to write guides how to use tool to solve basic problems. If you know another tools like this, but with not so bad documentation, share with me please

[SalahAdDin]

@samayer12 thank you, but we decide to stop using tools that do not have docs.

It is sad that users a forced to write guides on how to use tools to solve basic problems. If you know another tool like this, but with not-so-bad documentation, share them with me, please.

I'm looking for an alternative too.

[synulux]

@samayer12 thank you, but we decide to stop use tool that no have docs.

It sad that users a forced to write guides how to use tool to solve basic problems. If you know another tools like this, but with not so bad documentation, share with me please

Almost one year since this issue was opened and still no documentation for parserOptions? Thought this package would help me with managing my commits, but an uncomplete documentation doesn't helps as I'd like to configure my own options...

[SpinBoxx]

Soon 2 years...

[escapedcat]

@SpinBoxx "help wanted" tag is still valid ;)

[juliaovod]

Perhaps this will help:

npm install @commitlint/types --save-dev

In the node_modules/@commitlint/types/lib/parse.d.ts file, you can find the following definition for configuring commit message parsing:

declare namespace conventionalCommitsParser {
    interface Options {
        /**
         * Used to match header pattern.
         *
         * @default
         * /^(\w*)(?:\(([\w\$\.\-\* ]*)\))?\: (.*)$/
         */
        headerPattern?: Options.Pattern | undefined;
    
        /**
         * Used to define what capturing group of `headerPattern` captures what header
         * part. The order of the array should correspond to the order of
         * `headerPattern`'s capturing group. If the part is not captured it is `null`.
         * If it's a `string` it will be converted to an `array` separated by a comma.
         *
         * @default
         * ['type', 'scope', 'subject']
         */
        headerCorrespondence?: Options.Correspondence | undefined;
    }
}

[SalahAdDin]

Perhaps this will help:

npm install @commitlint/types --save-dev

In the node_modules/@commitlint/types/lib/parse.d.ts file, you can find the following definition for configuring commit message parsing:

declare namespace conventionalCommitsParser {
    interface Options {
        /**
         * Used to match header pattern.
         *
         * @default
         * /^(\w*)(?:\(([\w\$\.\-\* ]*)\))?\: (.*)$/
         */
        headerPattern?: Options.Pattern | undefined;
    
        /**
         * Used to define what capturing group of `headerPattern` captures what header
         * part. The order of the array should correspond to the order of
         * `headerPattern`'s capturing group. If the part is not captured it is `null`.
         * If it's a `string` it will be converted to an `array` separated by a comma.
         *
         * @default
         * ['type', 'scope', 'subject']
         */
        headerCorrespondence?: Options.Correspondence | undefined;
    }
}

Does this package not have its own proper types?