Trace Compass/Contributor Guidelines

This page explains how to contribute code to the Trace Compass project.

When to submit patches

As with any open-source project, external contributions are very appreciated! If you have a simple and straightforward fix to an obvious bug, feel free to push it directly to the project's Gerrit (see below).

If you wish to work on a larger problem or feature, it would be a good idea to contact us first, either on the mailing list or in the IRC channel. It could avoid duplicate work in case somebody is already working on the same thing. For substantial new features, it is always good to discuss their design and integration first on bugzilla.

What to submit

• Your patch should not introduce any error or warning. The project uses many non-default compiler settings, if you get unexpected errors, see this page for common fixes.

• Follow the project's coding style. It is defined in Eclipse project settings, which are committed in the tree, so simply hitting Ctrl+Shift+F in Eclipse should auto-format the current file.
  • Basically, 4 spaces for indentation, opening brackets on the same line.
  • We've turned off the auto-wrapping and unwrapping of lines, because it was doing more harm than good. Please wrap lines to reasonable lengths (100-120 is a good soft limit). Do NOT wrap after '.' (method invocations), it makes the code less readable. After '(' or ',' is usually good.

• Split your larger contributions in smaller, independant commits that could go in independently of each other. It is not unsual to have patch #1 go in quickly, but then have patch #2 go through many rounds of review. Smaller commits make the process faster for everyone (remember, the time taken to review a patch is n^2, where n is the number of lines in the patch!)

• Use short and meaningful commit titles. Good advice about commit titles/messages can be found at this page. Also make sure your commits have Change-Id (see below) and Signed-off-by lines.

• Not a hard requirement, but we normally prefix the commit titles with the name of the component to which the patch applies, in lowercase. This normally corresponds to the plugin name, so "lttng: xxxx" or "tmf: xxxx".

Where to submit

The Trace Compass maintainers use the Gerrit installation hosted at Eclipse to submit patches and review external contributions. This means anybody can push a branch to a special Git URL, which will create an entry on the Web UI where the review process can be followed.

Instructions can be found at the Gerrit page on the Eclipse wiki. The most important parts are:

• Make sure you have an Eclipse account, and that you have signed the Eclipse CLA.
• Upload your SSH key via the Gerrit Web UI.
• Set up the git-commit hook, and make sure your commits have a Change-Id line in them.

If any of these are missing, Gerrit will reject your patches when you try to push them, with a message explaining what should be done to rectify it.

To push patches to the Trace Compass Gerrit, use the following remote configuration:

[remote "eclipse-review"]
	url = ssh://<username>@git.eclipse.org:29418/tracecompass/org.eclipse.tracecompass.git
	push = HEAD:refs/for/master

subsituting <username> with your Eclipse user name.

The review process

We will try to give feedback to new patches in a reasonable amount of time, usually in the following days. Smaller patches makes the review go faster.

We try to have two (2) committers review every patch that goes in. For a patch from a committer, this means a second committer should review it. For a patch from a non-committer, one committer should do a thorough review, and at least a second one should give a quick look.

For a patch to be approved, it need to be marked as Verified and Code Review. Verified in general means that the patch technically works, it compiles, the tests pass, and it does what it is supposed to do. Code Review means the patch "looks" good, it follows the coding style, uses relevant algorithms and data structures, etc.

If a patch is marked -1, a comment should be given to explain what needs to be fixed. Unlike Bugzilla, it is unfortunately not possible to "assign" a review in Gerrit. If a patch is marked -1 with comments, it is then expected for the author to provide either answers to the questions that were asked, or to push a new version of the patch.

To push a new version of a Gerrit patch, simply amend (using git commit --amend or by using the amend button) the commit and push again to the same branch. This is where the Change-Id line comes into play: if Gerrit sees that same Change-Id targeted at the same branch, it will add a new version to the existing entry instead of creating a new entry.

Do not get discouraged if your patch is given a -1! The worst answer you could receive is no answer at all, which means your patch got completely ignored. A -1 really means "we love you and want to make your patch better!" ;)