Contributing

OML and the instrumented applications are all open source software distributed under the MIT license. As such you are most welcome to have a peek at the code, clone it, and modify it. If you've found, and fixed, a bug, or have implemented a new feature or a new app which you would like to see added to our official codebase, your patches are most welcome.

A summary of how to contribute follows.

Modify the code

The easiest do make changes to OML is to work in a local Git clone. See Getting the source for details about cloning or repository. Alternatively, we also maintain a clone on GitHub (please don't post issues there, though).

To develop on top of a release branch, we recommend doing the following after cloning the repo, and before anything else.

$ cd oml
$ git checkout --track -b release/2.x origin/release/2.x
$ git checkout -b my-feature

This does two things: it first creates a tracking branch to track the remote origin/release/2.x branch (the most current release branch as of this writing), and then it creates a feature branch called my-feature rooted at the tip of the release/2.x branch. Replace my-feature with something more descriptive of what you want to develop.

You might want to have a look at our Coding Style Guidelines. While they are not enforced throughout all the current code, we aim at having a consistent style, and will eventually get there. It will be easier if your contributions already adhere to it.

Make sure you include informative and well-formatted messages with your commits [1]. Also, remember to --signoff (-s for short) your commits, for easier followup. The gittutorial(7) has plenty of other tips to get you started. This is particularly important if you intend to submit patches to be integrated into our master tree.

Configure your Git environment.

If you want to contribute your changes to us, please configure your Git environment, with at least your name and a valid email address, so we can properly acknowledge your work when integrating your commits. You can do it with

$ git config --global user.name "Your Name Comes Here" 
$ git config --global user.email you@yourdomain.example.com

The --global sets these parameters for all your Git repos. You can limit this to the current repo by removing this option.

Contribute changes

When you are satisfied with your changes, you can send them our way so we can review them and integrate them into the main tree. To do so, you have three options

1. Create an issue and attach the patches;
2. Send patches to the oml-develop@… mailing list ;
3. Send us a pull request (same issue tracker or mailing list as above).

Patch creation

The first two options need you to create patches from the Git branch containing your changes.

The best way to do this is with ​git format-patch(1) to have export them in a suitable format:

$ git format-patch origin/release/2.x..HEAD # Assuming you started working from origin/release/2.x

Pull request

If your repository is publicly accessible (e.g., on a server with anonymous read access or GitHub), you can also send us a pull request. Use git request-pull(1) rather than GitHub's internal system [see 2,3 for reasons]

$ git request-pull origin/release/2.x http://url/of/repo # Assuming you started working from origin/release/2.x

References

1. Tim Pope. A Note About Git Commit Messages. April 2008.
2. Linus Torvalds. I don't do github pull requests, and ensuing discussion. May 2012.
3. Scott Lawrence. Leaving GitHub. August 2012.