Skip to main content
Jump to: navigation, search

Trace Compass/Commit message guidelines

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>

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 JavaDoc typo 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

References

  • Original document that was modified to this. [1]

Back to the top