“Hey, which Jira task is this commit related to?”
That question started popping up more and more in our team. And that’s when we realized: it was time to standardize our commit messages.
The challenge: connecting code to context
In our team, every Jira task has a unique identifier like TWSF-1234. But not everyone remembered to include it in their commits. The result? It was hard to track what was being delivered and why.
That’s when we decided to use Commitlint to enforce that every commit includes the task ID in the scope field. And more than that - we created a custom rule to make it happen.
What is Commitlint?
Commitlint is a tool that checks your commit messages against a set of rules. It helps keep your Git history clean, consistent, and easy to understand.
You can use predefined rules (like @commitlint/config-conventional) or create your own. We went with both.
Creating a custom rule
Here’s our commitlint.config.js file:
module.exports = {
extends: ['@commitlint/config-conventional'],
rules: {
'twsf-task-scope': [2, 'always'],
},
plugins: [
{
rules: {
'twsf-task-scope': ({ scope }) => {
const regex = /^TWSF-\d+$/;
const isValid = regex.test(scope);
return [
isValid,
'Scope must follow the pattern TWSF-<task-number>, e.g., TWSF-1234',
];
},
},
},
],
};
What does this config do?
- Extends the conventional commit rules.
-
Adds a custom rule called
twsf-task-scope. - This rule checks if the scope in the commit message matches the pattern TWSF-.
✅ Valid commit example:
feat(TWSF-1234): add export report button
❌ Invalid commit example:
fix(report): fix export bug
This second commit would be rejected with the message:
Scope must follow the pattern TWSF-, e.g., TWSF-1234
How to apply this to your project
1 - Install Commitlint and the required packages:
npm install --save-dev @commitlint/{cli,config-conventional}
2 - Create the commitlint.config.js file with the configuration above.
3 - Integrate it with Git using a commit hook (via Husky):
- Create the hook file directly:
Inside the .husky folder, create a new file with the name of the hook you need. For Commitlint, the file should be named commit-msg.
# Use the 'touch' command on Unix/Linux systems or 'New-Item' in PowerShell (Windows)
touch .husky/commit-msg
- Add the validation script to the file:
Open the .husky/commit-msg file with a text editor and add the command that will run Commitlint. The standard command is npx --no-install commitlint --edit ${1}.
#!/usr/bin/env sh
npx --no-install commitlint --edit "$1"
The result: better traceability, less confusion
After applying this rule, our commits became much more organized. Every delivery is clearly linked to a Jira task, making reviews, deployments, and even audits easier.
If you’re looking to bring more clarity to your project, creating custom rules with Commitlint is a great move. It’s simple, effective, and keeps your team aligned.
Did this help? Let me know in the comments how your team handles commit message standards!
Top comments (1)
Muito útil