-
Notifications
You must be signed in to change notification settings - Fork 20
Committing guidelines
The status of this document is currently Request for Comments.
Commit messages are a golden opportunity to give people context on what you are adding to the codebase. These are some guidelines to make sure everyone is using them consistently.
Your subject line (the commit title) should be a concise summary of the changes being submitted. Be specific and precise, and avoid getting into minuteness - additional context, if needed, should be added in the detailed commit description, not here.
Please keep the subject line under 70-75 characters. This encourages conciseness and ensures the summary is rendered fully in a diverse range of environments.
Good:
Add the user's fetch information in a global multidimensional array instead of a local one.
Bad:
Fixed scope bugs.
In most cases - except for the most trivial changes, a commit description (or "body") is needed in order to provide additional context (such as how and why a certain change - or set thereof - was implemented). Be descriptive and provide as much information as required, while also striving to minimize excessive verbosity.
Commit descriptions can have any arbitrary number of lines, within reason - use your best judgment. Does your description refer only to things that are relevant to the changes being made?
Also note that, unlike the commit summary, there is no restriction imposed on the commit description character length. Here as well, we expect contributors to use their best judgment, by using line breaks and blank lines where it makes sense.
- Include relevant information and context where you can, to allow us to quickly see the purpose of the commit. Don't be too verbose - be specific and concise.
- Write in the infinitive, not in the past - i.e. write "Add user details to the global scope and fetch on load" rather than "Added user details to the global scope and fetched on load"
- The use of standard markdown is allowed, but we prefer plain text. Use single quotes to refer to specific filenames or code snippets within the commit message (i.e.
404 error page: Fix conflicting 'margin' CSS property for 'body'). If using markdown, refer to a syntax cheatsheet if necessary. - Use short commit hashes whenever you need to refer to previous commits from your commit message. The short hash should preferably have a length of 8; a length of 7 is also acceptable. Example:
Complements 17236a81 by adding line break.
Note that the GitHub interface will always render commit hashes abbreviated to 7 chars.
If your change is small enough to not have a commit body, i.e. your subject line can describe your changes, then it's okay to commit without one. If you're making significant changes that require more explanation then you must include the commit body.
Each commit you make should do one thing. Try to make sure all changes in the commit are all for the same purpose - one refactoring, or one feature, etc. If you have more changes to make, split them up into multiple commits.
Commits on development branches need not pass tests every time. Particularly if you're writing your tests first and then developing features, it can be helpful to create a commit where tests don't pass.
Merges and commits to master must pass the tests every time. The master branch is considered the stable channel - anything on there should be suitable for production deployment. Commits should generally not be made directly to master - only organization and repository administrators have the ability to, and should avoid doing so if at all possible.