Contribute

Contributions to OP-TEE are managed by the OP-TEE Core Team and anyone can contribute to OP-TEE as long as it is understood that it will require a Signed-off-by tag from the one submitting the patch(es). The Signed-off-by tag is a simple line at the end of the explanation for the patch, which certifies that you wrote it or otherwise have the right to pass it on as an open source patch (see below). You thereby assure that you have read and are following the rules stated in the Developer Certificate of Origin as stated below.

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:

(a) 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

(b) 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

(c) The contribution was provided directly to me by some other
    person who certified (a), (b) or (c) and I have not modified
    it.

(d) 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.

We have borrowed this procedure from the Linux kernel project to improve tracking of who did what, and for legal reasons.

To sign-off a patch, just add a line in the commit message saying:

Signed-off-by: Random J Developer <random@developer.example.org>

Use your real name or on some rare cases a company email address, but we disallow pseudonyms or anonymous contributions.

GitHub

This section describes how to use GitHub for OP-TEE development and contributions.

Setting up an account

You do not need to own a GitHub account in order to clone a repository. But if you want to contribute, you need to create an account at GitHub. Note that a free plan is sufficient to collaborate.

SSH is recommended to access your GitHub repositories securely and without supplying your username and password each time you pull or push something. To configure SSH for GitHub, please refer to Connecting to GitHub with SSH.

Forking

Only owners of the OP-TEE projects have write permissions to the git repositories of those projects. Contributors should fork OP-TEE/*.git and/or linaro-swg/*.git into their own account, then work on this forked repository. The complete documentation about forking can be found at fork a repo.

Creating pull requests

When you want to submit a patch to the OP-TEE project, you are supposed to create a pull request to the git where you forked your git from. How that is done using GitHub is explained at the GitHub pull request page.

Commit messages

  • The subject line should explain what the patch does as precisely as possible. It is usually prefixed with keywords indicating which part of the code is affected, but not always. Avoid lines longer than 80 characters.

  • The commit description should give more details on what is changed, and explain why it is done. Indication on how to enable and use some particular feature can be useful, too. Try to limit line length to 72 characters, except when pasting some error message (compiler diagnostic etc.). Long lines are allowed to accommodate URLs, too (preferably use URLs in a Fixes: or Link: tag).

  • The commit message must end with a blank line followed by some tags, including your Signed-off-by: tag. By applying such a tag to your commit, you are effectively declaring that your contribution follows the terms stated by Developer Certificate of Origin (in the DCO section there is also a complete example).

  • Other tags may be used, such as:

    • Tested-by: Test R <test@r.com>
    • Acked-by: Acke R <acke@r.com>
    • Suggested-by: Suggeste R <suggeste@r.com>
    • Reported-by: Reporte R <reporte@r.com>
  • When citing a previous commit, whether it is in the text body or in a Fixes: tag, always use the format shown above (12 hexadecimal digits prefix of the commit SHA1, followed by the commit subject in double quotes and parentheses).

Review feedback

It is very likely that you will get review comments from other OP-TEE users asking you to fix certain things etc. When fixing review comments, do:

  • Add fixup patches on top of your existing branch. Do not squash and force push while fixing review comments.
  • When all comments have been addressed, just write a simple messages in the comments field saying something like “All comments have been addressed”. By doing so you will notify the maintainers that the fix might be ready for review again.

Finalizing your contribution

Once you and reviewers have agreed on the patch set, which is when all the people who have commented on the pull request have given their Acked-by: or Reviewed-by:, you need to consolidate your commits:

Use git rebase -i to squash the fixup commits (if any) into the initial ones. For instance, suppose the git log --oneline for you contribution looks as follows when the review process ends:

<sha1-commit4> [Review] Do something
<sha1-commit3> [Review] Do something
<sha1-commit2> Do something else
<sha1-commit1> Do something

Then you would do:

$ git rebase -i <sha1-commit1>^

Edit the commit script so it looks like so:

pick <sha1-commit1> Do something
squash <sha1-commit3> [Review] Do something
squash <sha1-commit4> [Review] Do something
pick <sha1-commit2> Do something else

Add the proper tags (Acked-by: ..., Reviewed-by: ..., Tested-by: ...) to the commit message(s) for each and every commit as provided by the people who reviewed and/or tested the patches.

Hint

git commit --fixup=<sha1-of-commit-to-fix> and later on git rebase -i --autosquash <sha1-of-first-commit-in-patch-serie>^1 is pretty convenient to use when adding review patches and doing the final squash operation.

Once rebase -i is done, you need to force-push (-f) to your GitHub branch in order to update the pull request page.

$ git push -f <my-remote> <my-branch>

After completing this it is the project maintainers job to apply your patches to the master branch.