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