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.