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