Ultimate Guide to Writing Commit Messages for Commitlint Workflow

This guide provides detailed instructions and best practices for crafting commit messages when using Commitlint, ensuring consistency, clarity, and traceability in your codebase. Following this format not only improves collaboration but also integrates seamlessly with tools like Jira.

Commit Message Structure

Commitlint enforces a specific structure for commit messages. The standard format is:

type(scope?): subject

1. Type

The type defines the purpose of the commit. Use one of the following conventional types:

2. Scope (Optional)

The scope specifies the section of the codebase affected by the commit. Examples:

• lambda

• s3

• api

• ui

If multiple scopes are affected, separate them with delimiters like /, \, or ,.

3. Subject

The subject is a brief summary of the change, written in imperative tone and without a period. It should be concise and descriptive.

Imperative Tone

An imperative tone describes what the commit does rather than what it did or will do. Imagine completing the sentence: "If applied, this commit will..."

• Good Examples:

  • Add S3 bucket creation functionality

  • Fix Lambda trigger configuration

  • Refactor presigned URL generator

  • Update README with setup instructions

• Bad Examples:

  • Added S3 bucket creation functionality (past tense)

  • Adding Lambda trigger configuration (progressive tense)

  • Fixes Lambda trigger configuration. (ends with a period)

---

Examples of Commit Messages

Simple Examples

• feat(s3): Add S3 bucket creation functionality

• fix(lambda): Resolve Lambda trigger configuration issue

• docs: Update README with API setup instructions

• chore: Update dependencies for Node.js

Advanced Example with Jira Issue Key

To integrate with Jira, include the issue key in the subject or body of the commit message:

• Subject Example:

  • feat(lambda): PROJECTISSUE-123 Add Lambda trigger for S3 bucket

• Body Example:

  •   feat(lambda): Add Lambda trigger for S3 bucket
    
      This commit addresses Jira issue PROJECTISSUE-123. It configures the Lambda function to trigger automatically when a file is uploaded to the S3 bucket.
    

---

Steps for Using Commitlint with VS Code

1. Install Commitlint Ensure Commitlint is installed and properly configured in your repository. Typically, this is done via:

    npm install --save-dev @commitlint/{config-conventional,cli}
   

2. Set Up Commitlint Configuration Add a commitlint.config.js file in the root of your repository:

    module.exports = { extends: ['@commitlint/config-conventional'] };
   

3. Write a Commit Message in VS Code When creating a commit, follow this structure:

    git commit -m "type(scope): subject"
   

4. Include Jira Issue Key (Optional) If required, prepend or append the Jira issue key in the subject or body. Example:

    git commit -m "feat(lambda): PROJECTISSUE-123 Add Lambda trigger for S3 bucket"
   

5. Push Your Commit Push your branch as usual:

    git push origin <branch-name>
   

6. Validate Commits Automatically If Commitlint is integrated with your CI/CD pipeline or pre-commit hooks, invalid commit messages will be flagged.

---

Checklist for Crafting Commit Messages

1. Use a valid type (feat, fix, etc.).

2. Include a relevant scope (if applicable).

3. Write a clear, concise subject in imperative tone.

4. Avoid ending the subject with a period.

5. Optionally include a Jira issue key for better traceability.

6. Provide additional context in the body if needed.

By following this guide, you ensure that your commit history remains clear, meaningful, and professional.