You are here

Contribution Guidelines

All IoTivity code contributions go through peer review in IoTivity’s Gerrit server. Contributions must be properly formatted and follow IoTivity’s coding style and coding policies.

Commit messages

Commit messages are an important part of the project documentation. When writing a commit message, provide a clear explanation of why a change was made so that others or your future self can later review what happened and why it happened.

Commit message format:

  • Header line: explain the commit in one line, as an imperative sentence.

  • Body: a few lines of text explaining things in more detail, possibly giving some background about the issue being fixed, etc.

  • Footers: all commits must contain the Signed-off-by and the Change-Id lines, or the Gerrit server will reject the submission. Other footer lines are accepted and the order of those lines is not important.

    Reported-by: whoever-reported-it
    Signed-off-by: Your Name <youremail@yourhost.com>
    Change-Id: Ida39a3ee5e6b4b0d3255bfef95601890afd80709

  • Developer certificate of origin: the Signed-off-by line is your signature, indicating that you agree to abide by the terms of the developer certificate of origin.

Developer Certificate of Origin

Version 1.1
Copyright (C) 2004, 2006 The Linux Foundation and its contributors.

660 York Street, Suite 102
San Francisco, CA 94110 USA

Everyone is permitted to copy and distribute verbatim copies of this license document, but changing it is not allowed.

Developer’s Certificate of Origin 1.1

By making a contribution to this project, I certify that:

  1. The contribution was created in whole or in part by me and I have the right to submit it under the open source license indicated in the file; or
  2. The contribution is based upon previous work that, to the best of my knowledge, is covered under an appropriate open source license and I have the right under that license to submit that work with modifications, whether created in whole or in part by me, under the same open source license (unless I am permitted to submit under a different license), as indicated in the file; or
  3. The contribution was provided directly to me by some other person who certified (a), (b) or (c) and I have not modified it.
  4. I understand and agree that this project and the contribution are public and that a record of the contribution (including all personal information I submit with it, including my sign-off) is maintained indefinitely and may be redistributed consistent with this project or the open source license(s) involved.

The body of the commit message can be several paragraphs. Use proper word-wrap and keep columns shorter than about 74 characters so the “git log” will display the information cleanly. Make sure you explain your solution and why you’re doing what you’re doing, as opposed to describing what you’re doing.

Multiple Signed-off-by lines are possible. They are required if the patch was created by a Contributor other than the one submitting the commit to Gerrit. If the patch was received and re-sent by multiple people, each person is expected to add their signature.

The Change-Id line uniquely identifies each commit during the review process. It is necessary because the Git commit ID is a SHA-1 hash calculated according to the contents of the commit which will change as the commit is updated to fix issues found in the review process. See the Gerrit documentation for more information.

Install the Gerrit commit-msg hook script in your Git clone to create the Change-Id line automatically. From the root of that repository, run one of:

$ curl -Lo .git/hooks/commit-msg http://gerrit.iotivity.org/tools/hooks/commit-msg
$ scp -p -P 29418 john.doe@gerrit.iotivity.org:hooks/commit-msg .git/hooks/

Then ensure that the execute bit is set on the hook script:

$ chmod u+x .git/hooks/commit-msg

Review process

Every IoTivity Contributor is allowed to participate in the review of anyone else’s commits. Contributors are immediately given the rights to propose a +1 review, indicating that the contribution looks correct, or -1, indicating that it needs more work and should not be accepted in its current state.

A three-stage approach is recommended, especially for Contributors providing their first contributions:

  1. Is the idea behind the contribution sound?

  2. Is the contribution architected correctly?

  3. Is the contribution polished?

That is, review initially whether the overall picture is correctly addressed, whether the type of implementation is correct, whether this type of solution aligns with IoTivity goals, etc. At this stage, it’s more important to provide a subjective and qualitative review (“spirit fit” with the project goals).

Next, review the implementation itself to determine if it has been correctly written and if the implementation is actually doing what the author proposed. This stage is for quantitative and objective review and to determine if the major requirements of the contribution guidelines are met (for example, if a unit test is required, whether it is present or not). This is a “technical fit” with the project goals.

Finally, review whether the contribution meets the overall guidelines for contribution, such as coding style, organization of the code, naming of variables and functions, etc. This is the “nitpick” stage and many contributors start with this, putting off possible newcomers with an avalanche of minutiae. While necessary before the contribution can be accepted, this can usually be postponed until the final stages.

For more details and the rationale behind this phased approach, see this blog post.

Contribution approval

All Contributors can give the Gerrit review votes of +1 and -1, but only Maintainers and delegated sub-Maintainers are given the right and responsibility of voting +2 (approved) and -2 (declined, at least for now).

Maintainers have the responsibility of ensuring that all contributions have either an approval mark (the +2), a temporary or permanent rejection (the -2) or that feedback is given on where to improve (often a -1 review). Whenever approval is withheld, the Maintainer must justify the review on technical grounds.