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

[Christian Babeux]

Looks good to me!

Perhaps we could add a section about guidelines to add tests?

Thanks,

Christian

On Mon, Aug 26, 2013 at 1:39 PM, Jérémie Galarneau
<jeremie.galarneau at efficios.com> wrote:
> 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.
>
> 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
>
> --
> Jérémie Galarneau
> EfficiOS Inc.
> http://www.efficios.com
>
> _______________________________________________
> lttng-dev mailing list
> lttng-dev at lists.lttng.org
> http://lists.lttng.org/cgi-bin/mailman/listinfo/lttng-dev