Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Comment: add note for submitting draft feature in gerrit

Table of Contents

Info
titleInfo

ONLY 1 JIRA issue per commit.

Think about this scenario: a developer performs a Commit for 1 new functionality and 4 bugs.

Then, here are the problems:

  1. It is difficult for the reviewer to understand which code relates to which issue.
  2. Tt takes the reviewer more time to review. You may even discourage the reviewer to look at the code submission.
  3. In case 1 bug is not properly fix, then the whole commit is rejected.
Info
titleInfo
  • Self-commits are not allowed.
  • NEVER embed jar, war, tar, gz, gzip, zip in Gerrit
Info
titleReference

To submit code into Gerrit on an unfinished feature, multiple times to bring transparency and get early feedback , refer to "Submitting a Draft Feature"

Overview

The following is based on OPEN-O experiences and multiple references in the open source community.

There are tons of reasons on why it is essentials to write good commit messages. For the sake of keeping things short, here are 3 reasons:

  • ONAP is public, so everything you do is widely visible. As you are proud of your work, you want to make good impressions.
  • It speeds up the reviewing process.
  • It helps to write good Release Notes.

Which Commits would you rather read?
Commit Bad

Commit Good

Commit Structure

Commit Structure

Approach

To formulate good commit message focus is these 3 points:

  • Explain the What, the Why and the How.
    • What: Do not assume the code is self-evident/self-documenting. The commit message should have a clear statement as to what the original problem is.
    • Why: It may fix a bug, it may add a feature, it may improve performance, reliability, stability, or just be a change for the sake of correctness. Describe the overall code structure, particularly for large changes, but more importantly describe the intent/motivation behind the changes.
    • How: Describe how the problem being fixed. Describe any limitations of the current code. For short obvious patches this part can be omitted, but it should be a high level description of what the approach was.
    • The smaller the amount of code being changed, the quicker & easier it is to review & identify potential flaws.
  • Keep in mind than within a 3 months, you may have to review your own code.

Do

  • Write the summary line and description of what you have done in the imperative mode, that is as if you were commanding someone. Start the line with a VERB  FixAddChange instead of Fixed, Added, Changed.
  • Always leave the second line blank.
  • Keep the summary line shorter than 50 characters.
  • Keep the body line around 72 characters. Make as much paragraph as you need.
  • One commit per change.
  • List THE issue addressed, (not a list of issues).

Don't

  • Don't terminate the summary line with a period - it's a title and titles don't end with a period.
  • Don't use ! or !! in the message. They are useless.
  • Don't provide the issue number in the summary. Use External Reference section to list the ONE Jira issue.
  • Don't mix two unrelated functional changes. Idea is to divide to conquer. Think about the reviewer who must desiccate with issues he faces. Think about how easy it will be in case you have to revert code.
  • Don't include whitespace changes together with code changes. Make 2 separate commits.
  • Don't include patch set-specific comments like "Patch set 2: rebased"

In case of wrong commit message

There is always a possibility to change to commit message before the code is merged.

You simply have to enter the command line: git commit --amend

This method is applicable only for the latest change.

Anchor
CommitProcessReference
CommitProcessReference
References

How to Write a Git Commit Message. Very inspiring, I particularly like this sentence What may be a hassle at first soon becomes habit, and eventually a source of pride and productivity for all involved.
OpenStack Git commit Good Practices
Commit Message Good Practices
Writing Good Commit Messages
On Commit Message