Info

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. It 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

  • Self-commits are not allowed.
  • NEVER embed binary files including jar, war, tar, gz, gzip, zip in Gerrit

Reference

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 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  Fix, Add, Change 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.

OOM Specific case

As OOM is the installer, it receives merge requests from all ONAP components. It's therefore important to understand from which component it comes and what's the specific changes it comes from.

Therefore, the commit message (on OOM) must follow this form:

[NAME_OF_COMPONENT|DOC|COMMON|GENERIC] Meaningful title (from OOM side)

at least one sentence explaining the change done in this patch, cause and consequences and possibly more of course

Issue-ID: AS_WE_ARE_FORCED_BUT_MEANINGLESS
Change-ID: xxx
Sign-off: xxx

Commit message will be the last stuff that will stay with our code so it must clearly explain the changes, the "why" and the consequences. If it change OOM behavior in any way, documentation must be also updated.

Merge requests which are not following this pattern will not be merged.

Please read the following pages and follow the guidelines for writing commit message contained therein.


As you can see, most of the change is to declare which componentn is impacted by this change

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

https://gerrit.onap.org/r/Documentation/user-upload.html#push_replace (Thanks Geora)

10 Comments

  1. Gildas Lanilis

    Practice approved by TSC 2017-07-13 (topic #10). PDF Summary of materials presented.

    1. Rich Tabedzki

      In case of using 'git commit --ammend', does this command guarantee that the change will be pushed to gerrit after edit is complete or is "git review" required as the next command to execute?

      1. Pamela Dragosh

        Yes, git review is required as the next command.

      2. Andrew Grimberg

        'git commit --amend' only modifies the local commit object. This isn't a gerrit specific command, it's a sub-command of git itself. So, yes, a 'git review' is required after the change.

  2. Michael O'Brien

    Hi, could we put a header like "[OOM-1]" in the commit comment - then we can track a set of commits more easily in git history.  Also some systems hyperlink these headers to the actual JIRA - this would also aide for cross-repo distributed commits - thank you /michael

    1. Gildas Lanilis

      Hi,

      The commit header is limited to 50 characters, thus I would use that limited space to explain the goal of the commit.If someone needs more info he can dive into Jira.

      While performorfing the "git commit -s" cmd, git provides an opportunity to use the above external reference section to establish a link with Jira. You just need to enter the JIRA issue ID and Gerrit will create the hyperlink automatically (no need to enter the full url).

      1. Michael O'Brien

        Sounds good - will do on my next commit

        /michael

        1. Andrew Grimberg

          As of the August 10, 2017 TSC meeting JIRA issue ID's are required in the commit message. As Gildas Lanilis says, you shouldn't be putting the issue in the subject line. It's actually rather poor form. Instead the recommendation from LF Release Engineering is to put it into the message footer exactly like the graphic shows (in the 'External References') and without the [ ] surrounding it.

          For tracking related changes in Gerrit you should be using the same topic when needed as you can search topics in the Gerrit UI.

        2. Michael O'Brien

          The multi-line commit structure works very well - reviews are still referenced back to the JIRA

          Follow

          CommitStructure

          and use a "git commit --amend" for reviews already in progress.

          /michael

  3. Michael O'Brien

      We will need to update the wiki for cases where binaries like SDC zip files are required for testing

    https://wiki.onap.org/display/DW/Commit+Messages

      For example the vFWSNK.zip and vFWPKG.zip files for the vFW - https://wiki.onap.org/display/DW/Vetted+vFirewall+Demo+-+Full+draft+how-to+for+F2F+and+ReadTheDocs#VettedvFirewallDemo-Fulldrafthow-toforF2FandReadTheDocs-Prerequisites

    https://gerrit.onap.org/r/#/c/57083/

    LOG-522 - Getting issue details... STATUS