Contributing as a Non-Committer

If you're a committer on an Apache project, it means that you can commit directly to the project's repository. For instance, with Apache CloudStack committers are allowed to directly push commits into the git repository.

Non-committers, however, have to submit patches for review. Apache CloudStack accepts GitHub pull requests. If you are new to Git and GitHub, check these two links:

• GitHub 15 minutes tutorial
• Creating Pull Requests

Apache CloudStack has a read-only mirror on GitHub that is kept in sync with the canonical Git repo maintained by the Apache Software Foundation. Submitting GitHub pull requests is the easiest way to get your contribution upstream. For detailed instructions see the link below:

GitHub Contribution Guidelines

Submitting a patch through JIRA

While we encourage you to submit your contribution through GitHub pull requests, you can also attach a patch in a JIRA ticket. For the purpose of these instructions, we'll assume that you already have a system with Git and have found a bug to fix or have a feature that you'd like to submit, and you're willing to contribute that code or documentation under the Apache License 2.0.

Further, if you're fixing a bug we'll assume that you've either filed a bug report (where you will attach your patch) or are submitting a fix for a known bug. If you find a bug and would like to fix it, that's awesome! Please be sure to file the bug too, though.

If you want to add a feature, you should bring it up for discussion on the dev@cloudstack.apache.org mailing list before implementing it. This ensures that it meshes with the plans that other contributors have for Apache CloudStack, and that you're not doing redundant work. Other developers may also have ideas for the feature or suggestions that will help you land the feature without having to re-do the work. More information about our mailing lists can be found here.

In short, communication is a vital part of making a contribution to an Apache project.

Getting Started

First, lets make sure that you've added your name and email to your `~/.gitconfig`:

$ git config --global user.name "Your Name"
$ git config --global user.email you@domain.com

You'll grab the CloudStack source with git:

$ git clone https://git-wip-us.apache.org/repos/asf/cloudstack.git

If you already have the source, make sure you're working with the most recent version. Do a `git pull` if you cloned the source more than a few hours ago. (Apache CloudStack development can move pretty fast!)

$ git checkout -b mybranch

This does two things: One, it creates the branch mybranch and two, it changes your working branch to mybranch. Running `git branch` will show you which branch you're working on, with an asterisk next to the active branch, like so:

[user@localhost cloudstack]$ git branch
  master
  * mybranch
  

Make whatever changes you're going to make, be sure to use git add to stage the changes, and then you're going to commit the changes to your working branch:

git commit -m "Insert a meaningful summary of changes here."

Finally, you can create a patch and attach it to the JIRA issue that you created for the bug you are fixing.

git format-patch master --stdout > ~/patch-name.patch

Review

Once you've submitted your pull request, you should receive a response within a few days. If you receive no response within a week, please ping the cloudstack-dev mailing list (dev@cloudstack.apache.org).

Screencast

If you are new to git you might want to watch this screencast:

Further Reading

You might want to peruse the Get Involved page on Apache.org, and the On Contributing Patches doc as well. Note that some of that does not apply to Apache CloudStack, as we're using git rather than Subversion. But do respect the original style of the CloudStack code, and ensure that you're using spaces rather than tabs, and your patches have Unix line endings (LF) rather than Windows-type line endings (CRLF).