X-Git-Url: https://git.liburcu.org/?p=lttng-tools.git;a=blobdiff_plain;f=CONTRIBUTING.md;h=6873d78109b05927ed17de73cce8d335389b601a;hp=83fff57dd379f0e02482f604863c90ede64587a2;hb=HEAD;hpb=93794bcc34c3168d73ed17a372ad2ca63a2a0188 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