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