CONTRIBUTING.md

   1 <!--
   2 SPDX-FileCopyrightText: 2016 Philippe Proulx <pproulx@efficios.com>
   3
   4 SPDX-License-Identifier: CC-BY-4.0
   5 -->
   6
   7 # LTTng-UST contributor's guide
   8
   9 Being an open source project, the LTTng-UST project welcomes
  10 contributions from anyone. This guide walks you through the process
  11 of contributing a patch to LTTng-UST.
  12
  13
  14 ## Getting the source code
  15
  16 The LTTng-UST project uses [Git](https://git-scm.com/) for version
  17 control. The upstream Git repository URL is:
  18
  19     git://git.lttng.org/lttng-ust.git
  20
  21
  22 ## Coding standard
  23
  24 LTTng-UST uses the
  25 [Linux kernel coding style](https://www.kernel.org/doc/html/latest/process/coding-style.html).
  26
  27 Although the LTTng-UST code base is primarily written in C, it does
  28 contain shell, Perl, and Python code as well. There is no official coding
  29 standard for these languages. However, using a style consistent with the
  30 rest of the code written in that language is strongly encouraged.
  31
  32
  33 ## Creating and sending a patch
  34
  35 LTTng-UST's development flow is primarily based on
  36 [Gerrit Code Review](https://review.lttng.org/q/project:lttng-ust), although
  37 we also accept e-mail based patch series on the
  38 [`lttng-dev` mailing list](https://lists.lttng.org/cgi-bin/mailman/listinfo/lttng-dev)
  39 and pull requests on our [GitHub mirror](https://github.com/lttng/lttng-ust).
  40 If you're going to create GitHub pull requests, make sure you still follow the
  41 guidelines below.
  42
  43 The mailing list is also used to share and comment on
  44 <abbr title="Request for Comments">RFC</abbr>s and answer
  45 user questions.
  46
  47 Once your changes have been comitted to your local branch, you may use the
  48 [git-review](https://opendev.org/opendev/git-review) plugin to submit them
  49 dirrectly to [Gerrit](https://review.lttng.org) using the following command:
  50
  51     git review
  52
  53 Please note that you will need to create an account on [Gerrit](https://review.lttng.org)
  54 and add an SSH public key.
  55
  56 For e-mail based patches you may use Git's
  57 [`format-patch`](https://git-scm.com/docs/git-format-patch) command
  58 to generate a patch file. The following command line generates a
  59 patch from the latest commit:
  60
  61     git format-patch -N1 -s --subject-prefix="PATCH lttng-ust"
  62
  63 The custom `PATCH lttng-ust` subject prefix is mandatory when
  64 submitting patches that apply to the LTTng-UST project.
  65
  66 The patch's subject (the commit message's first line) should:
  67
  68   * begin with an uppercase letter
  69   * be written in the present tense
  70   * _not_ exceed 72 characters in length
  71   * _not_ end with a period
  72   * be prefixed with `Fix:` if the commit fixes a bug
  73
  74 The commit message's body should be as detailed as possible and explain
  75 the reasons behind the proposed change. Any related
  76 [bug report(s)](https://bugs.lttng.org/projects/lttng-ust/issues)
  77 should be mentioned at the end of the message using the `#123` format,
  78 where `123` is the bug number:
  79
  80   * Use `Refs: #123` if the patch is related to bug 123, but does not
  81     fix it yet.
  82   * Use `Fixes: #123` to signify that this patch fixes the bug.
  83
  84 Make sure to **sign-off** your submitted patches (the `-s` argument to
  85 Git's `commit` and `format-patch` commands).
  86
  87 Here's a complete example:
  88
  89 ~~~ text
  90 Fix: use this instead of that in some context
  91
  92 Ball tip jowl beef ribs shankle, leberkas venison turducken tail pork
  93 chop t-bone meatball tri-tip. Tongue beef ribs corned beef ball tip
  94 kevin ground round sausage rump meatloaf pig meatball prosciutto
  95 landjaeger strip steak. Pork pork belly beef.
  96
  97 Biltong turkey porchetta filet mignon corned beef. T-bone bresaola
  98 shoulder meatloaf tongue kielbasa.
  99
 100 Fixes: #321
 101 Refs: #456
 102 Refs: #1987
 103
 104 Signed-off-by: Jeanne Mance <jmeance@lttng.org>
 105 ~~~
 106
 107 Please note that patches should be **as focused as possible**. Do not,
 108 for instance, fix a bug and correct the indentation of an unrelated
 109 block of code as part of the same patch.
 110
 111 Once you are confident your patch meets the required guidelines,
 112 you may use Git's [`send-email`](https://git-scm.com/docs/git-send-email)
 113 command to send your patch to the mailing list:
 114
 115     git send-email --suppress-cc=self --to lttng-dev@lists.lttng.org *.patch
 116
 117 Make sure you are
 118 [subscribed](http://lists.lttng.org/cgi-bin/mailman/listinfo/lttng-dev)
 119 to the mailing list to follow and take part in discussions about your
 120 changes. You may join the file to an email as an attachment if you can't
 121 send the patch directly using <code>git&nbsp;send&#8209;email</code>.
 122
 123
 124 ## Reviews
 125
 126 Once your patch has been posted to the mailing list or as a GitHub
 127 pull request, other contributors may propose modifications.
 128 This is completely normal. This collaborative code review is an integral
 129 part of the open source development process in general and LTTng-UST
 130 makes no exception.
 131
 132 Keep in mind that reviewing patches is a time-consuming process and,
 133 as such, may not be done right away. The delays may be affected by the
 134 current release cycle phase and the complexity of the proposed changes.
 135 If you think your patch might have been forgotten, please mention it on
 136 the [`#lttng`](irc://irc.oftc.net/lttng) IRC channel rather than
 137 resubmitting.
 138
 139
 140 ## Release cycle
 141
 142 The LTTng-UST project follows a release cycle that alternates between
 143 development and release candidate (RC) phases. The master branch is
 144 feature-frozen during RC phases: only bug fixes are accepted during
 145 this period. However, patches adding new functionality may still be
 146 submitted and reviewed during the RC. The upcoming features and release
 147 dates are posted in a monthly digest on the mailing list.