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). If you're going
  47 to create GitHub pull requests, make sure you still follow the
  48 guidelines below.
  49
  50 Like a lot of open source projects, patches are submitted and reviewed
  51 on its development mailing list,
  52 [`lttng-dev`](http://lists.lttng.org/cgi-bin/mailman/listinfo/lttng-dev)
  53 (`lttng-dev@lists.lttng.org`). The mailing list is also used to share
  54 and comment on <abbr title="Request for Comments">RFC</abbr>s and answer
  55 user questions.
  56
  57 Once your changes have been committed to your local branch, you may use
  58 Git's [`format-patch`](https://git-scm.com/docs/git-format-patch) command
  59 to generate a patch file. The following command line generates a
  60 patch from the latest commit:
  61
  62     git format-patch -N1 -s --subject-prefix="PATCH lttng-tools"
  63
  64 The custom `PATCH lttng-tools` subject prefix is mandatory when
  65 submitting patches that apply to the LTTng-tools project.
  66
  67 The patch's subject (the commit message's first line) should:
  68
  69   * begin with an uppercase letter
  70   * be written in the present tense
  71   * _not_ exceed 72 characters in length
  72   * _not_ end with a period
  73   * be prefixed with `Fix:` if the commit fixes a bug
  74
  75 The commit message's body should be as detailed as possible and explain
  76 the reasons behind the proposed change. Any related
  77 [bug report(s)](https://bugs.lttng.org/projects/lttng-tools/issues)
  78 should be mentioned at the end of the message using the `#123` format,
  79 where `123` is the bug number:
  80
  81   * Use `Refs: #123` if the patch is related to bug 123, but does not
  82     fix it yet.
  83   * Use `Fixes: #123` to signify that this patch fixes the bug.
  84
  85 Make sure to **sign-off** your submitted patches (the `-s` argument to
  86 Git's `commit` and `format-patch` commands).
  87
  88 Here's a complete example:
  89
  90 ~~~ text
  91 Fix: use this instead of that in some context
  92
  93 Ball tip jowl beef ribs shankle, leberkas venison turducken tail pork
  94 chop t-bone meatball tri-tip. Tongue beef ribs corned beef ball tip
  95 kevin ground round sausage rump meatloaf pig meatball prosciutto
  96 landjaeger strip steak. Pork pork belly beef.
  97
  98 Biltong turkey porchetta filet mignon corned beef. T-bone bresaola
  99 shoulder meatloaf tongue kielbasa.
 100
 101 Fixes: #321
 102 Refs: #456
 103 Refs: #1987
 104
 105 Signed-off-by: Jeanne Mance <jmeance@lttng.org>
 106 ~~~
 107
 108 Please note that patches should be **as focused as possible**. Do not,
 109 for instance, fix a bug and correct the indentation of an unrelated
 110 block of code as part of the same patch.
 111
 112 The project contains a script, [`extras/checkpatch.pl`](extras/checkpatch.pl),
 113 that performs a number of checks on a patch to ensure it is ready for
 114 submission. Run this script on your patch and correct any reported
 115 errors before posting it to the mailing list:
 116
 117     extras/checkpatch.pl --no-tree 0001-Fix...patch
 118
 119 Once you are confident your patch meets the required guidelines,
 120 you may use Git's [`send-email`](https://git-scm.com/docs/git-send-email)
 121 command to send your patch to the mailing list:
 122
 123     git send-email --suppress-cc=self --to lttng-dev@lists.lttng.org *.patch
 124
 125 Make sure you are
 126 [subscribed](http://lists.lttng.org/cgi-bin/mailman/listinfo/lttng-dev)
 127 to the mailing list to follow and take part in discussions about your
 128 changes. You may join the file to an email as an attachment if you can't
 129 send the patch directly using <code>git&nbsp;send&#8209;email</code>.
 130
 131
 132 ## Reviews
 133
 134 Once your patch has been posted to the mailing list or as a GitHub
 135 pull request, other contributors may propose modifications.
 136 This is completely normal. This collaborative code review is an integral
 137 part of the open source development process in general and LTTng-tools
 138 makes no exception.
 139
 140 Keep in mind that reviewing patches is a time-consuming process and,
 141 as such, may not be done right away. The delays may be affected by the
 142 current release cycle phase and the complexity of the proposed changes.
 143 If you think your patch might have been forgotten, please mention it on
 144 the [`#lttng`](irc://irc.oftc.net/lttng) IRC channel rather than
 145 resubmitting.
 146
 147
 148 ## Release cycle
 149
 150 The LTTng-tools project follows a release cycle that alternates between
 151 development and release candidate (RC) phases. The master branch is
 152 feature-frozen during RC phases: only bug fixes are accepted during
 153 this period. However, patches adding new functionality may still be
 154 submitted and reviewed during the RC. The upcoming features and release
 155 dates are posted in a monthly digest on the mailing list.