Notice: this Wiki will be going read only early in 2024 and edits will no longer be possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.
Difference between revisions of "Trace Compass/Commit message guidelines"
(→Example) |
(→Example) |
||
| Line 32: | Line 32: | ||
* Wrap the message body so that lines are less than 80 characters long. If a URL is too long, give it its own line, but don't break or wrap it. | * Wrap the message body so that lines are less than 80 characters long. If a URL is too long, give it its own line, but don't break or wrap it. | ||
| − | === | + | === Examples === |
| + | This is a typical patch, and what it should look like. | ||
<pre> | <pre> | ||
tmf.core: Add ability to support with timestamps beyond 2320. | tmf.core: Add ability to support with timestamps beyond 2320. | ||
Revision as of 21:33, 21 November 2016
The commit message plays an important role. They are the first thing other people will see of your commit. A good commit message will let the reviewers help merge a patch faster, it will also contribute towards the documentation of the project as people using the contributed patches can know what the patch does. Finally, in the off chance of there being a bug that gets in, a good commit message will allow searching and bisecting patches to be easier.
component: Short subject line More details. The blank line between the subject and body is mandatory. The subject line is used to represent the commit in code-review e-mails, search results, git-rebase, and more. Bug: T54321 Change-id:I12345 Signed-off-by: Bob Bobovich <bob@bobland.bob>
Contents
Structure
Subject
The first line of the commit message is known as the subject. It should less than 80 characters long (aim for 50-70).
- Write the subject line in the imperative mood (as if you're instructing someone). Start with "Change", "Add", "Fix", etc. not "Added" or "Fixes". For example "Add api-edit method".
- Do not end the subject with a period (full stop).
- Prefix the subject with the relevant component (the general area of code being modified).
Body
- Separate the body from the subject with an empty line.
- Think about the following questions:
- Why should this change should be made? What is wrong with the current code?'
- Why should it be done in this particular way?
- Did you try it in a different way first? Describe alternate approaches you took.
- Can a reviewer confirm that it works as intended?
- Avoid URLs in commit messages. (except for references)
- Use git hashes instead of URLs to refer to other changes.
- If there was external documentation or discussions, also summarize the relevant points.
- Wrap the message body so that lines are less than 80 characters long. If a URL is too long, give it its own line, but don't break or wrap it.
Examples
This is a typical patch, and what it should look like.
tmf.core: Add ability to support with timestamps beyond 2320. This patch changes the nanosecond timestamp to use unsigned math to handle timestamps in nanoseconds beyond the year 2320 without overflowing. Algorithm used: unsigned math: see java 8 spec here: java.com Does not yet address bug 4444. Follows-up Id5e7cbb1. Change-Id: I88c5f819c42d9fe1468be6b2cf74413d7d6d6907 Signed-Off-By: Gordon Freeman <gfreeman@blackmesa.gov>
Here are some examples where one line suffices.
SegStore.core: Bug 1701 fix typo javadoc in SegmentStoreFactory#create Change-Id: I88c5f819c42d9fe1468be6b2cf7441347d6d6904 Signed-Off-By: Mario Mario<itsamee@koopa.nes>
tmf.core: Add unit test for TmfTrace#equals Change-Id: I88c5f819c42d9fe1468be6b2cf74413d7d3d6905 Signed-Off-By: Christopher Blair <cblair@confed.gov>
Here is an example where more detail is needed
Add line chart entry to TimeGraphs Change-Id: I58c5f819c42d9fe1468be6b2cf74413d7d3d6905 Signed-Off-By: Marcus Fenix <xXxCOG_warrior_xXx@hotmail.com>
This is what it should look like
tmf.ui: Add line chart entry to TimeGraphs This adds a time graph entry that is a line chart in the style of spreadsheet application line charts. The range is self-adjusting so the maximum value is the top of the window range, and the minimum value is the bottom. Unless the max == min, in which case, it will be a straight line through the middle. Special care must be taken to not display more points than the resolution of the screen and the points must be in ascending X value order. It will be used in upcoming patches to display the IO usage per file and per process in the resources view. Tests and documentation are included in this patch. Change-Id: I58c5f819c42d9fe1468be6b2cf74413d7d3d6905 Signed-Off-By: Marcus Fenix <marcusfenix@hotmail.com>
Of note
Component
You may start the subject line with a component indicating what area of the code is affected by this commit.
It should be one of the following:
- The last two folders in a package. (eg: tmf.ui)
- The last common node eg: ctf.core and ctf.core.test would be ctf.core, ctf.core and ctf.ui would be ctf:.
- Try to make it easier to understand which maintainer/reviewer should handle your patch.
Change-Id
Gerrit's git-review tool will automatically append the "Change-Id: Ixxx" keyword to new commits.
Signed-Off-By
Signed-Off-By's are mandatory in eclipse projects.
Dependencies
If you have cross-repo dependencies (your commit depends on another commit in a different repository), declare them. It helps the review process.
Further reading
- A Note About Git Commit Messages - Tim Pope
- Using Git - Data Mapper
- Contribution guidelines - nodejs
- Submitting patches - git-core
- Commit guidelines - jQuery
- Writing good commit messages - Erlang
- Start your commit message with a verb, by Skud Bayley
References
- Original document that was modified to this. [1]