Skip to content

Instantly share code, notes, and snippets.

@abravalheri
Forked from stephenparish/commit.md
Last active June 21, 2024 05:50
Show Gist options
  • Save abravalheri/34aeb7b18d61392251a2 to your computer and use it in GitHub Desktop.
Save abravalheri/34aeb7b18d61392251a2 to your computer and use it in GitHub Desktop.
RFC: Git Commit Message Guidelines

Commit Message Guidelines

In the last few years, the number of programmers concerned about writing structured commit messages have dramatically grown. As exposed by Tim Pope in article readable commit messages are easy to follow when looking through the project history. Moreover the AngularJS contributing guides introduced conventions that can be used by automation tools to automatically generate useful documentation, or by developers during debugging process.

This document borrows some concepts, conventions and even text mainly from these two sources, extending them in order to provide a sensible guideline for writing commit messages.

Goals

  • allow generating CHANGELOG.md by script
  • allow ignoring commits by git bisect (not important commits like formatting)
  • provide better information when browsing the history

Motivation

Consider the following commit messages:

  • fix comment stripping
  • fixing broken links
  • Bit of refactoring
  • Check whether links do exist and throw exception
  • Fix sitemap include (to work on case sensitive linux)
  • Fix small typo in docs widget (tutorial instructions)
  • Fix test for scenario.Application - should remove old iframe
  • docs - various doc fixes
  • docs - stripping extra new lines
  • Replaced double line break with single when text is fetched from Google
  • Added support for properties in documentation

On the one hand, looking at the first 5 messages is not possible to identify which part of the code had changed. (The remaining messages try to specify where the change is, but they don't share any convention…)

On the other hand, commits introducing formatting changes (adding/removing spaces/empty lines, indentation), missing semi colons, comments, etc are not interesting to debug code or to documenting changes, since no logic change inside them.

Although it is possible to find more information by checking which files had been changed and performing some diffs, it is not practical when looking in git history.

Structural conventions can speed up this process, by allowing filtering. For example, when bisecting, you can ignore files by doing:

git bisect skip $(git rev-list --grep irrelevant <good place> HEAD)

Proposal

Commit Message Format

<type>(<scope>): <subject> <meta>
<BLANK LINE>
<body>
<BLANK LINE>
<footer>

The first line of a commit message should not be longer than 72 characters, and all the other lines should have a maximum of 100 characters! This allows the message to be easier to read on Github as well as in various git tools.

Subject line may be prefixed for continuous integration purposes. For example, JIRA requires ticket in the beggining of commit message message: "[LHJ-16] fix(compile): add unit tests for windows"

The usage of markup that can be read as plain text (e.g. markdown, reST, etc), specially in body and footer is optional, but useful when auto generating changelogs.

Allowed <type>

The <type> of a commit message should be a single word or abbreviation drawn from an ontology, according to the nature of the project. This document specifies a programming ontology, with the following elements:

  • feat: A new feature
  • fix: A bug fix
  • docs: Documentation only changes
  • style: Changes that do not affect the meaning of the code (white-space, formatting, missing semi-colons, etc)
  • refactor: A code change that neither fixes a bug nor adds a feature
  • perf: A code change that improves performance
  • test: Adding missing tests
  • build: Changes to the build/compilation/packaging process or auxiliary tools such as documentation generation
  • ci: Changes in the continuous integration/delivery setup

In the case a project decides to use a different ontology, this needs to be specified in its contributing guidelines (usually a CONTRIBUTING.md file in the root of the project), either by including a modified copy of the text in this document replacing the items in the list above, or by linking this document and providing a replacement type list. Example text:

<!-- CONTRIBUTING.md -->
# Commit Message Guidelines
This project follows [specific commit message guidelines](... link to this document), with the following allowed types:

* ...: ...
* ...: ...

An example of ontology for a book writing project is: typo, restructure, write, move, etc…

Allowed <scope> (optional)

Usually it is convenient to mention exactly which part of the code base changed. The <scope> token is responsible for providing that information. For example, imagine that a webserver introduces OAuth login via Facebook, a valid commit message would be:

feat(auth): introduce sign in via Facebook

Please notice that here auth might refer to a conceptual architectural component or even the basename of an file in the repository. While the granularity of the scope can vary, it is important for it to be a part of the "common language" spoken in the project.

Please notice that in some cases the scope is naturally too broad, and therefore not worthy to mention. Examples of this special case:

docs: replace old website URL
refactor: move folder structure to `src` directory layout

<subject> text

Subject line should contains succinct description of the change.

  • use imperative, present tense: “change” not “changed” nor “changes”
  • don't capitalize first letter
  • no dot (.) at the end

Allowed <meta> (optional)

Additionally, the end of subject-line may contain hashtags to facilitate changelog generation and bissecting.

  • #wip - indicate for contributors the feature being implemented is not complete yet. Should not be included in changelogs (just the last commit for a feature goes to the changelog).
  • #irrelevant - the commit does not add useful information. Used when fixing typos, etc... Should not be included in changelogs.

Message body

  • just as in <subject> use imperative, present tense: “change” not “changed” nor “changes”
  • includes motivation for the change and contrasts 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: isolate scope bindings definition has changed and
the inject option for the directive controller injection was removed.

To migrate the code follow the example below:

Before:

   scope: {
     myAttr: 'attribute',
     myBind: 'bind',
     myExpression: 'expression',
     myEval: 'evaluate',
     myAccessor: 'accessor'
   }

After:

   scope: {
     myAttr: '@',
     myBind: '@',
     myExpression: '&',
     // myEval - usually not useful, but in cases where the expression is assignable, you can use '='
     myAccessor: '=' // in directive's template change myAccessor() to myAccessor
   }

The removed `inject` wasn't generaly useful for directives so there should be no code using it.
Referencing issues

Closed bugs 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

Revert

If the commit reverts a previous commit, it should begin with revert:, followed by the header of the reverted commit. In the body it should say: This reverts commit ., where the hash is the SHA of the commit being reverted.

Examples

feat($browser): add onUrlChange event (popstate/hashchange/polling)

New $browser event:
- forward popstate event if available
- forward hashchange event if popstate not available
- do polling when neither popstate nor hashchange available

Breaks $browser.onHashChange, which was removed (use onUrlChange instead)
fix($compile): add unit tests for IE9

Older IEs serialize html uppercased, but IE9 does not...
Would be better to expect case insensitive, unfortunately jasmine does
not allow to user regexps for throw expectations.

Closes #392
Breaks foo.bar api, foo.baz should be used instead
feat(directive): add directives disabled/checked/multiple/readonly/selected

New directives for proper binding these attributes in older browsers (IE).
Added coresponding description, live examples and e2e tests.

Closes #351
style($location): add couple of missing semi colons
docs(guide): update fixed docs from Google Docs

Couple of typos fixed:
- indentation
- batchLogbatchLog -> batchLog
- start periodic checking
- missing brace
feat($compile): simplify isolate scope bindings

Change the isolate scope binding options to:
  - @attr - attribute binding (including interpolation)
  - =model - by-directional model binding
  - &expr - expression execution binding

This change simplifies the terminology as well as
number of choices available to the developer. It
also supports local name aliasing from the parent.

BREAKING CHANGE: isolate scope bindings definition has changed and
the inject option for the directive controller injection was removed.

To migrate the code follow the example below:

Before:

   scope: {
     myAttr: 'attribute',
     myBind: 'bind',
     myExpression: 'expression',
     myEval: 'evaluate',
     myAccessor: 'accessor'
   }

After:

   scope: {
     myAttr: '@',
     myBind: '@',
     myExpression: '&',
     // myEval - usually not useful, but in cases where the expression is assignable, you can use '='
     myAccessor: '=' // in directive's template change myAccessor() to myAccessor
   }

The removed `inject` wasn't generaly useful for directives so there should be no code using it.

Generating CHANGELOG.md

Changelogs may contain three sections: new features, bug fixes, breaking changes. This list could be generated by script when doing a release, along with links to related commits. Of course you can edit this change log before actual release, but it could generate the skeleton.

List of all subjects (first lines in commit message) since last release:

git log <last tag> HEAD --pretty=format:%s

New features in this release

git log <last release> HEAD --grep feat

Thanks to @stephenparish for the original text

@juanmeleiro
Copy link

Hi.

I currently use git not only for programming, but for writing too. Thinking about that, I suggest a format that permits any use of git as a versioning system, not only versioning of code.

Suggested changes:

  • Make <type> drawable from any ontology, thus separating format from content.
  • In view of previous suggestion, specify a format for such ontologies.

Types for writing could, for example, be ones such as typo, restructure, write, move, etc.

Some other general comments:

  • I didn't quite get the syntax for <scope>s
  • Explicitly say that <meta> tags may be structured; i.e. drawn from an ontology

What are your thoughts?

@fnog
Copy link

fnog commented Jan 24, 2020

Some typos from the first paragraph.

"In the last few yers years, the number of programmers concerned about writting structured commit messages had have dramatically grown."

"This document borrow borrows some concepts, conventions and even text mainly from these two sources, extending them in order to provide a sensible guideline for writing commit messages."

Kudos for the doc!

@abravalheri
Copy link
Author

Thank you very much @juanmeleiro and @fnog

@Zerri
Copy link

Zerri commented Aug 18, 2020

A commit that change only the Changelog file can use the prefix docs?

@abravalheri
Copy link
Author

Hi @Zerri, that is precisely what I would do. After all, changelogs are docs...

@Romulo-S
Copy link

What prefix shoud i use when migrating to a new version of a framework? Like PrimeNG 9 to 10?

@abravalheri
Copy link
Author

Hi Romulo, I suppose that, if you are not add features, introducing APIs or breaking APIs, that could be a build prefix. Or maybe you want to introduce something like deps?

@Romulo-S
Copy link

I just see in a page that you could use prefix vendor for dependencies and packages update so i recommended the team to use that

@goyalyashpal
Copy link

Or maybe you want to introduce something like deps?

i heard deps update go under the type chore

@henryobiaraije
Copy link

I figured this out and have been using it for a while. I saw this gist by browsing around to see if there are people who do this as well.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment