Skip to content

Latest commit

 

History

History
120 lines (70 loc) · 4.16 KB

COMMIT_MESSAGES.md

File metadata and controls

120 lines (70 loc) · 4.16 KB
Raw

Commit Message Conventions

This page defines a convention for commit messages for pyannote related projects.

All commits pushed to the pyannote repositories must conform to that convention.

The contens of this page are partly based on the angular commit messages document.

Purpose

The commit message is what is what describes your contribution. Its purpose must therefore be to document what a commit contributes to a project.

Its head line should be as meaningful as possible because it is always seen along with other commit messages.

Its body should provide information to comprehend the commit for people who care.

Its footer may contain references to external artifacts (issues it solves, related commits) as well as breaking change notes.

This applies to all kind of projects.

Format

Short form (only subject line)

<type>(<scope>): <subject>

Long form (with body)

<type>(<scope>): <subject>

<BLANK LINE>

<body>

<BLANK LINE>

<footer>

First line cannot be longer than 70 characters, second line is always blank and other lines should be wrapped at 80 characters! This makes the message easier to read on github as well as in various git tools.

Subject Line

The subject line contains succinct description of the change.

Allowed

  • feat (feature)
  • fix (bug fix)
  • docs (documentation)
  • style (formatting, missing semi colons, �)
  • refactor
  • test (when adding missing tests)
  • chore (maintain)
  • improve (improvement, e.g. enhanced feature)

Allowed

Scope could be anything specifying place of the commit change.

text

  • use imperative, present tense: change not changed nor changes or changing
  • do not capitalize first letter
  • do not append dot (.) at the end

Message Body

  • just as in use imperative, present tense: change not changed nor changes or changing
  • include motivation for the change and contrast it with previous behavior

Message Footer

Breaking changes

All breaking changes have to be mentioned in footer with the description of the change, justification and migration notes

BREAKING CHANGE: Id editing feature temporarily removed

    As a work around, change the id in XML using replace all or friends

Referencing issues

Closed bugs / feature requests / issues should be listed on a separate line in the footer prefixed with "Closes" keyword like this:

Closes #234

or in case of multiple issues:

Closes #123, #245, #992

More on good commit Messages

FAQ for Geeks

Why to use imperative form in commit messages?

I.e. why to use add test for #foo versus added test for #foo or adding test for foo?

Makes commit logs way more readable. See the work you did during a commit as a work on an issue and the commit as solving that issue. Now write about for what issue the commit is a result rather than what you did or are currently doing.

Example: You write a test for the function #foo. You commit the test. You use the commit message add test for #foo. Why? Because that is what the commit solves.

How to categorize commits which are direct follow ups to merges?

Use chore(merge): <what>.

I want to commit a micro change. What should I do?

Ask yourself, why it is only a micro change. Use feat = docs, style or chore depending on the change of your merge. Please see next question if you consider commiting work in progress.

I want to commit work in progress. What should I do?

Do not do it or do it (except for locally) or do it on a non public branch (ie. non master / develop ...) if you need to share the stuff you do.

When you finished your work, squash the changes to commits with reasonable commit messages and push them on a public branch.