X-Git-Url: http://git.lttng.org./?a=blobdiff_plain;ds=inline;f=CONTRIBUTING.md;h=fbb48cd5ee145f11ceff31910ead598524d6f26c;hb=dcffe9462d11f9de5b441b801da5b2b7ae42c79a;hp=83fff57dd379f0e02482f604863c90ede64587a2;hpb=93794bcc34c3168d73ed17a372ad2ca63a2a0188;p=lttng-tools.git
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 83fff57dd..fbb48cd5e 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -15,47 +15,44 @@ control. The upstream Git repository URL is:
## Coding standard
-LTTng-tools uses the
-[Linux kernel coding style](http://www.kernel.org/doc/Documentation/CodingStyle)
-with one addition: single-line `if`/`for`/`while` statements must be
-wrapped in braces.
-
-Example:
-
-~~~ c
-/* not good */
-if (this == that)
- goto fail;
-
-/* good */
-if (this == that) {
- goto fail;
-}
-~~~
+See CodingStyle for guidelines style and design guidelines.
-Although the LTTng-tools code base is primarily written in C, it does
-contain shell, Perl, and Python code as well. There is no official coding
+Although the LTTng-tools code base is primarily written in C++, it does
+contain C, shell, and Python code as well. There is no official coding
standard for these languages. However, using a style consistent with the
rest of the code written in that language is strongly encouraged.
## Creating and sending a patch
-LTTng-tools's development flow is primarily email-based, although we
-also accept pull requests on our
-[GitHub mirror](https://github.com/lttng/lttng-tools). If you're going
-to create GitHub pull requests, make sure you still follow the
+LTTng-tools's development flow is primarily based on
+[Gerrit Code Review](https://review.lttng.org), although we also accept
+e-mail based patch series on the
+[`lttng-dev` mailing list](https://lists.lttng.org/cgi-bin/mailman/listinfo/lttng-dev)
+and pull requests on our [GitHub mirror](https://github.com/lttng/lttng-tools).
+If you're going to create GitHub pull requests, make sure you still follow the
guidelines below.
-Like a lot of open source projects, patches are submitted and reviewed
-on its development mailing list,
-[`lttng-dev`](http://lists.lttng.org/cgi-bin/mailman/listinfo/lttng-dev)
-(`lttng-dev@lists.lttng.org`). The mailing list is also used to share
-and comment on RFCs and answer
+The mailing list is also used to share and comment on
+RFCs and answer
user questions.
-Once your changes have been committed to your local branch, you may use
-Git's [`format-patch`](https://git-scm.com/docs/git-format-patch) command
+A template commit messsage is available below, and as a file that you may
+configure your local check out to use:
+
+ git config commit.template .commit_template
+
+Once your changes have been comitted to your local branch, you may use the
+[git-review](https://opendev.org/opendev/git-review) plugin to submit them
+directly to [Gerrit](https://review.lttng.org) using the following command:
+
+ git review
+
+Please note that you will need to create an account on [Gerrit](https://review.lttng.org)
+and add an SSH public key.
+
+For e-mail based patches you may use Git's
+[`format-patch`](https://git-scm.com/docs/git-format-patch) command
to generate a patch file. The following command line generates a
patch from the latest commit:
@@ -66,14 +63,39 @@ submitting patches that apply to the LTTng-tools project.
The patch's subject (the commit message's first line) should:
- * begin with an uppercase letter
- * be written in the present tense
- * _not_ exceed 72 characters in length
- * _not_ end with a period
- * be prefixed with `Fix:` if the commit fixes a bug
-
-The commit message's body should be as detailed as possible and explain
-the reasons behind the proposed change. Any related
+ * Begin with an uppercase letter.
+ * Be written in the present tense.
+ * _Not_ exceed 72 characters in length.
+ * _Not_ end with a period.
+
+In the case of bug fixes, the patch's subject must be prefixed with
+`Fix:` and a suitable sub-system name. For instance, a patch
+addressing a bug in the session daemon should start with `Fix:
+sessiond:`. Patches targeting shared code can either use the namespace
+of the interface or of the internal library, whichever is more
+precise.
+
+A non-exhaustive list of common sub-system prefixes follows:
+
+ * `relayd` (relay daemon).
+ * `sessiond` (session daemon).
+ * `lttng` (LTTng CLI client).
+ * `ust-consumerd` (user space consumer daemon).
+ * `kernel-consumerd` (kernel space consumer daemon).
+ * `consumerd` (common consumer daemon).
+ * `common` (internal `libcommon`).
+ * `trace-chunk` (internal `lttng_trace_chunk_*` interface).
+ * `lttng-ctl` (`liblttng-ctl` library).
+ * `mi` (LTTng client's machine interface).
+
+When possible, the commit title should describe the issue _as
+observed_ and not the underlying cause. For instance, prefer `Fix:
+sessiond: hang on SIGTERM after session rotation` to `Fix: sessiond:
+unchecked status on exit`.
+
+The commit message's body must be as detailed as possible and explain
+the reasons behind the proposed change. Keep in mind that this message
+will be read in a number of years and must still be clear. Any related
[bug report(s)](https://bugs.lttng.org/projects/lttng-tools/issues)
should be mentioned at the end of the message using the `#123` format,
where `123` is the bug number:
@@ -82,21 +104,64 @@ where `123` is the bug number:
fix it yet.
* Use `Fixes: #123` to signify that this patch fixes the bug.
+In the case of bug fixes, the following structure must be used:
+
+ * Observed issue
+ * Cause
+ * Solution
+ * **Optional**: Known drawbacks
+
+A short commit message can be used when submitting typo fixes or minor
+cleanups that don't introduce behaviour changes.
+
+When submitting a patch that affects existing code, implement changes
+to the existing code as prelude patches in a patch series. Explain why
+those changes are needed and how they make follow-up changes
+easier/possible.
+
Make sure to **sign-off** your submitted patches (the `-s` argument to
Git's `commit` and `format-patch` commands).
Here's a complete example:
~~~ text
-Fix: use this instead of that in some context
-
-Ball tip jowl beef ribs shankle, leberkas venison turducken tail pork
-chop t-bone meatball tri-tip. Tongue beef ribs corned beef ball tip
-kevin ground round sausage rump meatloaf pig meatball prosciutto
-landjaeger strip steak. Pork pork belly beef.
-
-Biltong turkey porchetta filet mignon corned beef. T-bone bresaola
-shoulder meatloaf tongue kielbasa.
+Fix: relayd: missing thingy in the doodad folder on error
+
+Observed issue
+==============
+After a communication error, the relay daemon will not produce
+a thingy in the doodad folder. This results in the knickknack
+baring the foo.
+
+Steps to reproduce (list of commands or narrative description).
+
+Cause
+=====
+The thingy_do_the_doodad() callback is only invoked when
+the thread responsible for receiving messages and dispatching
+them to the correct actors encounters an emoji.
+
+However, an emoji is not guaranteed to be present in the ELF
+section header [1].
+
+Solution
+========
+Flushing the doodad on every reception of a thingo ensures that
+the thingy is present in the doodad folder even if a communication
+error occurs.
+
+Known drawbacks
+===============
+Flushing the doodad too often may spam the widget and result in
+degradation of the gizmo. This doesn't matter right now since
+it happens exactly once per blue moon.
+
+If this becomes a serious issue, we could machine learn the MVP
+through the big O terminal.
+
+References
+==========
+[1] https://www.thedocs.com/elf/proving-my-point-unambiguously.aspx
Fixes: #321
Refs: #456