DEV Community

Werliton Silva
Werliton Silva

Posted on

How We Solved Commit Chaos with a Custom Commitlint Rule

#webdev #programming #beginners #productivity

The Problem: Everyone Commits Differently

You know that moment when you're reviewing code and think,
"Wait… what Jira task is this commit even related to?"

Yeah, we lived that.

In our team, each Jira task had a clear ID like TWSF-1234, but our commit messages? A wild mix. Some had the task ID, some didn’t. Some were super descriptive, others… not so much.

We knew we needed to fix this. Not just for ourselves, but for future us - the ones debugging, deploying, or trying to understand what happened two sprints ago.

💡 The Idea: Let’s Automate the Standard

We didn’t want to rely on memory or discipline alone. We wanted a system that would guide developers to write consistent, traceable commit messages - without being annoying.

That’s when we found **Commitlint**.

Commitlint checks your commit messages and makes sure they follow a set of rules. You can use standard rules, or - and this is where it gets fun - you can write your own.

🛠️ Our Custom Rule: Enforcing Jira Task IDs

We created a rule that checks if the scope of the commit message matches our Jira task format: TWSF-<number>. If it doesn’t, the commit is rejected with a friendly message.

Here’s what our config looks like:

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',
                    ];
                },
            },
        },
    ],
};
Enter fullscreen mode Exit fullscreen mode

✅ Valid commit: 

feat(TWSF-1234): add export button to report
Enter fullscreen mode Exit fullscreen mode

❌ Invalid commit: 

fix(report): fix export bug
Enter fullscreen mode Exit fullscreen mode

The second one gets blocked with a clear message telling the dev what to fix.

📦 Sharing the Rule Across Projects

We didn’t stop there. To make this reusable across all our projects, we packaged the rule into a private npm library. Now, any team in the company can install it and instantly get the same commit standards.

Here’s how we did it:

  • Created a new npm package with the config.
  • Published it privately using our company scope.
  • In each project, we just install and extend it: 
npm install --save-dev @ourcompany/commitlint-config-twsf
Enter fullscreen mode Exit fullscreen mode

And in commitlint.config.js:

module.exports = require('@ourcompany/commitlint-config-twsf');
Enter fullscreen mode Exit fullscreen mode

🎯 The Result: Clean, Consistent, Traceable Commits

Now every commit tells a story. It’s linked to a Jira task, easy to understand, and consistent across the board. No more guessing, no more digging.

If your team struggles with messy commit messages, I highly recommend trying this out. It’s simple, effective, and makes a real difference in day-to-day development.

Want help setting it up? Drop a comment or message me — happy to share what worked for us.

Top comments (0)