OpenStack-SDK-PHP/Process

This page is a document of the contribution process to the PHP SDK. This is a somewhat configurable process following the defaults and flow set by the OpenStack comminity. This is a fair bit different from the contribution process to Github other other places using a pull request style.

The following documents the typical process to adding a change.

Get the Code

You can start by getting the code from OpenStack or from the Github mirror. Getting it from either location is fine.

Make a Change

There are a few steps to making a change. Typically, you will start by creating a branch based on master for your change. Work done directly on the master branch can become an issue later if a change isn't accepted or you're managing multiple changes in parallel.

Branches associated with launchpad blueprints (feature requests) and bugs have a specific pattern to them. Blueprints are named bp/[blueprint name]. For example, bp/remove-deprecated. Bugs are name bug/[bug number]. For example, bug/1234.

On this new branch make changes scoped to this area. Note, every single commit related to the changes will be its own review in Gerrit. Each commit should be able to stand on it's own if merged into master in an unrelated manner to the other commits. If there is feedback or changes needed to the review being proposed, the commit itself will need to be amended to incorporate these chances.

The Gerrit workflow is quite different from Github and the pull request style. Instead of a pull request with multiple commits you end up with a commit (sometimes called a patch set) containing the change. The patch set is iterated on until it's ready to go in. This causes there to be a smaller history where each changes is clearly represented. This model is used on numerous Git based projects.

Send the commits to review

When the changes are ready to be seen by others, it's time to use git-review. Once you have git-review installed, from the base of the project run the command git review.

This will send the commits to the right place on review.openstack.org and provide you with a link to see the review and its progress.

The review process

Once a commit is into the review process it needs to get a score of +2 for a code review and +1 for workflow. Code review has to do with the quality of the commit for the project. Workflow is about acceptance into the project as a feature and the style of a feature. Regular reviewers, who are not part of the project, can +1 or -1 and commit. Those on the core team can give a score from -2 to +2 for a code review and -1 to +1 for workflow.

Once an item in review reaches +2 for a code review and +1 for workflow, Jenkins will merge it into master.

If a commit has comments on it, which may be inline in one of the files, and needs to be revied than the commit itself needs to be changed. In the original place it was created it can be amended or using git review -d 1234, where 1234 is the id or the review, the review can be downloaded. From here the code can be altered the git commit --amend can be used to amend the previous commit.

Andrew Hutchings has a clear example at http://www.linuxjedi.co.uk/2012/03/real-way-to-start-hacking-on-openstack.html.

Once the commit has changed, use git review to upload the new version. From here the review process scoring starts over on the new change set.

Questions?

If you have questions please feel free to ask in IRC (#openstack-sdks) or on the openstack-dev mailing list. We're happy to try and answer them or improve on this writeup.