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