[English|한국어 (대한민국)|Indonesia|中文 (简体, 中国)|español (México)|English (United Kingdom)|Deutsch]

Set Up and Learn GIT

Note

This section assumes you have completedAccount Setup guide.

GIT

What is Git?

Git is a free and open source distributed version control system that theOpenStack community uses to manage changes to source code and documentation.

Git allows you to:

Installation

Mac OS

  1. Go to the Gitdownload page and clickMac OS X.

  2. The downloaded file should be a dmg in your downloads folder. Open that dmgfile and follow the instructions on screen.

If you use the package managerHomebrew, open a terminaland type:

brewinstallgit

Linux

For distributions like Debian, Ubuntu, or Mint open a terminal and type:

sudoaptinstallgit

For distributions like RedHat, Fedora or CentOS open a terminaland type:

sudodnfinstallgit

For SUSE distributions open a terminal and type:

sudozypperingit

Windows

Windows Subsystem for Linux (WSL)is available in Windows 10 Anniversary Update or later (build 1607+).There is the possibility to install and run modern Linux Operating Systems:

All common tools like bash, git, and SSH will work out of the box.

Although Gitdownload page provides Windowsinstallation binary, most OpenStack development tools (e.g., git-review)unfortunately will not work well on Windows environment.

Configure Git

Once you have Git installed you need to configure it. Open your terminalapplication and issue the following commands putting in your first/last nameand email address. This is how your contributions will be identified:

gitconfig--globaluser.name"Firstname Lastname"gitconfig--globaluser.email"your_email@youremail.com"

Note

Use the same email address that was used during the account setup.

Learning Git

You can useGit Immersion to workthrough tutorials for learning git.

For reference, use theGit Reference and Cheat Sheet.

Commit Messages

Commit messsages are the first things a reviewer sees and are used asdescriptions in the git log. They provide a description of the history ofchanges in a repository. Commit messages cannot be modified once the patch ismerged.

Format:

  • Summary Line

  • Empty line

  • Body

  • Empty line

  • Footers

Note

Footers should be entered one per line with no empty lines between them.

Summary Line

The summary line briefly describes the patch content. The character limit is 50characters. The summary line should not end with a period. If the change isnot finished at the time of the commit, start the commit message with WIP.

Body

The body contains the explanation of the issue being solved and why it shouldbe fixed, the description of the solution, and additional optional informationon how it improves the code structure, or references to other relevant patches,for example. The lines are limited to 72 characters. The body should containall the important information related to the problem, without assuming that thereader understands the source of the problem or has access to external sites.

Footers

Footers are lines in the final paragraph of a commit message, used to link thechange to other tools.

The following footer is required:

  • TheChange-Id line is a unique hash describing the change, which isgenerated automatically by a Git commit hook when you initially save a commitmessage. This should not be changed when rebasing a commit following reviewfeedback, since it is used by Gerrit, to track versions of a patch. It won’tappear when you’re editing a new commit message for the first time, but ifyoucommit--amend later you will see it.

StoryBoard specific footers:

  • Task:1234: the number of the task in Storyboard implemented by thechange. This will auto update the task to ‘Review’ status and assign itto you when you push the patch.

  • Story:1234567: the number of the story in Storyboard to which the taskbeing implemented belongs. This will post a comment on the story with alink to your patch.

Launchpad specific footers:

  • Closes-Bug:#123456789: useCloses-Bug if the commit is intended tofully fix and close the bug being referenced. Use the Launchpad ID of the bugfor the number; Gerrit automatically creates a link to the bug.

  • Partial-Bug:#123456789: usePartial-Bug if the commit is only apartial fix and more work is needed. Use the Launchpad ID of the bugfor the number; Gerrit automatically creates a link to the bug.

  • Related-Bug:#12456789: useRelated-Bug if the commit is merelyrelated to the referenced bug. Use the Launchpad ID of the bugfor the number; Gerrit automatically creates a link to the bug.

  • Partial-Implements: Use this footer if the change partially implementsa Launchpad blueprint. Use the name of the blueprint as an ID.

  • Implements: Use this footer if the change fully implementsa Launchpad blueprint. Use the name of the blueprint as an ID.

The following footers are optional; however, their use is recommended if theyare applicable to the patch:

  • TheDocImpact footer contains a comment about whythe change impacts documentation. Put DocImpact on a line by itself.Use this footer to indicate that documentation is either contained in thepatch or has documentation impact.When this footer is included in a commitmessage, Gerrit creates a bug for the project affected by the change for tasktracking, or move to the openstack-api-site as needed.

  • TheAPIImpact footer contains a comment about whythe change impacts a public HTTP API. Put APIImpact on a line by itself.Use this footer to indicate that the patch impacts a publicHTTP API. When this footer is included in a commit message,the API_Working_Group can use it to help find relevant reviews.

  • TheSecurityImpact footer is used to indicate that a change hassecurity implications and should be reviewed by the OpenStack Security Group.

  • TheUpgradeImpact footer contains a commentabout why the change impacts upgrades. It is used to indicate that a changehas upgrade implications for those doing continuous deployment or N to N+1upgrades. Also consider updating the ‘Upgrade Notes’ section in the releasenotes for the affected project.

  • TheDepends-On: <gerrit-change-url> footer is used to refer to a changethe current one depends on. Use the permalink of the change.