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