OpenStack - User contributions [en]

Meetings/HeatAgenda

2013-12-10T19:48:10Z

Andersonvom: /* Agenda */ Add date to current agenda

= Weekly Heat (Orchestration) meeting =
The [https://launchpad.net/heat heat] Orchestration project team holds a meeting in <code><nowiki>#openstack-meeting</nowiki></code>:
* Wednesdays at [http://www.timeanddate.com/worldclock/fixedtime.html?hour=20&min=0&sec=0 2000 UTC]

Everyone is welcome.

The blueprints that are used as a basis for [https://launchpad.net/heat the heat project] can be found at https://blueprints.launchpad.net/heat

=== Agenda (2013-12-11) ===
* Review last meeting's actions
* Adding items to the agenda
* Unassigned icehouse-2 blueprints
* Repurposing of the stack/resource status columns - related to [https://blueprints.launchpad.net/heat/+spec/stack-convergence stack convergence]
* Open discussion

== Previous meetings ==
* [http://eavesdrop.openstack.org/meetings/heat/2013/ 2013 Heat meeting archive]
* [http://eavesdrop.openstack.org/meetings/heat/2012/ 2012 Heat meeting archive]

== Meeting organizers ==
* Publish the agenda 24h in advance
* Mail the agenda to the list and invite participants
* Ask each person responsible for an action from the previous meeting to prepare a line of the form, for each action item: . #info nickname description of the action link to the diff / mailing list thread etc. describing the implementation of the action
* Use http://meetbot.debian.net/Manual.html to get an automatic summary
* Mail the automatic summary as a reply to the invitation

Glance

2013-11-06T20:06:08Z

Andersonvom: /* Documentation */ Fix typo

= [[OpenStack]] Image service ("Glance") =

{| border="1" cellpadding="2" cellspacing="0"
| Source code
| https://github.com/openstack/glance
|-
| Bug tracker
| https://bugs.launchpad.net/glance/+bugs
|-
| Blueprints
| https://blueprints.launchpad.net/glance
|-
| Developer doc
| http://docs.openstack.org/developer/glance/
|}

== Related projects ==
* Python Glance client
* Image API documentation

== Documentation ==
* [http://docs.openstack.org/api/openstack-image-service/2.0/content/openstack-image-service-api-v2-reference.html Image API (v2) specification]
* [http://docs.openstack.org/api/openstack-image-service/1.0/content/ Image API (v1) specification]
* [http://docs.openstack.org/trunk/openstack-compute/admin/content/ Administration Guide]

== Other resources ==
* [[InstallInstructions/Glance|Install Instructions]]
* [[GlanceFeatureMatrix|Feature Support Matrix]]

Keystone/Trusts

2013-11-01T14:36:45Z

Andersonvom: /* To enumerated the trusts */ Fix headers of HTTP calls

__TOC__

= Trusts =
== Use Cases ==
# HEAT and failover. It needs to move a virtual machine from one host to another.
# Content production. Something generates a large file and needs to store it in swift.

In both cases, the users authorizes it at setup time to perform this action any time in the future, long after the token is expired.

== Rules ==
"Keystone is the Delegation Service that handles all the delegations for users. It is trusted to ensure that

* a delegator cannot delegate an attribute he has not already been assigned
* a delegator cannot delegate once the delegation depth has been consumed
* a delegator cannot delegate outside the validity period of his own delegation.

In other words, a delegator can only delegate less than (or equal to) what he already has, and not more than it.

== Current Status of Delegation ==
Right now, a user delegates in a short term fashion using tokens. Once a token has been granted to a user, he hands that off to another (service) user in order to prove his identity and authorization to perform some set of actions. In addition, since tokens are not scoped to a specific endpoint, they are currently passed on from one endpoint to another. This is not a secure approach. If any endpoint along the way is compromised, all the tokens in that endpoint are usable against any other service that accepts tokens. So we limit the scope of tokens to only that single endpoint, and we remove the attack. As a result, we also remove the ability of the remote service user to request additional operations from additional remote services on behalf of the original user. This is a problem that the trusts are designed to serve.

== Rules ==
* A trust is a promise to allow delegation at some point in the future. The actual delegation is performed in the token. The trust is used to get the token.
* The data for the delegation itself is simply the uuid user_ids for the trustor and trustee, along with the privileges that are being delegated.
* The delegated privileges are a combination of a tenant id and a number of roles that must be a subset of the roles assigned to the trustor.
** If all privileges are missing, then nothing is being delegated (ie. there is not a way of saying "delegate everything").
* A final parameter, delegation depth, says whether the delegation is recursive or not, and if recursive specifies the length of the delegation chain.
** A value of 0 (or missing) means that the delegate cannot delegate these permissions further.
** A value of 1 means that the delegate can delegate the permissions to any set of delegates but the latter cannot delegate further.
** A value of 2 means the delegation chain can be extended by a further length of 2 (ie. delegator to delegate to subdelegate to subsubdelegate).
** A value of 'inf' means that the delegation is infinitely recursive.
* There is also a list of endpoints associated with the delegation.
** This further restricts the delegation to the specified endpoints only.
** If the endpoints are missing, then the delegation is useless.
** A special value of 'all_endpoints' allows the trust to be used by all endpoints associated with the delegated tenant.
* There is an optional value for duration, which comprises the start time and end time for the trust.

== APIs ==
=== To create a trust ===
POST /trusts

When POSTing to trusts, the trustor supplies

* trustee: a user ID
* tenantId:
* roles
* endpoints
* trust start time (optional, defaults to submission time)
* trust end time (optional, defaults to never)
* delegation depth (optional)

The trustor ID is implied from the creating users ID.

=== To enumerated the trusts ===
GET /trusts/

This will return a document with two lists:
* The first is the list of trusts for which the user is the trustor
* The second is a list of trusts for which the user is the trustee

=== To enumerate the list of trustees for trusts that the user has created: ===
GET /user/<id>/trustees

* Which will return a list of trustee user ids, each of which is associated with a list of URLS for the associated trusts.
* This will view active trusts. disabled trusts will require an additional paramater (disabled)
* Only the trustor will be able to access this URL. Any other user will get a 403 (Forbidden).

=== To enumerate the set of trustors that have nominated the user as the trustee: ===
GET /user/<id>/trustors

* Which will return a list of trustor user ids, each of which is associated with a list of URLS for the associated trusts.
* This will view active trusts. disabled trusts will require an additional paramater (disabled)
* Only the trustor will be able to access this URL. Any other user will get a 403 (Forbidden)

=== To view a trust ===
* GET /trusts/{trustID}
* This will view active trusts. disabled trusts will require an additional paramater (disabled)
* Only the trustor or trustee will be able to access this URL. Any other user will get a 403 (Forbidden).

=== To deactivate a trust ===
* DELETE /trusts/{trustID}
* This sets the trust status to disabled.
* Only the trustor will be able to access this URL. Any other user will get a 403 (Forbidden).

=== TrustID ===
The trust id is a blob, and for the first implementation, will be a UUID. It should be useless to anyone but the trustor and the trustee. No other user should be able to view it. The user should be able to enumerate her preauthentications, in order to view, modify, and delete them. /users/preauthentications

== Implementation ==
Implemented in two phases.

== Token Format Changes ==
Each token created from a Trust will have two additional fields.

* '''trustee''' field with the userID of the trustee
* '''trust''' field with the trust ID.

When performing recursive delegation, there needs to be a record of the delegation chain, not least so that the trustor can understand how the new trustee has been added to the token. Thus, each token will have a '''trusts '''field. This will be a list with the name of each trustee in the chain, ordered from the original trustee to the trustee that requested the token.

Phase 1

# Trusts get implemented today "hard wired" with the attributes that are currently exposed in a token: (trustor) user, tenant, roles, endpoints.
# Tokens that get generated from the trusts will look just like normal tokens. They will have an additional field "trustee". This will allow the current consumers of tokens to continue to use a trust token just like they do now.

Phase 2.

# Modify the token architecture to allow arbitrary sets of attributes.
# Modify the trust architecture to specify arbitrary sets of attributes to be used in a token.

Keystone/Trusts

2013-11-01T14:25:14Z

Andersonvom: /* To enumerated the trusts */ Fix lists and HTTP calls

__TOC__

= Trusts =
== Use Cases ==
# HEAT and failover. It needs to move a virtual machine from one host to another.
# Content production. Something generates a large file and needs to store it in swift.

In both cases, the users authorizes it at setup time to perform this action any time in the future, long after the token is expired.

== Rules ==
"Keystone is the Delegation Service that handles all the delegations for users. It is trusted to ensure that

* a delegator cannot delegate an attribute he has not already been assigned
* a delegator cannot delegate once the delegation depth has been consumed
* a delegator cannot delegate outside the validity period of his own delegation.

In other words, a delegator can only delegate less than (or equal to) what he already has, and not more than it.

== Current Status of Delegation ==
Right now, a user delegates in a short term fashion using tokens. Once a token has been granted to a user, he hands that off to another (service) user in order to prove his identity and authorization to perform some set of actions. In addition, since tokens are not scoped to a specific endpoint, they are currently passed on from one endpoint to another. This is not a secure approach. If any endpoint along the way is compromised, all the tokens in that endpoint are usable against any other service that accepts tokens. So we limit the scope of tokens to only that single endpoint, and we remove the attack. As a result, we also remove the ability of the remote service user to request additional operations from additional remote services on behalf of the original user. This is a problem that the trusts are designed to serve.

== Rules ==
* A trust is a promise to allow delegation at some point in the future. The actual delegation is performed in the token. The trust is used to get the token.
* The data for the delegation itself is simply the uuid user_ids for the trustor and trustee, along with the privileges that are being delegated.
* The delegated privileges are a combination of a tenant id and a number of roles that must be a subset of the roles assigned to the trustor.
** If all privileges are missing, then nothing is being delegated (ie. there is not a way of saying "delegate everything").
* A final parameter, delegation depth, says whether the delegation is recursive or not, and if recursive specifies the length of the delegation chain.
** A value of 0 (or missing) means that the delegate cannot delegate these permissions further.
** A value of 1 means that the delegate can delegate the permissions to any set of delegates but the latter cannot delegate further.
** A value of 2 means the delegation chain can be extended by a further length of 2 (ie. delegator to delegate to subdelegate to subsubdelegate).
** A value of 'inf' means that the delegation is infinitely recursive.
* There is also a list of endpoints associated with the delegation.
** This further restricts the delegation to the specified endpoints only.
** If the endpoints are missing, then the delegation is useless.
** A special value of 'all_endpoints' allows the trust to be used by all endpoints associated with the delegated tenant.
* There is an optional value for duration, which comprises the start time and end time for the trust.

== APIs ==
=== To create a trust ===
POST /trusts

When POSTing to trusts, the trustor supplies

* trustee: a user ID
* tenantId:
* roles
* endpoints
* trust start time (optional, defaults to submission time)
* trust end time (optional, defaults to never)
* delegation depth (optional)

The trustor ID is implied from the creating users ID.

=== To enumerated the trusts ===
GET /trusts/

This will return a document with two lists:
* The first is the list of trusts for which the user is the trustor
* The second is a list of trusts for which the user is the trustee

To enumerate the list of trustees for trusts that the user has created:

GET /user/<id>/trustees

* Which will return a list of trustee user ids, each of which is associated with a list of URLS for the associated trusts.
* This will view active trusts. disabled trusts will require an additional paramater (disabled)
* Only the trustor will be able to access this URL. Any other user will get a 403 (Forbidden).

To enumerate the set of trustors that have nominated the user as the trustee:

GET /user/<id>/trustors

* Which will return a list of trustor user ids, each of which is associated with a list of URLS for the associated trusts.
* This will view active trusts. disabled trusts will require an additional paramater (disabled)
* Only the trustor will be able to access this URL. Any other user will get a 403 (Forbidden)

=== To view a trust ===
* GET /trusts/{trustID}
* This will view active trusts. disabled trusts will require an additional paramater (disabled)
* Only the trustor or trustee will be able to access this URL. Any other user will get a 403 (Forbidden).

=== To deactivate a trust ===
* DELETE /trusts/{trustID}
* This sets the trust status to disabled.
* Only the trustor will be able to access this URL. Any other user will get a 403 (Forbidden).

=== TrustID ===
The trust id is a blob, and for the first implementation, will be a UUID. It should be useless to anyone but the trustor and the trustee. No other user should be able to view it. The user should be able to enumerate her preauthentications, in order to view, modify, and delete them. /users/preauthentications

== Implementation ==
Implemented in two phases.

== Token Format Changes ==
Each token created from a Trust will have two additional fields.

* '''trustee''' field with the userID of the trustee
* '''trust''' field with the trust ID.

When performing recursive delegation, there needs to be a record of the delegation chain, not least so that the trustor can understand how the new trustee has been added to the token. Thus, each token will have a '''trusts '''field. This will be a list with the name of each trustee in the chain, ordered from the original trustee to the trustee that requested the token.

Phase 1

# Trusts get implemented today "hard wired" with the attributes that are currently exposed in a token: (trustor) user, tenant, roles, endpoints.
# Tokens that get generated from the trusts will look just like normal tokens. They will have an additional field "trustee". This will allow the current consumers of tokens to continue to use a trust token just like they do now.

Phase 2.

# Modify the token architecture to allow arbitrary sets of attributes.
# Modify the trust architecture to specify arbitrary sets of attributes to be used in a token.

Keystone/Trusts

2013-11-01T14:20:15Z

Andersonvom: /* Rules */ Reword and fix typo

__TOC__

= Trusts =
== Use Cases ==
# HEAT and failover. It needs to move a virtual machine from one host to another.
# Content production. Something generates a large file and needs to store it in swift.

In both cases, the users authorizes it at setup time to perform this action any time in the future, long after the token is expired.

== Rules ==
"Keystone is the Delegation Service that handles all the delegations for users. It is trusted to ensure that

* a delegator cannot delegate an attribute he has not already been assigned
* a delegator cannot delegate once the delegation depth has been consumed
* a delegator cannot delegate outside the validity period of his own delegation.

In other words, a delegator can only delegate less than (or equal to) what he already has, and not more than it.

== Current Status of Delegation ==
Right now, a user delegates in a short term fashion using tokens. Once a token has been granted to a user, he hands that off to another (service) user in order to prove his identity and authorization to perform some set of actions. In addition, since tokens are not scoped to a specific endpoint, they are currently passed on from one endpoint to another. This is not a secure approach. If any endpoint along the way is compromised, all the tokens in that endpoint are usable against any other service that accepts tokens. So we limit the scope of tokens to only that single endpoint, and we remove the attack. As a result, we also remove the ability of the remote service user to request additional operations from additional remote services on behalf of the original user. This is a problem that the trusts are designed to serve.

== Rules ==
* A trust is a promise to allow delegation at some point in the future. The actual delegation is performed in the token. The trust is used to get the token.
* The data for the delegation itself is simply the uuid user_ids for the trustor and trustee, along with the privileges that are being delegated.
* The delegated privileges are a combination of a tenant id and a number of roles that must be a subset of the roles assigned to the trustor.
** If all privileges are missing, then nothing is being delegated (ie. there is not a way of saying "delegate everything").
* A final parameter, delegation depth, says whether the delegation is recursive or not, and if recursive specifies the length of the delegation chain.
** A value of 0 (or missing) means that the delegate cannot delegate these permissions further.
** A value of 1 means that the delegate can delegate the permissions to any set of delegates but the latter cannot delegate further.
** A value of 2 means the delegation chain can be extended by a further length of 2 (ie. delegator to delegate to subdelegate to subsubdelegate).
** A value of 'inf' means that the delegation is infinitely recursive.
* There is also a list of endpoints associated with the delegation.
** This further restricts the delegation to the specified endpoints only.
** If the endpoints are missing, then the delegation is useless.
** A special value of 'all_endpoints' allows the trust to be used by all endpoints associated with the delegated tenant.
* There is an optional value for duration, which comprises the start time and end time for the trust.

== APIs ==
=== To create a trust ===
POST /trusts

When POSTing to trusts, the trustor supplies

* trustee: a user ID
* tenantId:
* roles
* endpoints
* trust start time (optional, defaults to submission time)
* trust end time (optional, defaults to never)
* delegation depth (optional)

The trustor ID is implied from the creating users ID.

=== To enumerated the trusts ===
* GET /trusts/
* This will return a document with two lists.
** The first is the list of trusts for which the user is the trustor
** The second is a list of trusts for which the user is the trustee

To enumerate the list of trustees for trusts that the user has created:

* GET /user/<id>/trustees
* Which will return a list of trustee user ids, each of which is associated with a list of URLS for the associated trusts.
* This will view active trusts. disabled trusts will require an additional paramater (disabled)
* Only the trustor will be able to access this URL. Any other user will get a 403 (Forbidden).

To enumerate the set of trustors that have nominated the user as the trustee:

* GET /user/<id>/trustors
* Which will return a list of trustor user ids, each of which is associated with a list of URLS for the associated trusts.
* This will view active trusts. disabled trusts will require an additional paramater (disabled)
* Only the trustor will be able to access this URL. Any other user will get a 403 (Forbidden)

=== To view a trust ===
* GET /trusts/{trustID}
* This will view active trusts. disabled trusts will require an additional paramater (disabled)
* Only the trustor or trustee will be able to access this URL. Any other user will get a 403 (Forbidden).

=== To deactivate a trust ===
* DELETE /trusts/{trustID}
* This sets the trust status to disabled.
* Only the trustor will be able to access this URL. Any other user will get a 403 (Forbidden).

=== TrustID ===
The trust id is a blob, and for the first implementation, will be a UUID. It should be useless to anyone but the trustor and the trustee. No other user should be able to view it. The user should be able to enumerate her preauthentications, in order to view, modify, and delete them. /users/preauthentications

== Implementation ==
Implemented in two phases.

== Token Format Changes ==
Each token created from a Trust will have two additional fields.

* '''trustee''' field with the userID of the trustee
* '''trust''' field with the trust ID.

When performing recursive delegation, there needs to be a record of the delegation chain, not least so that the trustor can understand how the new trustee has been added to the token. Thus, each token will have a '''trusts '''field. This will be a list with the name of each trustee in the chain, ordered from the original trustee to the trustee that requested the token.

Phase 1

# Trusts get implemented today "hard wired" with the attributes that are currently exposed in a token: (trustor) user, tenant, roles, endpoints.
# Tokens that get generated from the trusts will look just like normal tokens. They will have an additional field "trustee". This will allow the current consumers of tokens to continue to use a trust token just like they do now.

Phase 2.

# Modify the token architecture to allow arbitrary sets of attributes.
# Modify the trust architecture to specify arbitrary sets of attributes to be used in a token.

Gerrit Workflow

2013-10-31T20:39:33Z

Andersonvom: /* Add dependency */ Fix typo

= Gerrit Workflow Quick Reference =
Use this section as a quick reference for commands that you need to run to begin work in a new repository. Read this entire section before you complete the steps in the workflow for the first time. Then, review this section when you start work on a new [[OpenStack]] project. For a more complete description of the setup, see [[GerritJenkinsGit]].

[[File:Contribution path.png]]

== Account Setup ==
You'll need a [https://launchpad.net/+login Launchpad account], since this is how the Web interface for the Gerrit Code Review system will identify you. This is also useful for automatically crediting bug fixes to you when you address them with your code commits.

If you haven't already, [https://www.openstack.org/join/ join The OpenStack Foundation] (it's free and required for all code contributors). Among other privileges, this also allows you to vote in elections and run for elected positions within The OpenStack Project. When signing up for Foundation Membership, make sure to give the same E-mail address you'll use for code contributions, since this will need to match your preferred E-mail address in Gerrit.

Visit https://review.openstack.org/ and click the '''Sign In''' link at the top-right corner of the page. Log in with your Launchpad ID.

Because Gerrit uses Launchpad OpenID single sign-on, you won't need a separate password for Gerrit, and once you log in to one of Launchpad, Gerrit, or Jenkins, you won't have to enter your password for the others.

Unless you are an U.S. Government Employee (see below), [https://review.openstack.org/#/settings/agreements agree to the Individual Contributor License Agreement] and provide contact information. Your full name and E-mail address will be public (since they also appear in project commit logs) and the latter needs to match the user.email in your Git configuration. The other contact information (postal address, phone numbers) will be kept confidential and is only used as a fallback record in the unlikely event The OpenStack Foundation needs to reach you directly over code contribution related matters. This contact information can also be easily [https://review.openstack.org/#/settings/contact updated] later if desired, but make sure the primary E-mail address always matches the one you set for your OpenStack Foundation Membership--otherwise Gerrit will give you an error message and refuse to accept your contact information.

Employees of the the U.S. Government do not sign the Individual CLA. Instead, someone with authority to sign on behalf of your agency should sign the [[GovernmentCLA|U.S. Government Contributor License Agreement]]. Please contact the OpenStack Foundation to initiate this process.

If you are '''contributing on behalf of a company''' or organization, you still need to sign the ICLA above but someone at your company or organization also needs to sign the [https://review.openstack.org/#/settings/agreements Corporate Contributor License Agreement] providing a list of people authorized to commit code to OpenStack. Check [[HowToUpdateCorporateCLA|How to update the CCLA]] to provide changes to such list. A list of current companies and organizations with an existing [[Contributors/Corporate|Corporate CLA]] is available for your review.

You'll also want to [https://review.openstack.org/#/settings/ssh-keys upload an SSH key] while you're at it, so that you'll be able to [[GerritWorkflow|commit changes for review]] later.

Ensure that you have run these steps to let git know about your email address:

<pre><nowiki>
git config --global user.name "Firstname Lastname"
git config --global user.email "your_email@youremail.com"
</nowiki></pre>

To check your git configuration:

<pre><nowiki>
git config --list
</nowiki></pre>

== Git Review Installation ==
We recommend using the "git-review" tool which is a git subcommand that handles all the details of working with Gerrit, the code review system used in [[OpenStack]] development. Before you start work, make sure you have git-review installed on your system.

On Ubuntu, MacOSx, or most other Unix-like systems, it is as simple as:

<pre><nowiki>
pip install git-review
</nowiki></pre>

On Ubuntu Precise (12.04) and later, git-review is included in the distribution, so install it as any other package:

<pre><nowiki>
apt-get install git-review
</nowiki></pre>

On Fedora 16 and later, git-review is included into the distribution, so install it as any other package:

<pre><nowiki>
yum install git-review
</nowiki></pre>

On Fedora 15 and earlier you have to install pip (its package name is `python-pip`), then install git-review using pip in a conventional way.

On Red Hat Enterprise Linux, you must first enable the [http://fedoraproject.org/wiki/EPEL EPEL] repository, then install it as any other package:

<pre><nowiki>
yum install git-review
</nowiki></pre>

On openSUSE 12.2 and later, git-review is included in the distribution under the name python-git-review, so install it as any other package:
<pre><nowiki>
zypper in python-git-review
</nowiki></pre>

All of git-review's interactions with gerrit are sequences of normal git commands. If you want to know more about what it's doing, just add -v to the options and it will print out all of the commands it's running.

== Project Setup ==
Clone a project in the usual way, for example:

<pre><nowiki>
git clone git://git.openstack.org/openstack/nova.git
</nowiki></pre>

You may want to ask git-review to configure your project to know about Gerrit at this point. If you don't, it will do so the first time you submit a change for review, but you probably want to do this ahead of time so the Gerrit Change-Id commit hook gets installed. To do so (again, using Nova as an example):

<pre><nowiki>
cd nova
git review -s
</nowiki></pre>

Git-review checks that you can log in to gerrit with your ssh key. It assumes that your gerrit/launchpad user name is the same as the current running user. If that doesn't work, it asks for your gerrit/launchpad user name. If you don't remember the user name go to the [https://review.openstack.org/#/settings/ settings page on gerrit] to check it out (it's not your email address).

Note that you can verify the SSH host keys for review.openstack.org here: https://review.openstack.org/#/settings/ssh-keys

If you get the error "We don't know where your gerrit is.", you will need to add a new git remote. The url should be in the error message. Copy that and create the new remote.

<pre><nowiki>
git remote add gerrit ssh://<username>@review.openstack.org:29418/openstack/nova.git
</nowiki></pre>

In the project directory, you have a `.git` hidden directory and a `.gitreview` hidden file. You can see them with:

<pre><nowiki>
ls -la
</nowiki></pre>

== Normal Workflow ==
Once your local repository is set up as above, you must use the following workflow.

Make sure you have the latest upstream changes:

<pre><nowiki>
git remote update
git checkout master
git pull --ff-only origin master
</nowiki></pre>

Create a [http://progit.org/book/ch3-4.html topic branch] to hold your work and switch to it. If you are working on a blueprint, name your topic branch '''bp/BLUEPRINT''' where BLUEPRINT is the name of a blueprint in launchpad (for example, "bp/authentication"). The general convention when working on bugs is to name the branch '''bug/BUG-NUMBER''' (for example, "bug/1234567"). Otherwise, give it a meaningful name because it will show up as the topic for your change in Gerrit.

<pre><nowiki>
git checkout -b TOPIC-BRANCH
</nowiki></pre>

To generate documentation artifacts, navigate to the directory where the pom.xml file is located for the project and run the following command:

<pre><nowiki>
mvn clean generate-sources
</nowiki></pre>

For complete information about generating documentation artifacts, see "Build Output Locally" on the https://wiki.openstack.org/wiki/Documentation/HowTo page.

=== Committing Changes ===
[[GitCommitMessages|Git commit messages]] should start with a short 50 character or less summary in a single paragraph. The following paragraph(s) should explain the change in more detail.

If your changes addresses a blueprint or a bug, be sure to mention them in the commit message using the following syntax:

<pre><nowiki>
Implements: blueprint BLUEPRINT
Closes-Bug: ####### (Partial-Bug or Related-Bug are options)
</nowiki></pre>

For example:

<pre><nowiki>
Adds keystone support

...Long multiline description of the change...

Implements: blueprint authentication
Closes-Bug: #123456
Change-Id: I4946a16d27f712ae2adf8441ce78e6c0bb0bb657
</nowiki></pre>

Note that in most cases the Change-Id line should be automatically added by a Gerrit commit hook that you will want to install. See [[Gerrit_Workflow#Project_Setup|Project Setup]] for details on configuring your project for Gerrit. If you already made the commit and the Change-Id was not added, do the Gerrit setup step and run:
<pre>git commit --amend</pre>
The commit hook will automatically add the Change-Id when you finish amending the commit message, even if you don't actually make any changes.

Make your changes, commit them, and submit them for review:
<pre><nowiki>
git commit -a
git review
</nowiki></pre>

'''Caution: Do not check in changes on your master branch. Doing so will cause merge commits when you pull new upstream changes, and merge commits will not be accepted by Gerrit.

Prior to checking in make sure that you run "[http://testrun.org/tox/latest/ tox]".

=== Review ===
Once the code is committed, it appears at https://review.openstack.org. Please refer http://wiki.openstack.org/GerritJenkinsGit for more information. If the link corresponding to your code is clicked, it shows the status and other information. Automatic testing occurs and the results are displayed. Reviewers comment in the comment box or in the code itself.

If someone leaves an in-line comment, you can see it from expanded "Patch Set." "Comments" column shows how many comments are in each file. If you click a file name that has comments, the new page shows a diff page with the reviewer's name and comments. Click "Reply" and write your response. It is saved as a draft if you click "Save." Now, go back to the page that shows a list of patch sets and click "Review," and then, click "Publish comments."

If your code is not ready for review, click "Work in Progress" to indicate that a reviewer does not need to review it for now. Note that the button is invisible until you login the site.

More on what happens next is described on [[GerritJenkinsGit#Reviewing_a_Change]].

=== Drafts ===
A change can be submitted as a draft if, for example, it's not ready for merging, or even general code review, but you would like to share it selectively to get early comments. If you upload a change as a draft, by default, no one else can see it. You must explicitly add each person you would like to share it with as a reviewer. Reviewers you add can leave comments, but cannot vote at this stage. You can continue to upload new patchsets to the change as it evolves, and once it is ready for general review, you can click the "Publish" button. It becomes a normal change in Gerrit that everyone can see, including the earlier reviews from the draft stage. This is a one way transition; once a draft is published, it can't be made a draft again.

A draft change is uploaded by adding the "-D" option. Simply make changes, commit them, and submit them as a draft:

<pre><nowiki>
git commit -a
git review -D
</nowiki></pre>

'''Caution: Earlier versions (prior to 1.16) of git-review may also have the "-D" option, but the git ref that Gerrit uses to indicate a change should be a draft was changed; so if using "-D" results in an error, you may need to upgrade to latest.'''

=== Long-lived Topic Branches ===
If you are working on a larger project, you may be working on your topic branch for a while. In that case, you may want to check in your changes frequently during development and you must rebase your change to the current state of the master repository before submitting it for code review. In these situations you should prepare your change carefully before submitting it.

If the master repository has changed since you started, you should rebase your changes to the current state. And if you have made many small commits, you should squash them so that they do not show up in the public repository. Remember: each commit becomes a change in Gerrit, and must be approved separately. If you are making one "change" to the project, squash your many "checkpoint" commits into one commit for public consumption. Here's how:

<pre><nowiki>
git checkout master
git pull origin master
git checkout TOPIC-BRANCH
git rebase -i master
</nowiki></pre>

Use the editor to squash any commits that should not appear in the public history. If you want one change to be submitted to Gerrit, you should only have one "pick" line at the end of this process. After completing this, you can prepare your public commit message(s) in your editor. You start with the commit message from the commit that you picked, and it should have a Change-Id line in the message. Be sure to leave that Change-Id line in place when editing.

Once the commit history in your branch looks correct, run '''git review''' to submit your changes to Gerrit.

=== Updating a Change ===
If the code review process suggests additional changes, make and amend the changes to the the existing commit. Leave the existing Change-Id: footer in the commit message as-is. Gerrit knows that this is an updated patch for an existing change:

<pre><nowiki>
git commit -a --amend
git review
</nowiki></pre>

=== Add dependency ===
When you want to start new work that is based on the commit under the review, you can add the commit as a dependency.

<pre><nowiki>
#fetch change under review and check out branch based on that change.
git review -d $PARENT_CHANGE_NUMBER
git checkout -b $DEV_TOPIC_BRANCH
# Edit files, add files to git
git commit
git review
</nowiki></pre>

* '''NOTE:''' git review rebases the existing change (the dependency) and the new commit if there is a conflict against the branch they are being proposed to. Typically this is desired behavior as merging cannot happen until these conflicts are resolved. If you don't want to deal with new patchsets in the existing change immediately you can pass the -R option to git review in the last step above to prevent rebasing. This requires future rebasing to resolve conflicts.

If the commit your work depends on is updated, and you need to get the latest patch from the depended commit, you can do the following.

<pre><nowiki>
# fetch and checkout the parent change
git review -d $PARENT_CHANGE_NUMBER
# Note the branch created by git review. Should be review/$USER/$PARENT_CHANGE_ID or similar.
# Checkout existing development topic branch for the child commit.
git checkout $DEV_TOPIC_BRANCH
# Rebase onto updated parent branch to create a dependency on the latest version of that change.
git rebase -i review/$USER/$PARENT_CHANGE #This is the branch created by git review that was noted earlier.
# Do the revisions
git commit -a --amend
# submit for review
git review
</nowiki></pre>

The note for the previous example applies here as well. Typically you want the rebase behavior in git review. If you would rather postpone resolving merge conflicts you can use git review -R as the last step above.

Gerrit Workflow

2013-10-31T20:34:32Z

Andersonvom: Fix git commit message example

= Gerrit Workflow Quick Reference =
Use this section as a quick reference for commands that you need to run to begin work in a new repository. Read this entire section before you complete the steps in the workflow for the first time. Then, review this section when you start work on a new [[OpenStack]] project. For a more complete description of the setup, see [[GerritJenkinsGit]].

[[File:Contribution path.png]]

== Account Setup ==
You'll need a [https://launchpad.net/+login Launchpad account], since this is how the Web interface for the Gerrit Code Review system will identify you. This is also useful for automatically crediting bug fixes to you when you address them with your code commits.

If you haven't already, [https://www.openstack.org/join/ join The OpenStack Foundation] (it's free and required for all code contributors). Among other privileges, this also allows you to vote in elections and run for elected positions within The OpenStack Project. When signing up for Foundation Membership, make sure to give the same E-mail address you'll use for code contributions, since this will need to match your preferred E-mail address in Gerrit.

Visit https://review.openstack.org/ and click the '''Sign In''' link at the top-right corner of the page. Log in with your Launchpad ID.

Because Gerrit uses Launchpad OpenID single sign-on, you won't need a separate password for Gerrit, and once you log in to one of Launchpad, Gerrit, or Jenkins, you won't have to enter your password for the others.

Unless you are an U.S. Government Employee (see below), [https://review.openstack.org/#/settings/agreements agree to the Individual Contributor License Agreement] and provide contact information. Your full name and E-mail address will be public (since they also appear in project commit logs) and the latter needs to match the user.email in your Git configuration. The other contact information (postal address, phone numbers) will be kept confidential and is only used as a fallback record in the unlikely event The OpenStack Foundation needs to reach you directly over code contribution related matters. This contact information can also be easily [https://review.openstack.org/#/settings/contact updated] later if desired, but make sure the primary E-mail address always matches the one you set for your OpenStack Foundation Membership--otherwise Gerrit will give you an error message and refuse to accept your contact information.

Employees of the the U.S. Government do not sign the Individual CLA. Instead, someone with authority to sign on behalf of your agency should sign the [[GovernmentCLA|U.S. Government Contributor License Agreement]]. Please contact the OpenStack Foundation to initiate this process.

If you are '''contributing on behalf of a company''' or organization, you still need to sign the ICLA above but someone at your company or organization also needs to sign the [https://review.openstack.org/#/settings/agreements Corporate Contributor License Agreement] providing a list of people authorized to commit code to OpenStack. Check [[HowToUpdateCorporateCLA|How to update the CCLA]] to provide changes to such list. A list of current companies and organizations with an existing [[Contributors/Corporate|Corporate CLA]] is available for your review.

You'll also want to [https://review.openstack.org/#/settings/ssh-keys upload an SSH key] while you're at it, so that you'll be able to [[GerritWorkflow|commit changes for review]] later.

Ensure that you have run these steps to let git know about your email address:

<pre><nowiki>
git config --global user.name "Firstname Lastname"
git config --global user.email "your_email@youremail.com"
</nowiki></pre>

To check your git configuration:

<pre><nowiki>
git config --list
</nowiki></pre>

== Git Review Installation ==
We recommend using the "git-review" tool which is a git subcommand that handles all the details of working with Gerrit, the code review system used in [[OpenStack]] development. Before you start work, make sure you have git-review installed on your system.

On Ubuntu, MacOSx, or most other Unix-like systems, it is as simple as:

<pre><nowiki>
pip install git-review
</nowiki></pre>

On Ubuntu Precise (12.04) and later, git-review is included in the distribution, so install it as any other package:

<pre><nowiki>
apt-get install git-review
</nowiki></pre>

On Fedora 16 and later, git-review is included into the distribution, so install it as any other package:

<pre><nowiki>
yum install git-review
</nowiki></pre>

On Fedora 15 and earlier you have to install pip (its package name is `python-pip`), then install git-review using pip in a conventional way.

On Red Hat Enterprise Linux, you must first enable the [http://fedoraproject.org/wiki/EPEL EPEL] repository, then install it as any other package:

<pre><nowiki>
yum install git-review
</nowiki></pre>

On openSUSE 12.2 and later, git-review is included in the distribution under the name python-git-review, so install it as any other package:
<pre><nowiki>
zypper in python-git-review
</nowiki></pre>

All of git-review's interactions with gerrit are sequences of normal git commands. If you want to know more about what it's doing, just add -v to the options and it will print out all of the commands it's running.

== Project Setup ==
Clone a project in the usual way, for example:

<pre><nowiki>
git clone git://git.openstack.org/openstack/nova.git
</nowiki></pre>

You may want to ask git-review to configure your project to know about Gerrit at this point. If you don't, it will do so the first time you submit a change for review, but you probably want to do this ahead of time so the Gerrit Change-Id commit hook gets installed. To do so (again, using Nova as an example):

<pre><nowiki>
cd nova
git review -s
</nowiki></pre>

Git-review checks that you can log in to gerrit with your ssh key. It assumes that your gerrit/launchpad user name is the same as the current running user. If that doesn't work, it asks for your gerrit/launchpad user name. If you don't remember the user name go to the [https://review.openstack.org/#/settings/ settings page on gerrit] to check it out (it's not your email address).

Note that you can verify the SSH host keys for review.openstack.org here: https://review.openstack.org/#/settings/ssh-keys

If you get the error "We don't know where your gerrit is.", you will need to add a new git remote. The url should be in the error message. Copy that and create the new remote.

<pre><nowiki>
git remote add gerrit ssh://<username>@review.openstack.org:29418/openstack/nova.git
</nowiki></pre>

In the project directory, you have a `.git` hidden directory and a `.gitreview` hidden file. You can see them with:

<pre><nowiki>
ls -la
</nowiki></pre>

== Normal Workflow ==
Once your local repository is set up as above, you must use the following workflow.

Make sure you have the latest upstream changes:

<pre><nowiki>
git remote update
git checkout master
git pull --ff-only origin master
</nowiki></pre>

Create a [http://progit.org/book/ch3-4.html topic branch] to hold your work and switch to it. If you are working on a blueprint, name your topic branch '''bp/BLUEPRINT''' where BLUEPRINT is the name of a blueprint in launchpad (for example, "bp/authentication"). The general convention when working on bugs is to name the branch '''bug/BUG-NUMBER''' (for example, "bug/1234567"). Otherwise, give it a meaningful name because it will show up as the topic for your change in Gerrit.

<pre><nowiki>
git checkout -b TOPIC-BRANCH
</nowiki></pre>

To generate documentation artifacts, navigate to the directory where the pom.xml file is located for the project and run the following command:

<pre><nowiki>
mvn clean generate-sources
</nowiki></pre>

For complete information about generating documentation artifacts, see "Build Output Locally" on the https://wiki.openstack.org/wiki/Documentation/HowTo page.

=== Committing Changes ===
[[GitCommitMessages|Git commit messages]] should start with a short 50 character or less summary in a single paragraph. The following paragraph(s) should explain the change in more detail.

If your changes addresses a blueprint or a bug, be sure to mention them in the commit message using the following syntax:

<pre><nowiki>
Implements: blueprint BLUEPRINT
Closes-Bug: ####### (Partial-Bug or Related-Bug are options)
</nowiki></pre>

For example:

<pre><nowiki>
Adds keystone support

...Long multiline description of the change...

Implements: blueprint authentication
Closes-Bug: #123456
Change-Id: I4946a16d27f712ae2adf8441ce78e6c0bb0bb657
</nowiki></pre>

Note that in most cases the Change-Id line should be automatically added by a Gerrit commit hook that you will want to install. See [[Gerrit_Workflow#Project_Setup|Project Setup]] for details on configuring your project for Gerrit. If you already made the commit and the Change-Id was not added, do the Gerrit setup step and run:
<pre>git commit --amend</pre>
The commit hook will automatically add the Change-Id when you finish amending the commit message, even if you don't actually make any changes.

Make your changes, commit them, and submit them for review:
<pre><nowiki>
git commit -a
git review
</nowiki></pre>

'''Caution: Do not check in changes on your master branch. Doing so will cause merge commits when you pull new upstream changes, and merge commits will not be accepted by Gerrit.

Prior to checking in make sure that you run "[http://testrun.org/tox/latest/ tox]".

=== Review ===
Once the code is committed, it appears at https://review.openstack.org. Please refer http://wiki.openstack.org/GerritJenkinsGit for more information. If the link corresponding to your code is clicked, it shows the status and other information. Automatic testing occurs and the results are displayed. Reviewers comment in the comment box or in the code itself.

If someone leaves an in-line comment, you can see it from expanded "Patch Set." "Comments" column shows how many comments are in each file. If you click a file name that has comments, the new page shows a diff page with the reviewer's name and comments. Click "Reply" and write your response. It is saved as a draft if you click "Save." Now, go back to the page that shows a list of patch sets and click "Review," and then, click "Publish comments."

If your code is not ready for review, click "Work in Progress" to indicate that a reviewer does not need to review it for now. Note that the button is invisible until you login the site.

More on what happens next is described on [[GerritJenkinsGit#Reviewing_a_Change]].

=== Drafts ===
A change can be submitted as a draft if, for example, it's not ready for merging, or even general code review, but you would like to share it selectively to get early comments. If you upload a change as a draft, by default, no one else can see it. You must explicitly add each person you would like to share it with as a reviewer. Reviewers you add can leave comments, but cannot vote at this stage. You can continue to upload new patchsets to the change as it evolves, and once it is ready for general review, you can click the "Publish" button. It becomes a normal change in Gerrit that everyone can see, including the earlier reviews from the draft stage. This is a one way transition; once a draft is published, it can't be made a draft again.

A draft change is uploaded by adding the "-D" option. Simply make changes, commit them, and submit them as a draft:

<pre><nowiki>
git commit -a
git review -D
</nowiki></pre>

'''Caution: Earlier versions (prior to 1.16) of git-review may also have the "-D" option, but the git ref that Gerrit uses to indicate a change should be a draft was changed; so if using "-D" results in an error, you may need to upgrade to latest.'''

=== Long-lived Topic Branches ===
If you are working on a larger project, you may be working on your topic branch for a while. In that case, you may want to check in your changes frequently during development and you must rebase your change to the current state of the master repository before submitting it for code review. In these situations you should prepare your change carefully before submitting it.

If the master repository has changed since you started, you should rebase your changes to the current state. And if you have made many small commits, you should squash them so that they do not show up in the public repository. Remember: each commit becomes a change in Gerrit, and must be approved separately. If you are making one "change" to the project, squash your many "checkpoint" commits into one commit for public consumption. Here's how:

<pre><nowiki>
git checkout master
git pull origin master
git checkout TOPIC-BRANCH
git rebase -i master
</nowiki></pre>

Use the editor to squash any commits that should not appear in the public history. If you want one change to be submitted to Gerrit, you should only have one "pick" line at the end of this process. After completing this, you can prepare your public commit message(s) in your editor. You start with the commit message from the commit that you picked, and it should have a Change-Id line in the message. Be sure to leave that Change-Id line in place when editing.

Once the commit history in your branch looks correct, run '''git review''' to submit your changes to Gerrit.

=== Updating a Change ===
If the code review process suggests additional changes, make and amend the changes to the the existing commit. Leave the existing Change-Id: footer in the commit message as-is. Gerrit knows that this is an updated patch for an existing change:

<pre><nowiki>
git commit -a --amend
git review
</nowiki></pre>

=== Add dependency ===
When you want to start new work that is based on the commit under the review, you can add the commit as a dependency.

<pre><nowiki>
#fetch change under review and check out branch based on that change.
git review -d $PARENT_CHANGE_NUMBER
git checkout -b $DEV_TOPIC_BRANCH
# Edit files, add files to git
git commit
git review
</nowiki></pre>

* NOTE* git review rebases the existing change (the dependency) and the new commit if there is a conflict against the branch they are being proposed to. Typically this is desired behavior as merging cannot happen until these conflicts are resolved. If you don't want to deal with new patchsets in the existing change immediately you can pass the -R option to git review in the last step above to prevent rebasing. This requires future rebasing to resolve conflicts.

If the commit your work depends on is updated, and you need to get the latest patch from the depended commit, you can do the following.

<pre><nowiki>
# fetch and checkout the parent change
git review -d $PARENT_CHANGE_NUMBER
# Note the branch created by git review. Should be review/$USER/$PARENT_CHANGE_ID or similar.
# Checkout existing development topic branch for the child commit.
git checkout $DEV_TOPIC_BRANCH
# Rebase onto updated parent branch to create a dependency on the latest version of that change.
git rebase -i review/$USER/$PARENT_CHANGE #This is the branch created by git review that was noted earlier.
# Do the revisions
git commit -a --amend
# submit for review
git review
</nowiki></pre>

The note for the previous example applies here as well. Typically you want the rebase behavior in git review. If you would rather postpone resolving merge conflicts you can use git review -R as the last step above.