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.

1. Creating a Development Environment

This section describes general requirements for doing development on the OpenShift Origin code base. This is all basic info on setting 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.

1.1. Shell/Terminal Installation

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.

1.2. Software Installation

Once you have a working shell, you will need to install git, Ruby, and a Ruby gem called Bundler.

1.2.1. git

Install the most recent version of git available for your operating system:

  • Fedora / RHEL / CentOS:

    $ yum install git

  • OS X: git may be installed by default, but can also be installed by installing XCode or via a package manager like Homebrew or MacPorts.

  • Windows: Cygwin’s package manager should include the latest version of git for Windows systems.

1.2.2. Ruby

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:

  1. 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.

  2. The ruby193 SCL. If you are doing your development on a RHEL or CentOS system, you can also work with the ruby193 Software Collection.

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.

1.2.3. Bundler

Once you have a Ruby 1.9.3 environment, you can install Bundler into it using the gem command:

System or RVM
$ gem install bundler
ruby193 SCL
$ scl enable ruby193 "gem install bundler"

1.3. Creating a Local Repository

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.

1.3.1. Create a GitHub Account

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!

1.3.2. Fork a Repository

To start working with the code, you must first create a fork of the GitHub repository that you wish to contribute to.

  1. Navigate to the GitHub page of the repository you wish to fork.

  2. Click on the fork button on the top right corner of the page.

image

This creates a copy of the repository in your own GitHub space.

1.3.3. Cloning Your Fork

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.

Clone the repository from your fork
git clone [email protected]:<username>/<repo-name>.git
git clone [email protected]:kraman/origin-server.git
Add the upstream repo so that you can pull changes
git remote add upstream <original repo git url>
git remote add upstream [email protected]:openshift/origin-server.git

1.3.4. Working on a Topic Branch

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...

1.3.5. Staying Updated

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.

  1. Pull the latest changes from upstream

    $ git fetch upstream
$ git fetch upstream --tags

  2. Make sure there are no un-committed changes

    $ git stash

  3. Make sure we are working on the master branch

    $ git checkout master

  4. Merge the latest changes

    $ git merge upstream/master

  5. Push the updates changes to our GitHub fork

    $ git push origin master
$ git push origin --tags

  6. Return to your bug/feature branch

    $ git checkout dev/kraman/bug/12345

  7. Rebase this branch onto latest code from master (expect conflicts)

    $ git rebase master

  8. Resolve conflicts

  9. Push the rebased branch back to your fork

    $ git push origin dev/kraman/bug/12345 -f

  10. Restore any un-committed changes

    $ git stash pop
The git stash steps are optional. It is easier if you commit all changes before attempting a rebase.

1.4. The Vagrant Development Environment

As mentioned at the top of this section, OpenShift Origin has a very powerful development environment based on Vagrant. Check out the Vagrant Deployment Guide for all of the details on this system.

2. Hacking on OpenShift

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 rhc client utility

  • Release Engineering, which covers the packaging and distribution of OpenShift via RPM, vagrant, puppet, and oo-install

Each section below explains how and where to look for the feature backlog, bug records, and source code relevant to these areas.

2.1. General Notes

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.

Source Control: The source code for OpenShift origin lives in public repositories on GitHub. If you aren’t familiar with git, there are numerous primers available on the web.

2.2. Broker

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.

2.3. Runtime

"Runtime" refers to the components of OpenShift that are related to the hosted applications. This includes both the Node and the application Cartridges.

2.4. User Interface

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.

2.5. Release Engineering

Release engineering covers Origin testing, documentation and packaging.

3. Submitting Code

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:

  1. Update your branch and make sure you are rebased off the latest upstream/master:

    1. git fetch upstream

    2. git rebase upstream/<source_branch>

    3. git push origin <working_branch>

  2. Squash your commits onto a single revision (described below)

  3. Submit a pull request on GitHub (described below)

3.1. Combining multiple commits

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:

$ git log
commit 0681b5f7be31457f3c56928e63a8bee1696e2cdc
Author: Jane Doe <[email protected]>
Date:   Fri Jan 24 17:19:46 2014 -0500

    Completed changes for the fix for Bug 1234

commit 8e63a8bee1696e2cdc0681b5f7be31457f3c5692
Author: Jane Doe <[email protected]>
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 protected]>
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.

3.2. Creating a pull request

GitHub instructions on creating a pull request

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.

3.3. Getting Your Pull Request Reviewed

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:

  1. 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.

  2. You can log into the OpenShift developers' IRC channel, #openshift-dev on FreeNode, and ask for a code review.

  3. 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.