contributor-guide/doc/source/common/git.rst

Setup and Learn GIT

Note

This section assumes you have completed accounts guide.

GIT

What is Git?

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

Git allows you to:

• Push and test code, docs, infrastructure changes, and CI configurations
• Push Specifications
• Push Use cases for features

Installation

Mac OS

1. Go to the Git download page and click Mac OS X.
2. The downloaded file should be a dmg in your downloads folder. Open that dmg file and follow the instructions on screen.

If you use the package manager Homebrew, open a terminal and type:

brew install git

Linux

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

sudo apt install git

For distributions like RedHat, Fedora 21 or earlier, or CentOS open a terminal and type:

sudo yum install git

For Fedora 22 or later open a terminal and type:

sudo dnf install git

For SUSE distributions open a terminal and type:

sudo zypper in git

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:

• Ubuntu 16.04
• openSUSE Leap 42
• SLES 12

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

Although Git download page provides Windows installation 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 terminal application and issue the following commands putting in your first/last name and email address. This is how your contributions will be identified:

git config --global user.name "Firstname Lastname"
git config --global user.email "your_email@youremail.com"

Note

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

Learning Git

You can use Git Immersion to work through tutorials for learning git.

For reference, use the Git Reference and Cheat Sheet.

Commit Messages

Commit messsages are the first things a reviewer sees and are used as descriptions in the git log. They provide a description of the history of changes in a repository. Commit messages cannot be modified once the patch is merged.

Format:

• Summary Line
• Empty line
• Body
• Empty line
• Tags

Note

Tags should be entered one per line.

Summary Line

The summary line briefly describes the patch content. The character limit is 50 characters. The summary line should not end with a period. If the change is not 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 should be fixed, the description of the solution, and additional optional information on how it improves the code structure, or references to other relevant patches, for example. The lines are limited to 72 characters. The body should contain all the important information related to the problem, without assuming that the reader understands the source of the problem or has access to external sites.

Tags

Tags are references used to link the change to other tools.

The following tags are required:

• The Change-id line is a unique hash describing the change, which is generated automatically by a Git commit hook. This should not be changed when rebasing a commit following review feedback, since it is used by Gerrit, to track versions of a patch.

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

• Closes-Bug: #123456789: use Closes-Bug if the commit is intended to fully fix and close the bug being referenced. Use the Launchpad ID of the bug for the number; Gerrit automatically creates a link to the bug.
• Partial-Bug: #123456789: use Partial-Bug if the commit is only a partial fix and more work is needed. Use the Launchpad ID of the bug for the number; Gerrit automatically creates a link to the bug.
• Related-Bug: #12456789: use 'Related-Bug' if the commit is merely related to the referenced bug. Use the Launchpad ID of the bug for the number; Gerrit automatically creates a link to the bug.
• Partial-Implements: Use this tag if the change partially implements a Launchpad blueprint. Use the name of the blueprint as an ID.
• Implements: Use this tag if the change fully implements a Launchpad blueprint. Use the name of the blueprint as an ID.
• The DocImpact tag contains a comment about why the change impacts documentation. Put DocImpact on a line by itself. Use this tag to indicate that documentation is either contained in the patch or has documentation impact. When this tag is included in a commit message, Gerrit creates a bug for the project affected by the change for task tracking, or move to the openstack-api-site as needed.
• The APIImpact tag contains a comment about why the change impacts a public HTTP API. Put APIImpact on a line by itself. Use this tag to indicate that the patch impacts a public HTTP API. When this tag is included in a commit message, the API_Working_Group can use it to help find relevant reviews.
• The SecurityImpact tag is used to indicate that a change has security implications and should be reviewed by the OpenStack Security Group.
• The UpgradeImpact tag contains a comment about why the change impacts upgrades. It is used to indicate that a change has upgrade implications for those doing continuous deployment or N to N+1 upgrades. Also consider updating the 'Upgrade Notes' section in the release notes for the affected project.
• The Depends-On: <gerrit-change-url> tag is used to refer to a change the current one depends on. Use the permalink of the change.
• Task: 1234: the number of the task in Storyboard implemented by the change.
• Story: 1234567: the number of the story in Storyboard to which the task being implemented belongs.