Clean-up: sessiond: remove some declarations from lttng-sessiond.h
[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
a7a35430
JG
46[GitHub mirror](https://github.com/lttng/lttng-tools) and
47[Gerrit Code Review](https://review.lttng.org). If you're going
93794bcc
PP
48to create GitHub pull requests, make sure you still follow the
49guidelines below.
50
51Like a lot of open source projects, patches are submitted and reviewed
52on its development mailing list,
53[`lttng-dev`](http://lists.lttng.org/cgi-bin/mailman/listinfo/lttng-dev)
54(`lttng-dev@lists.lttng.org`). The mailing list is also used to share
55and comment on <abbr title="Request for Comments">RFC</abbr>s and answer
56user questions.
57
58Once your changes have been committed to your local branch, you may use
59Git's [`format-patch`](https://git-scm.com/docs/git-format-patch) command
60to generate a patch file. The following command line generates a
61patch from the latest commit:
62
63 git format-patch -N1 -s --subject-prefix="PATCH lttng-tools"
64
65The custom `PATCH lttng-tools` subject prefix is mandatory when
66submitting patches that apply to the LTTng-tools project.
67
68The patch's subject (the commit message's first line) should:
69
20095472
JG
70 * Begin with an uppercase letter.
71 * Be written in the present tense.
72 * _Not_ exceed 72 characters in length.
73 * _Not_ end with a period.
93794bcc 74
a7a35430
JG
75In the case of bug fixes, the patch's subject must be prefixed with
76`Fix:` and a suitable sub-system name. For instance, a patch
77addressing a bug in the session daemon should start with `Fix:
78sessiond:`. Patches targeting shared code can either use the namespace
79of the interface or of the internal library, whichever is more
80precise.
81
82A non-exhaustive list of common sub-system prefixes follows:
83
84 * `relayd` (relay daemon).
85 * `sessiond` (session daemon).
86 * `lttng` (LTTng CLI client).
87 * `ust-consumerd` (user space consumer daemon).
88 * `kernel-consumerd` (kernel space consumer daemon).
89 * `consumerd` (common consumer daemon).
90 * `common` (internal `libcommon`).
91 * `trace-chunk` (internal `lttng_trace_chunk_*` interface).
92 * `lttng-ctl` (`liblttng-ctl` library).
93 * `mi` (LTTng client's machine interface).
94
95When possible, the commit title should describe the issue _as
96observed_ and not the underlying cause. For instance, prefer `Fix:
97sessiond: hang on SIGTERM after session rotation` to `Fix: sessiond:
98unchecked status on exit`.
99
100The commit message's body must be as detailed as possible and explain
101the reasons behind the proposed change. Keep in mind that this message
102will be read in a number of years and must still be clear. Any related
93794bcc
PP
103[bug report(s)](https://bugs.lttng.org/projects/lttng-tools/issues)
104should be mentioned at the end of the message using the `#123` format,
105where `123` is the bug number:
106
107 * Use `Refs: #123` if the patch is related to bug 123, but does not
108 fix it yet.
109 * Use `Fixes: #123` to signify that this patch fixes the bug.
110
a7a35430
JG
111In the case of bug fixes, the following structure must be used:
112
113 * Observed issue
114 * Cause
115 * Solution
116 * **Optional**: Known drawbacks
117
118A short commit message can be used when submitting typo fixes or minor
119cleanups that don't introduce behaviour changes.
120
121When submitting a patch that affects existing code, implement changes
122to the existing code as prelude patches in a patch series. Explain why
123those changes are needed and how they make follow-up changes
124easier/possible.
125
93794bcc
PP
126Make sure to **sign-off** your submitted patches (the `-s` argument to
127Git's `commit` and `format-patch` commands).
128
129Here's a complete example:
130
131~~~ text
a7a35430
JG
132Fix: relayd: missing thingy in the doodad folder on error
133
134Observed issue
135==============
136After a communication error, the relay daemon will not produce
137a thingy in the doodad folder. This results in the knickknack
138baring the foo.
139
140Steps to reproduce (list of commands or narrative description).
141
142Cause
143=====
144The thingy_do_the_doodad() callback is only invoked when
145the thread responsible for receiving messages and dispatching
146them to the correct actors encounters an emoji.
147
148However, an emoji is not guaranteed to be present in the ELF
149section header [1].
150
151Solution
152========
153Flushing the doodad on every reception of a thingo ensures that
154the thingy is present in the doodad folder even if a communication
155error occurs.
156
157Known drawbacks
158===============
159Flushing the doodad too often may spam the widget and result in
160degradation of the gizmo. This doesn't matter right now since
161it happens exactly once per blue moon.
162
163If this becomes a serious issue, we could machine learn the MVP
164through the big O terminal.
165
166References
167==========
168[1] https://www.thedocs.com/elf/proving-my-point-unambiguously.aspx
93794bcc
PP
169
170Fixes: #321
171Refs: #456
172Refs: #1987
173
174Signed-off-by: Jeanne Mance <jmeance@lttng.org>
175~~~
176
177Please note that patches should be **as focused as possible**. Do not,
178for instance, fix a bug and correct the indentation of an unrelated
179block of code as part of the same patch.
180
181The project contains a script, [`extras/checkpatch.pl`](extras/checkpatch.pl),
182that performs a number of checks on a patch to ensure it is ready for
183submission. Run this script on your patch and correct any reported
184errors before posting it to the mailing list:
185
186 extras/checkpatch.pl --no-tree 0001-Fix...patch
187
188Once you are confident your patch meets the required guidelines,
189you may use Git's [`send-email`](https://git-scm.com/docs/git-send-email)
190command to send your patch to the mailing list:
191
192 git send-email --suppress-cc=self --to lttng-dev@lists.lttng.org *.patch
193
194Make sure you are
195[subscribed](http://lists.lttng.org/cgi-bin/mailman/listinfo/lttng-dev)
196to the mailing list to follow and take part in discussions about your
197changes. You may join the file to an email as an attachment if you can't
198send the patch directly using <code>git&nbsp;send&#8209;email</code>.
199
200
201## Reviews
202
203Once your patch has been posted to the mailing list or as a GitHub
204pull request, other contributors may propose modifications.
205This is completely normal. This collaborative code review is an integral
206part of the open source development process in general and LTTng-tools
207makes no exception.
208
209Keep in mind that reviewing patches is a time-consuming process and,
210as such, may not be done right away. The delays may be affected by the
211current release cycle phase and the complexity of the proposed changes.
212If you think your patch might have been forgotten, please mention it on
213the [`#lttng`](irc://irc.oftc.net/lttng) IRC channel rather than
214resubmitting.
215
216
217## Release cycle
218
219The LTTng-tools project follows a release cycle that alternates between
220development and release candidate (RC) phases. The master branch is
221feature-frozen during RC phases: only bug fixes are accepted during
222this period. However, patches adding new functionality may still be
223submitted and reviewed during the RC. The upcoming features and release
224dates are posted in a monthly digest on the mailing list.
This page took 0.053124 seconds and 4 git commands to generate.