The perks of committing with conventions

Mario

• Free Radical
• Principal Product Engineer
• @SinnerSchrader

• 👨‍💻 🏄

This talk

• Issues with commit -m
• The conventional commit format
• Use commit messages for project automation
• Stay consistent with commitlint

git commit basically is 

<textarea required>

git commit -m "fix"

git commit -m "updated"

git commit -m "clean up"

Snark 

Missing information

Placeholder messages

Consistent, sensible commit messages are hard

commit -m free form does not help too much

conventional commit format

type(scope?): subject

chore: run tests on travis ci

fix(server): send cors headers

chore: run tests on travis ci

fix(server): send cors headers

type(scope?): subject

• Describes the category of your change
• Commonly used: build, chore, ci, docs, feat, fix, perf, refactor, revert, style, test

type(scope?): subject

chore: run tests on travis ci

fix(server): send cors headers

type(scope?): subject

type(scope?): subject

• Describes the module affected by your change
• Highly project specific
• e.g. changed package in Mono-Repo, component in component library, etc.

chore: run tests on travis ci

fix(server): send cors headers

type(scope?): subject

type(scope?): subject

• Terse description
• Avoid repeating information from type and scope
• Describe what the software does after your change 

Conventional commit format

• What type of changes am I committing?
• What scope is affected by my changes?
• subject: When applied, the software will ...

Conventional commit format

• High quality commit messages
• Ensure critical information included
• Add Context to Pull Requests
• Smaller commits via type and scope boundaries
• Format easily parsed by tooling

Tooling

Automatic changelogs

• conventional-changelog
• lerna
• git-changelog
• lerna-changelog
• generate-changelog
• standard-changelog

Automatic releases

• lerna
• standard-version
• semantic-release
• conventional-github-releaser
• conventional-recommended-bump

Automatic releases

BREAKING CHANGE        Major release

feat:                                   Minor release               

fix:                                      Patch Release

other                                 Patch/No Release

Keeping consistency

• commitlint
• 32 configurable rules
• lint single commits or ranges
• friendly error messages

• github.com/marionebl/commitlint

Use case: define allowed scopes

// commitlint.config.js

module.exports = {
  extends: ['angular'],
  rules: {
    'scope-enum': [
        2, 
        'always', 
        ['server', 'client']
    ]
  }
};

Use case: define allowed scopes

echo "fix: send cors headers" | npx commitlint
✔   found 0 problems, 0 warnings

echo "fix(server): send cors headers" | npx commitlint
✔   found 0 problems, 0 warnings

echo "fix(foo): some message" | npx commitlint
✖   scope must be one of [server, client] [scope-enum]
✖   found 1 problems, 0 warnings

Wrap up

• Author consistent, complete commit messages
• Keep changes small by fitting them into a schema
• Help coworkers understand your changes better
• Power automation with commit messages 
• Use ready-made tooling for changelogs, releases, commit prompts, linters

Thanks!

marionebl

marionebl