The goal of this document is to walk you through the concepts and specifics that should be understood while contributing to projects hosted in the OpenDev infrastructure.

In case you had already tried to setup git-review and it failed, it might be necessary to remove the Gerrit remote from git:

Git-review normally communicates with Gerrit using SSH over port 29418 with no further configuration needed. However, if you suspect that ssh over non-standards ports might be blocked (or you need to access the web using https) then you can configure git-review to use an https endpoint instead of ssh. Keep in mind that you will need to generate an HTTP password in Gerrit to use this connection. You should run the following command before “git review -s”:

Projects that are part of OpenStack project require signing the Individual Contributor License Agreement, see these detailed instructions .

For further information about the use of IRC in OpenStack, see IRC Guide .

You can find the OpenDev community in the #opendev IRC channel on Freenode.

There are times when the OpenDev team needs to configure channels to only allow people to join who are using a Registered Nick. Registering a Nick also prevents someone else from taking a Nick that people come to know you by.

If you do not know how to connect to Freenode, the Connecting to Freenode document will help.

While development on OpenDev only requires an account on the OpenDev Gerrit Code Review System, effective development in OpenDev hosted projects often requires interacting with other developers in IRC channels on Freenode. It is recommended to start by getting set up on IRC so that one can ask questions if one encounters issues with other phases of account setup.

The steps necessary to create a Gerrit account are described in Getting Started . Only extra recommended steps will be described here.

Development Workflow¶

Working on Bugs¶ Bug reports for a project are generally tracked on Launchpad at https://bugs.launchpad.net/<projectname>, or on StoryBoard ( https://storyboard.openstack.org). Contributors may review these reports regularly when looking for work to complete. There are 4 key tasks with regards to bugs that anyone can do: Confirm new bugs: When a bug is filed, it is set to the “New” status. A “New” bug can be marked “Confirmed” once it has been reproduced and is thus confirmed as genuine. Solve inconsistencies: Make sure bugs are Confirmed, and if assigned that they are marked “In Progress” Review incomplete bugs: See if information that caused them to be marked “Incomplete” has been provided, determine if more information is required and provide reminders to the bug reporter if they haven’t responded after 2-4 weeks. Review stale In Progress bugs: Work with assignee of bugs to determine if the bug is still being worked on, if not, unassign them and mark them back to Confirmed or Triaged. Learn more about working with bugs for various projects at: https://wiki.openstack.org/wiki/BugTriage Bug statuses are documented here: https://docs.openstack.org/project-team-guide/bugs.html If you find a bug that you wish to work on, you may assign it to yourself. When you upload a review, include the bug in the commit message for automatic updates back to Launchpad or StoryBoard. The following options are available for Launchpad: Closes - Bug : ####### Partial - Bug : ####### Related - Bug : ####### and for StoryBoard: Task : ###### Story : ###### Mentioning the story will create a handy link to the story from gerrit, and link to the gerrit patch in StoryBoard. Mentioning the task will change the task status in StoryBoard to ‘review’ while the patch is in review, and then ‘merged’ once the patch is merged. When all tasks in a story are marked ‘merged’, the story will automatically change status from ‘active’ to ‘merged’. If the patch is abandoned, the task status will change back to ‘todo’. It’s currently best to note both story and task so that the task status will update and people will be able to find the related story. Also see the Including external references section of the OpenStack Git Commit Good Practices wiki page.

Working on Specifications and Blueprints¶ Many OpenStack project teams have a <projectteam>-specs repository which is used to hold approved design specifications for additions and changes to the project team’s code repositories. The layout of the repository will typically be something like: specs /< release >/ It may also have subdirectories to make clear which specifications are approved and which have already been implemented: specs /< release >/ approved specs /< release >/ implemented You can typically find an example spec in specs/template.rst . Check the repository for the project team you’re working on for specifics about repository organization. Specifications are proposed for a given release by adding them to the specs/<release> directory and posting it for review. The implementation status of a blueprint for a given release can be found by looking at the blueprint in Launchpad. Not all approved blueprints will get fully implemented. Specifications have to be re-proposed for every release. The review may be quick, but even if something was previously approved, it should be re-reviewed to make sure it still makes sense as written. Historically, Launchpad blueprints were used to track the implementation of these significant features and changes in OpenStack. For many project teams, these Launchpad blueprints are still used for tracking the current status of a specification. For more information, see the Blueprints wiki page. View all approved project team’s specifications at https://specs.openstack.org/.

Starting a change¶ The Getting Started page explains how to originally clone and prepare a git repository. This only has to be done once, as you can reuse the cloned repository for multiple changes. Before creating your topic branch, just make sure you have the latest upstream changes: git remote update git checkout master git pull -- ff - only origin master

Git branch names¶ You may pick any name for your git branch names. By default, it will be reused as the topic for your change in Gerrit: git checkout - b TOPIC - BRANCH Best practices recommend, if you are working on a specific blueprint, to 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 ). If you want to use a different gerrit topic name from the git branch name, you can use the following command to submit your change: git review - t TOPIC

Committing changes¶ 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: Implements : blueprint BLUEPRINT Closes - Bug : ####### (Partial-Bug or Related-Bug are options) For example: Adds keystone support ... Long multiline description of the change ... Implements : blueprint authentication Closes - Bug : #123456 Change - Id : I4946a16d27f712ae2adf8441ce78e6c0bb0bb657 Note that in most cases the Change-Id line should be automatically added by a Gerrit commit hook installed by git-review. If you already made the commit and the Change-Id was not added, do the Gerrit setup step and run: git commit --amend . 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. Do not change the Change-Id when amending a change as that will confuse Gerrit. Make your changes, commit them, and submit them for review: git commit - a Note 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.

Using Signed-off-by¶ Projects may require the use of a Signed-off-by , and even if they do not, you are welcome to include Signed-off-by in your commits. By doing so, you are certifying that the following is true: Developer 's Certificate of Origin 1.1 By making a contribution to this project , I certify that : ( a ) The contribution was created in whole or in part by me and I have the right to submit it under the open source license indicated in the file ; or ( b ) The contribution is based upon previous work that , to the best of my knowledge , is covered under an appropriate open source license and I have the right under that license to submit that work with modifications , whether created in whole or in part by me , under the same open source license ( unless I am permitted to submit under a different license ), as indicated in the file ; or ( c ) The contribution was provided directly to me by some other person who certified ( a ), ( b ) or ( c ) and I have not modified it . ( d ) I understand and agree that this project and the contribution are public and that a record of the contribution ( including all personal information I submit with it , including my sign - off ) is maintained indefinitely and may be redistributed consistent with this project or the open source license ( s ) involved . A Signed-off-by header takes the following form in a commit message: Signed - off - by : Full Name < email @example . com > If you add the -s option to git commit , this header will be added automatically: git commit - s

Running Unit Tests¶ Before submitting your change, you should test it. To learn how to run python based unit tests in OpenStack projects see Running Python Unit Tests

Previewing a Change¶ Before submitting your change, you should make sure that your change does not contain the files or lines you do not explicitly change: git show

Submitting a Change for Review¶ Once you have committed a change to your local repository, all you need to do to send it to Gerrit for code review is run: git review When that completes, automated tests will run on your change and other developers will peer review it.

Updating a Change¶ If the code review process suggests additional changes, make and amend the changes to the existing commit. Leave the existing Change-Id: footer in the commit message as-is. Gerrit knows that this is an updated patchset for an existing change: git commit - a -- amend git review Understanding Changes and Patch Sets¶ It’s important to understand how Gerrit handles changes and patch sets. Gerrit combines the Change-Id in the commit message, the project, and the target branch to uniquely identify a change. A new patch set is determined by any modification in the commit hash. When a change is initially pushed up it only has one patch set. When an update is done for that change, git commit --amend will change the most current commit’s hash because it is essentially a new commit with the changes from the previous state combined with the new changes added. Since it has a new commit hash, once a git review is successfully processed, a new patch set appears in Gerrit. Since a patch set is determined by a modification in the commit hash, many git commands will cause new patch sets. Three common ones that do this are: git commit --amend

git rebase

git cherry-pick As long as you leave the “Change-Id” line in the commit message alone and continue to propose the change to the same target branch, Gerrit will continue to associate the new commit with the already existing change, so that reviewers are able to see how the change evolves in response to comments.

Squashing Changes¶ 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: git checkout master git pull origin master git checkout TOPIC - BRANCH git rebase - i master 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.

Adding a 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. 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 - a git review 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 patchset from the depended commit, you can do the following. Fetch and checkout the parent change: git review -d $PARENT_CHANGE_NUMBER Cherry-pick your commit on top of it: git review -x $CHILD_CHANGE_NUMBER Submit rebased change for review: git review 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.

Rebasing a commit¶ Sometimes the target branch you are working on has changed, which can create a merge conflict with your patch. In this case, you need to rebase your commit on top of the current state of the branch. This rebase needs to be done manually: Checkout and update master: $ git checkout master $ git remote update Checkout the working branch and rebase on master: $ git review -d 180503 $ git rebase origin/master If git indicates there are merge conflicts, view the affected files: $ git status Edit the listed files to fix conflicts, then add the modified files: $ git add <file1> <file2> <file3> Confirm that all conflicts are resolved, then continue the rebase: $ git status $ git rebase --continue