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