The LTTng project is open source and welcomes
contributions from anyone. This guide will walk you
through the process of contributing a patch to LTTng.
Get the source code
We use Git to control the versions of
the LTTng project. How to use Git is beyond the scope of
this guide, but its
official website provides
many great tutorials. Please refer to the
Download section
for the official LTTng Git repositories.
Programming style
We use the
Linux
kernel coding style with one addition for
LTTng-tools only: single-line
if/for/while
control statements must be wrapped in braces.
/* not good */
if (this == that)
goto fail;
/* good */
if (this == that) {
goto fail;
}
Although the LTTng code base is primarily written in C,
it does contain shell, Perl, Python, and Java code.
There is no official coding standard for these
languages. However, we encourage you to use a style
consistent with the rest of the code written in that
language.
Create a patch
To prepare your changes for submission, commit them to your
local branch while following the guidelines below.
The commit's subject (first line) should:
- Begin with an uppercase letter.
- Be written in the present tense.
- Not exceed 72 characters in length.
- Not end with a period.
-
Be prefixed with
Fix: if
the commit fixes a bug.
The commit message's body should be as detailed as possible and
explain the reasons behind the proposed change. You must mention
any related bug report at the end of the message with the
#123 format, where
123 is the bug number:
-
Use
Refs: #123
if the patch is related to bug 123, but does not
fix it yet.
-
Use
Fixes: #123
to indicate that this patch fixes the bug.
Make sure to sign-off your submitted
patches (the -s
argument to Git's commit
and format-patch
commands).
A patch must be as focused as possible. Do not, for instance,
fix a bug and correct the indentation of an unrelated block of code
as part of the same patch.
Here's a complete example:
Fix: use this instead of that in some context
Ball tip jowl beef ribs shankle, leberkas venison turducken tail pork
chop t-bone meatball tri-tip. Tongue beef ribs corned beef ball tip
kevin ground round sausage rump meatloaf pig meatball prosciutto
landjaeger strip steak. Pork pork belly beef.
Biltong turkey porchetta filet mignon corned beef. T-bone bresaola
shoulder meatloaf tongue kielbasa.
Fixes: #321
Refs: #456
Refs: #4972
Signed-off-by: Janine Sutto <jsutto@janine.su>
Submit a patch
LTTng's development flow is primarily based on
Gerrit Code Review,
although we also accept email-based patch series on the
lttng-dev mailing list,
and pull requests on our
GitHub mirrors.
The lttng-dev mailing list
is also used to share and comment on
RFCs and answer
questions.
To LTTng Review using git-review (preferred)
-
Sign-in to LTTng Review (Gerrit instance)
using your GitHub account and
add an SSH public key.
-
Install the git-review
plugin. The plugin is available through the package manager
of several Linux distributions including: Ubuntu, Debian,
Fedora, openSUSE, and Alpine.
-
In the checked-out repository, initialize the git-review state
by running git review -s.
-
Submit the changes by running git review.
Consult the git-review documentation
for more details about how the commands work, and the
Gerrit user documentation
to learn more about Gerrit.
-
When your submission is ready for review, you may add
the user project-maint as a reviewer.
project is the name of the project you are
submitting a change to.
For example:
lttng-tools-maintlttng-modules-maintlttng-ust-maint
To lttng-dev using email
-
Create one or more patch files corresponding
to your Git commits.
You can use Git's
format‑patch
command to generate a patch file.
For example, the following command line generates a patch from the
latest commit:
$
git format-patch -N1 -s --subject-prefix="PATCH project"
Replace project with one of:
lttng-toolslttng-ustlttng-modules-
babeltrace
(the Babeltrace
project uses the LTTng mailing list)
-
If your patch is for the LTTng-tools
project, run the checkpatch.pl
script on your patch file and correct any reported
errors:
$
extras/checkpatch.pl --no-tree 0001-Fix...patch
-
Send your patch to the LTTng
development mailing list.
You can use Git's
send‑email
command to do so:
$
git send-email --suppress-cc=self --to=lttng-dev@lists.lttng.org *.patch
Make sure you are
subscribed
to the mailing list to follow and take part in discussions about your
changes.
You can also join the file to an email as an
attachment if you can't send the patch directly
using git send‑email.
To GitHub
-
If you do not have one, create a GitHub account.
-
Fork
the project repository.
-
Push your locally submitted changes to a new branch in your
fork of the project repository.
-
Open a pull request.
Reviews
Once you have posted your patch to
LTTng Review,
the mailing list, or to another accepted platform, other
contributors may propose modifications to your patch.
This is completely normal. This collaborative code
review is an integral part of the open source
development process in general, and LTTng makes no
exception.
Keep in mind that reviewing patches is a time-consuming
process. Reviewers may not post comments right away. The
current release cycle phase and the complexity of the
proposed changes can affect the delays. If you think
that we might have forgotten your patch, please mention
it on the
#lttng IRC
channel rather than resubmitting.
Release cycle
The LTTng project follows a release cycle that
alternates between development and release candidate
(RC) phases. The master branch is feature-frozen during
RC phases; only bug fixes are accepted during this
period. However, patches which add new functionality during
an RC phase may still be reviewed on
Gerrit or the
mailing list.
