This document describes the recommended workflow to maintain a fork of a GitHub repository and how to submit pull requests for new features or bug fixes. Additionally you will find information on specific code areas within OpenShift and how to contribute to them.
This section describes general requirements for doing development on the OpenShift Origin code base. This is all basic info on asetting up an environment. Once you’ve done all of this, have a look at the Vagrant Deployment Guide. Unlike the other OpenShift deployment guides, Vagrant is strongly optimized in favor of developers.
Linux- and OS X-based systems come packaged with a shell or terminal environment that is suitable for Origin development. Windows users will need to install a shell environment, and currently the most active project for delivering this kind of environment is Cygwin. The rest of this document assumes that if you are working on a Windows system that you are working within the Cygwin environment.
Install the most recent version of git available for your operating system:
For compatibility with RHEL and CentOS, OpenShift runs on Ruby 1.9.3. You can develop using newer versions of Ruby as long as you do not use functionality that is not compatible with Ruby 1.9.3. If you’d prefer to play it safe, you have a few options for using Ruby 1.9.3 on systems where more recent versions of Ruby are shipped:
Ruby Version Manager. RVM enables you to locally compile side-by-side environments for different versions of Ruby. Refer to the RVM website for information on how to set up RVM and build ruby 1.9.3 locally.
The ruby193 SCL. If you are doing your development on a RHEL or CentOS system, you can also work with the
|If you intend to set up an Origin development environment according to the Vagrant Deployment Guide, do not use RVM. Vagrant and RVM have blocking interoperability issues.|
With a working shell environment and access to the
git source control utility, you have the basic tools you’ll need to copy the Origin code from GitHub and push your changes back when they’re ready. Next you need to head to GitHub to set up a working repository for yourself.
If you don’t have one already, head to GitHub and create an account for yourself. Registration is free and you won’t be able to submit code changes without an account!
To start working with the code, you must first create a fork of the GitHub repository that you wish to contribute to.
Navigate to the GitHub page of the repository you wish to fork.
Click on the fork button on the top right corner of the page.
This creates a copy of the repository in your own GitHub space.
Cloning is the process of copying your forked code to your local system. The
git utility does this in a way that establishes a relationship between your local copy of the code and the GitHub copy.
git clone email@example.com:<username>/<repo-name>.git git clone firstname.lastname@example.org:kraman/origin-server.git
Always try to avoid working on the master branch. It usually results in merge conflicts and/or update issues. Instead, work on a bug/feature/topic branch whenever possible.
#start from the master branch git checkout master #create a new branch git branch dev/kraman/bug/12345 #switch to the new branch git checkout dev/kraman/bug/12345 #...make changes...
Once a fork has been created, it does not automatically track the upstream repository. Follow the steps outlined below to keep the master branch up-to-date.
Pull the latest changes from upstream
$ git fetch upstream $ git fetch upstream --tags
Make sure there are no un-committed changes
$ git stash
Make sure we are working on the master branch
$ git checkout master
Merge the latest changes
$ git merge upstream/master
Push the updates changes to our GitHub fork
$ git push origin master $ git push origin --tags
Return to your bug/feature branch
$ git checkout dev/kraman/bug/12345
Rebase this branch onto latest code from master (expect conflicts)
$ git rebase master
Push the rebased branch back to your fork
$ git push origin dev/kraman/bug/12345 -f
Restore any un-committed changes
$ git stash pop
OpenShift development is divided roughly into the following areas:
Broker, which describes the Rails application that drives the REST API, plus management of Nodes via the message queuing service.
Runtime, which describes the operating environment of the Nodes and the cartridge framework
User Interface, which covers the web console, the admin console, and the
Release Engineering, which covers the packaging and distribution of OpenShift via RPM, vagrant, puppet, and
Each section below explains how and where to look for the feature backlog, bug records, and source code relevant to these areas.
The OpenShift Roadmap: If you are looking for a high-level idea of which features are in the pipeline for OpenShift Origin, check out our Roadmap Board on Trello. Each card in the "Epic Backlog" describes an overarching set of changes that is then broken down into cards across the backlogs of the different development areas.
Feature Backlogs: Each development area has their own backlog of tasks that is also maintained on Trello. Most of these tasks are associated with Epics from our Roadmap board.
Bug Tracking: We use Bugzilla to track the reports and resolutions of OpenShift bugs. If you hit weird behavior with an OpenShift component:
Once you know you’re dealing with an unreported bug, please don’t hesitate to submit it. The Bugzilla submission form will ask you which component of OpenShift the bug belongs under. See the development area information below which includes the relevant bugzilla groups.
The Broker itself is a Rails application that serves as the nerve center for OpenShift Origin. Everything from user creation to app deployment is handled through the Broker. The Broker exposes a REST API and communicates with Node hosts via AMQP.
"Runtime" refers to the components of OpenShift that are related to the hosted applications. This includes both the Node and the application Cartridges.
The user interface components include all of the things that users directly interact with when using OpenShift. Like the Broker, the web console and administrative consoles are Rails applications. Together with the
rhc command-line utility, the consoles act as clients to the Broker’s REST API.
Release engineering covers Origin testing, documentation and packaging.
If you are looking for information on specific code areas within OpenShift, jump to the next section. This section covers the basics of preparing modified code for being merged back into the Origin source.
Once your code is ready to be submitted, you will need to submit a pull request with your changes:
Update your branch and make sure you are rebased off the latest upstream/master:
git fetch upstream
git rebase upstream/<source_branch>
git push origin <working_branch>
Squash your commits onto a single revision (described below)
Submit a pull request on GitHub (described below)
Before you can submit a request, you should rebase and then squash all your changes on to a single commit. This makes it easier to review and also makes reverting the code easier in case of any build breakages.
To do this, first have a look at the recent commits to your local repository with
$ git log commit 0681b5f7be31457f3c56928e63a8bee1696e2cdc Author: Jane Doe <email@example.com> Date: Fri Jan 24 17:19:46 2014 -0500 Completed changes for the fix for Bug 1234 commit 8e63a8bee1696e2cdc0681b5f7be31457f3c5692 Author: Jane Doe <firstname.lastname@example.org> Date: Fri Jan 24 17:16:46 2014 -0500 Working on a fix for Bug 1234 commit fb35b5f8063485560494af0f7fcb600cb3adfe4c Merge: d8929c2 a703b5f Author: John Doe <email@example.com> Date: Fri Feb 14 09:54:59 2014 +0800 Merge pull request #2121 from other_coder/working_branch Fixed a bug in foo.bar
In this instance, the top two items in the log represent local commits to Jane Doe’s working branch. The third commit is a merge against upstream that was pulled in when Jane rebased her local repo directory. So in order to squash her intermediate commits into a single one, Jane will do an interactive rebase ("-i") starting from the most recent merge commit:
$ git rebase -i fb35b5f8063485560494af0f7fcb600cb3adfe4c
|You don’t need to enter the whole commit ID, but use copy and paste so that you don’t have to type any of it.|
The rebase editor will appear, and from here Jane can squash the commits:
pick 8e63a8b Working on a fix for Bug 1234 (1) pick 0681b5f Completed changes for the fix for Bug 1234 (2) # Rebase fb35b5f..0681b5f onto fb35b5f # # Commands: # p, pick = use commit # r, reword = use commit, but edit the commit message # e, edit = use commit, but stop for amending # s, squash = use commit, but meld into previous commit # f, fixup = like "squash", but discard this commit's log message # x, exec = run command (the rest of the line) using shell # # These lines can be re-ordered; they are executed from top to bottom. # # If you remove a line here THAT COMMIT WILL BE LOST. # # However, if you remove everything, the rebase will be aborted. # # Note that empty commits are commented out
|1||Replace "pick" with "r" or "reword" to make the initial commit’s message more explanatory: "Fix for Bug 1234 - broker.conf missing FOO_BAR setting."|
|2||On this line, replace "pick" with "f" or "fixup" to merge this commit into the initial commit.|
Now she can do a push to her forked repo on GitHub. If she previously pushed the intermediate commits, she will need to add the
--force flag to overwrite those with the new squashed commit:
$ git push origin my_working_branch --force
For more information about squashing commits, read the git Guide’s article on the topic.
If you need to make changes to your commit after a pull request has been issues, you can go back to the pull request page and update the commit range rather than submit a new pull requests.
The main OpenShift repos get dozens of pull requests per day. In order to make sure that your pull request is reviewed, please do one of these three things:
If you know the GitHub ID of the person who should review your code, you can alert them in a comment on your pull request by including the GitHub username preceded by the @ symbol.
You can log into the OpenShift developers' IRC channel, #openshift-dev on FreeNode, and ask for a code review.
You can send an e-mail to the OpenShift developers' mail list asking for a code review (don’t forget to include a link to the pull request).
Especially if you go with the mail list route, be sure to follow up if you don’t hear from anyone within a business day. In general the response time should be much shorter.