Commitlint: How to validate github issues / jira issues

[Anzumana]

Hey,
i am currently looking into how i could validate that a commit msg does include a github issue number or a jira issue number.
We currently do this with validate-commit-msg
since that package is supposed to be deprecated i was wondering how i am supposed to do something similar with commitlint.

[marionebl]

You can do this via the references-empty rule

// commitlint.config.js
module.exports = {
  'references-empty': [2, 'never']
};

This checks for the presence of any "reference", which depends on conventional-commit-parser settings. Per default this yields:

λ echo "type: subject" | commitlint
⧗   input: type: subject
✖   references may not be empty [references-empty]
✖   found 1 problems, 0 warnings

λ echo "type: subject #1" | commitlint
⧗   input: type: subject #1
✔   found 0 problems, 0 warnings

When validating JIRA ticket numbers you'll want to configure an issuePrefix:

// commitlint.config.js
module.exports = {
  parserPreset: {
    parserOpts: {
      issuePrefixes: ['PROJ-']
    }
  },
  'references-empty': [2, 'never']
};

This create the following results:

λ echo "type: subject" | commitlint
⧗   input: type: subject
✖   references may not be empty [references-empty]
✖   found 1 problems, 0 warnings

λ echo "type: subject #1" | commitlint
⧗   input: type: subject #1
✖   references may not be empty [references-empty]
✖   found 1 problems, 0 warnings

λ echo "type: subject PROJ-1" | commitlint
⧗   input: type: subject PROJ-1
✔   found 0 problems, 0 warnings

This question crops up often enough to warrant documentation.
Thinking about creating a "Common use cases" page.

[Anzumana]

does not have the desired effect in my repo at least not when i use it for the commit msg hook from husky

[marionebl]

Please provide the config you use and input examples with the expected commitlint output.

[marionebl]

@Anzumana This is not actionable for me without more information. I'll close tomorrow if there is no news on this.

[Anzumana]

my config was just
what you posted to test what you were saying.

// commitlint.config.js
module.exports = {
  parserPreset: {
    issuePrefixes: ['PROJ-']
  },
  'references-empty': [2, 'never']
};

and using this

"fix : test msg PROJ-123" 

did not result in the output you posted above.
So i am not sure whats wrong.

( Before that i tried a few more extensive configurations )
But i can;t reproduce the output you were showing above.

[marionebl]

Please post what in/output you see in your terminal session here.

[cevatkerim]

Same issue here.

echo "type: subject" | commitlint ⧗ input: type: subject ✔ found 0 problems, 0 warnings

Config:
// commitlint.config.js module.exports = { parserPreset: { issuePrefixes: ['PROJ-'] }, 'references-empty': [2, 'never'] };

[marionebl]

@cevatkerim rules definitions have to be wrapped into a rules, parserPreset must be inside parserOpts:

// commitlint.config.js
module.exports = {
  parserPreset: {
    parserOpts: {
      issuePrefixes: ['PROJ-']
    }
  },
  rules: {
    'references-empty': [2, 'never']
  }
};

echo "type: subject" | commitlint
⧗   input: type: subject
✖   references may not be empty [references-empty]
✖   found 1 problems, 0 warnings

echo "type: subject PROJ-1" | commitlint
⧗   input: type: subject PROJ-1
✔   found 0 problems, 0 warnings

[marionebl]

@Anzumana Could you try again with issuePrefixes inside parserPreset.parserOpts? My example did show a slightly wrong configuration before.

[Anzumana]

[Anzumana]

so i just passed it into vim and ran the command.
hope we can figure this out.
love the ideas presented by https://conventionalcommits.org/
getting people to care about commit msg is hard though.
and this would help tremendous.

[Anzumana]

sidenote: initially i though the best way for checking if someone used an issue prefix would be in the body of the commit msg. since commits could be related to multiple issues at the same time and then one would probably want a clean "type: subject"
and all the references to the issues somwhere in the body of the commit msg.
that way if you do

git log --oneline

the output will not be clogged with issues in the subject line that don't help you debugging.
The reason i went with trying to fit the issue prefix into the subject line was due to validate-commit-msg only allowed to validated that line as far as i know.

But thats just a personal preference and either way the solution that we can get working would be find with me.

[marionebl]

Reading your first example more closely: Have you tried renaming commitlint.config.json to commitlint.config.js? The echo show valids ECMAScript, which in this case is not valid JSON. That combination might trip the config parser up.

[Anzumana]

will try that today and then report back

[escapedcat]

I just had the same issue.
Looks like the rules object was missing in the example.

This works:

module.exports = {
  'rules': { 
    'references-empty': [2, 'never'],
  },
  parserPreset: {
    parserOpts: {
      issuePrefixes: ['PROJ-']
    }
  },
};

Example project can be found here:
https://github.com/escapedcat/commitlint-test/blob/master/commitlint.config.js

I hope this solves it for you as well.

[mebibou]

Is it also possible to configure so that this would be accepted:

PROJ-1 feat(users): add model

[escapedcat]

@Anzumana you got feedback on this? If it works for you I would close this.

@mebibou

commitlint checks if your commit messages meet the conventional commit format.

Therefor commit messages should be structured as follows:

<type>[optional scope]: <description>

[optional body]

[optional footer]

Issues numbers usually are being added to the description or to the body/footer of a message. Hope this helps.

[belamrani]

Hello, i'm looking for a solution to enable references checking only when the scope is feat or fix.
Any idea ?

[escapedcat]

@Anzumana you seem to be happy :)

@mebibou @belamrani for more options regarding parsing commit messages have a look at the conventionalCommitsParser Options

If your questions are still open feel free to ask them in the commitlint room on slack.

[Gherciu]

@Anzumana @belamrani @mebibou I created a plugin and a config special for JIRA commit messages style commitlint-jira