Add CONTRIBUTING.md
[lttng-tools.git] / CONTRIBUTING.md
CommitLineData
93794bcc
PP
1# LTTng-tools contributor's guide
2
3Being an open source project, the LTTng-tools project welcomes
4contributions from anyone. This guide walks you through the process
5of contributing a patch to LTTng-tools.
6
7
8## Getting the source code
9
10The LTTng-tools project uses [Git](https://git-scm.com/) for version
11control. The upstream Git repository URL is:
12
13 git://git.lttng.org/lttng-tools.git
14
15
16## Coding standard
17
18LTTng-tools uses the
19[Linux kernel coding style](http://www.kernel.org/doc/Documentation/CodingStyle)
20with one addition: single-line `if`/`for`/`while` statements must be
21wrapped in braces.
22
23Example:
24
25~~~ c
26/* not good */
27if (this == that)
28 goto fail;
29
30/* good */
31if (this == that) {
32 goto fail;
33}
34~~~
35
36Although the LTTng-tools code base is primarily written in C, it does
37contain shell, Perl, and Python code as well. There is no official coding
38standard for these languages. However, using a style consistent with the
39rest of the code written in that language is strongly encouraged.
40
41
42## Creating and sending a patch
43
44LTTng-tools's development flow is primarily email-based, although we
45also accept pull requests on our
46[GitHub mirror](https://github.com/lttng/lttng-tools). If you're going
47to create GitHub pull requests, make sure you still follow the
48guidelines below.
49
50Like a lot of open source projects, patches are submitted and reviewed
51on its development mailing list,
52[`lttng-dev`](http://lists.lttng.org/cgi-bin/mailman/listinfo/lttng-dev)
53(`lttng-dev@lists.lttng.org`). The mailing list is also used to share
54and comment on <abbr title="Request for Comments">RFC</abbr>s and answer
55user questions.
56
57Once your changes have been committed to your local branch, you may use
58Git's [`format-patch`](https://git-scm.com/docs/git-format-patch) command
59to generate a patch file. The following command line generates a
60patch from the latest commit:
61
62 git format-patch -N1 -s --subject-prefix="PATCH lttng-tools"
63
64The custom `PATCH lttng-tools` subject prefix is mandatory when
65submitting patches that apply to the LTTng-tools project.
66
67The patch's subject (the commit message's first line) should:
68
69 * begin with an uppercase letter
70 * be written in the present tense
71 * _not_ exceed 72 characters in length
72 * _not_ end with a period
73 * be prefixed with `Fix:` if the commit fixes a bug
74
75The commit message's body should be as detailed as possible and explain
76the reasons behind the proposed change. Any related
77[bug report(s)](https://bugs.lttng.org/projects/lttng-tools/issues)
78should be mentioned at the end of the message using the `#123` format,
79where `123` is the bug number:
80
81 * Use `Refs: #123` if the patch is related to bug 123, but does not
82 fix it yet.
83 * Use `Fixes: #123` to signify that this patch fixes the bug.
84
85Make sure to **sign-off** your submitted patches (the `-s` argument to
86Git's `commit` and `format-patch` commands).
87
88Here's a complete example:
89
90~~~ text
91Fix: use this instead of that in some context
92
93Ball tip jowl beef ribs shankle, leberkas venison turducken tail pork
94chop t-bone meatball tri-tip. Tongue beef ribs corned beef ball tip
95kevin ground round sausage rump meatloaf pig meatball prosciutto
96landjaeger strip steak. Pork pork belly beef.
97
98Biltong turkey porchetta filet mignon corned beef. T-bone bresaola
99shoulder meatloaf tongue kielbasa.
100
101Fixes: #321
102Refs: #456
103Refs: #1987
104
105Signed-off-by: Jeanne Mance <jmeance@lttng.org>
106~~~
107
108Please note that patches should be **as focused as possible**. Do not,
109for instance, fix a bug and correct the indentation of an unrelated
110block of code as part of the same patch.
111
112The project contains a script, [`extras/checkpatch.pl`](extras/checkpatch.pl),
113that performs a number of checks on a patch to ensure it is ready for
114submission. Run this script on your patch and correct any reported
115errors before posting it to the mailing list:
116
117 extras/checkpatch.pl --no-tree 0001-Fix...patch
118
119Once you are confident your patch meets the required guidelines,
120you may use Git's [`send-email`](https://git-scm.com/docs/git-send-email)
121command to send your patch to the mailing list:
122
123 git send-email --suppress-cc=self --to lttng-dev@lists.lttng.org *.patch
124
125Make sure you are
126[subscribed](http://lists.lttng.org/cgi-bin/mailman/listinfo/lttng-dev)
127to the mailing list to follow and take part in discussions about your
128changes. You may join the file to an email as an attachment if you can't
129send the patch directly using <code>git&nbsp;send&#8209;email</code>.
130
131
132## Reviews
133
134Once your patch has been posted to the mailing list or as a GitHub
135pull request, other contributors may propose modifications.
136This is completely normal. This collaborative code review is an integral
137part of the open source development process in general and LTTng-tools
138makes no exception.
139
140Keep in mind that reviewing patches is a time-consuming process and,
141as such, may not be done right away. The delays may be affected by the
142current release cycle phase and the complexity of the proposed changes.
143If you think your patch might have been forgotten, please mention it on
144the [`#lttng`](irc://irc.oftc.net/lttng) IRC channel rather than
145resubmitting.
146
147
148## Release cycle
149
150The LTTng-tools project follows a release cycle that alternates between
151development and release candidate (RC) phases. The master branch is
152feature-frozen during RC phases: only bug fixes are accepted during
153this period. However, patches adding new functionality may still be
154submitted and reviewed during the RC. The upcoming features and release
155dates are posted in a monthly digest on the mailing list.
This page took 0.039799 seconds and 4 git commands to generate.