[lttng-dev] [RFC] LTTng Contributor's guide

[David Goulet]

Jérémie Galarneau:
> Hi,
> 
> There was some talk on the IRC channel last week about the need for a
> contributor's guide. I have worked on a quick first draft which you
> may find below. Ideally, this would be posted on the LTTng website.
> 
> Feedback would be greatly appreciated.
> 
> Thanks,
> Jérémie
> 
> 
> *** Contributor's guide ***
> 
> Being an open source project, the LTTng project welcomes contributions
> from everyone.
> This guide will walk you through the process of contributing a patch to LTTng.
> 
> Getting the source code
> -----------------------
> 
> The LTTng project uses Git for source control. How to use Git is
> beyond the scope of this guide, but its official website[1] provides
> many great tutorials.
> Please refer to the download[2] page for links to LTTng's Git repositories.
> 
> Fixes and features should generally be developed against the master
> branch. If you intend on submitting a patch that addresses an issue in
> a specific stable branch or a development branch, make sure you
> mention it in the commit's description or the subject prefix.
> 
> Coding standard
> -------------
> 
> LTTng uses the Linux kernel coding style[3] with one addition: single
> line if-statements must be wrapped in braces.
> 
> Although the LTTng code base is primarily written in C, it does
> contain Perl, Python and Java code. There are no official coding
> standards for these languages. However, using a style consistent with
> the rest of the code written in that language is strongly encouraged.

Hmmm, for lttng-tools there is a CodingStyle file in the source repository that
should be used that includes more than just the if-statement wrapping.

Thanks
David

> 
> Creating and sending a patch
> -------------
> 
> LTTng's development flow is primarily e-mail based. Like a lot of open
> source projects, patches are submitted and reviewed on the project's
> mailing list (lttng-dev at lists.lttng.org). This list is also used to
> share and comment on RFCs and answer users' questions.
> 
> To make patch management and reviews as painless as possible, we
> encourage contributors to follow a uniform patch submission process.
> 
> Once your changes have been committed to your local branch, use Git's
> format-patch command to generate a patch file. The following command
> line will generate a patch from the latest commit: git format-patch
> -N1 -s --subject-prefix="PATCH project_name"
> 
> The patch's subject (the commit message's first line) should be
> written in the present tense and not exceed 72 characters in length.
> 
> The commit message's body should be as detailed as possible and
> explain the reasons behind the proposed change. Any related bug
> report(s) should be mentioned at the end of the message.
> 
> The lttng-tools project provides a script (checkpatch.pl) as part of
> the "extras" that performs a number of checks on a patch to ensure it
> is ready for submission. Run this script on your patch and correct any
> reported errors before posting it to the mailing list.
> 
> You may find an example of a patch suitable for submission here[4].
> 
> Note that patches should 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.
> 
> Once you are confident your patch meets the required guide lines, you
> may use Git's send-email command to send your patch on the mailing
> list. Make sure you are subscribed[5] to the mailing list to follow
> and take part in discussions about your changes.
> 
> You may join the file to an e-mail as an attachment if you can't send
> the patch directly using send-email.
> 
> Reviews
> -------------
> 
> Once your patch has been posted to the mailing list, other
> contributors may propose modifications to your patch. This is
> completely normal. This collaborative code review is an integral part
> of our development process.
> 
> Keep in mind that reviewing patches is a time-consuming process and,
> as such, may not be done right away. The delays may be affected by the
> current release cycle phase and the complexity of the proposed
> changes. If you think your patch might have been forgotten, please
> mention it on the #lttng[6] 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 will be accepted
> during this period. However, patches adding new functionality may
> still be submitted and reviewed during the RC.
> The upcoming features and release dates are announced in a monthly
> digest posted on the mailing list.
> 
> 
> [1] http://git-scm.com
> [2] http://lttng.org/download
> [3] http://www.kernel.org/doc/Documentation/CodingStyle
> [4] http://lists.lttng.org/pipermail/lttng-dev/2013-June/020574.html
> [5] http://lists.lttng.org/cgi-bin/mailman/listinfo/lttng-dev
> [6] irc://irc.oftc.net/lttng
>