Skip to content

Latest commit

 

History

History
169 lines (127 loc) · 5.08 KB

CONTRIBUTING.md

File metadata and controls

169 lines (127 loc) · 5.08 KB
Raw

Commit Message Conventions

These rules are adapted from the AngularJS commit conventions.

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

Generating CHANGELOG.md

We use these three sections in changelog: 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 --first-parent --pretty=format:%s

New features in this release

git log <last release>..HEAD --first-parent --grep feature:

Recognizing unimportant commits

These are formatting changes (adding/removing spaces/empty lines, indentation), missing semi colons, comments. So when you are looking for some change, you can ignore these commits - no logic change inside this commit.

When bisecting, you can ignore these by:

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

Provide more information when browsing the history

This would add kinda “context” information. Look at these messages (taken from last few angular’s commits):

  • 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

All of these messages try to specify where is the change. But they don’t share any convention...

Merge commits

Since we only add code through pull requests, the commit messages for those should follow this format. (The commit messages for non-merges don't need to.)

Format of the commit message

<type>: <subject>
<BLANK LINE>
<body>
<BLANK LINE>
<footer>

Any line of the commit message cannot be longer 100 characters! This allows the message to be easier to read on github as well as in various git tools.

Subject line

Subject line contains succinct description of the change.

Allowed <type>

NOTE: none of these are capitalized!

  • feat (feature)
  • fix (bug fix)
  • docs (documentation)
  • style (formatting, missing semi colons, …)
  • refactor
  • test (when adding missing tests)
  • chore (maintain)

<subject> text

  • Use imperative, present tense: “change” not “changed” nor “changes”.
  • Capitalize first letter.
  • Dot (.) at the end.
  • Emojis are recommended, but not required.

Message body

  • Just as in use imperative, present tense: “change” not “changed” nor “changes”.
  • Include motivation for the change and contrast with previous behavior.

http://365git.tumblr.com/post/3308646748/writing-git-commit-messages http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html

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: New tabs now open at the bottom.

You can revert this behaviour by going to the add-on’s preferences, and selecting `open on top` in the `new tab location` dropdown.

Referencing issues

Closed bugs should be listed on a separate line in the footer prefixed with "Fixes" keyword like this:

Fixes #234

or in case of multiple issues:

Fixes #123.
Fixes #245.
Fixes #992.

Merged branch

The merged branch and pull request number should also be mentioned here.

Merge pull request #123 from contributor/branch-name.

Examples

fix: Remove margin from popups.

Make the CSS more specific, to handle more cases.

Fixes #135.
Merge pull request #314 from ericawright/remove-from-popups.
fix: Don't show unidentified buttons in the tab's toolbar.

Style tools from tab-bar as hidden until further decision can be made on where to put them.
Restore tools' positions upon disabling tab center.

Fixes #4.
Fixes #304.
Merge pull request #311 from bwinton/tab-bar-buttons.
docs: Added a CONTRIBUTING.md.

Merge pull request #420 from bwinton/docs.