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

[Mathieu Desnoyers]

* 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.

It looks great ! A couple of minor comments below,

> 
> 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.

We should also point out that patches should focus on a single "logical"
change at a time. The basic questions to think about whenever choosing
how to split changes into separate patches is:
- making sure that each patch build on its own (bissectability),
- if the feature needs to be reverted, only the feature should be
  taken away by a git revert. Not, e.g., cleanups, nor unrelated
  fixes.

We might also want to point out a set of testing guide lines before
submitting. e.g.

build
make check

and also VPATH build, as well as make dist testing if the patch touches
automake files (for instance).

> 
> 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.

We should point out that when a feature patch submitted for review
(during a rc) is considered acceptable, the

Acked-by

tag will be given by maintainers. It should be added to the patch
changelog for resubmission. However, if the patch needs to be changed
compared to the ack'd version when resubmitted at the end of the release
candidate cycle, the acked-by tag should be removed, and a description
of the changes since the acked version should be written in the
changelog.

Thanks,

Mathieu

> 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

-- 
Mathieu Desnoyers
EfficiOS Inc.
http://www.efficios.com