general/contribute.rst - OP-TEE/optee_docs - TrustedFirmware Git Browser

 .. _contribute:

 ##########
 Contribute
 ##########
 Contributions to OP-TEE are managed by the OP-TEE :ref:`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.

 .. _DCO:

 Developer Certificate of Origin
 *******************************

 .. code-block:: none

     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:

 .. code-block:: none

     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 :ref:`DCO` (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:

 .. code-block:: none

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

 Then you would do:

 .. code-block:: bash

     $ git rebase -i <sha1-commit1>^

 Edit the commit script so it looks like so:

 .. code-block:: none

     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.

 .. code-block:: bash

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

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

 .. _fork a repo: https://help.github.com/articles/fork-a-repo
 .. _GitHub: https://github.com
 .. _Connecting to GitHub with SSH: https://help.github.com/articles/connecting-to-github-with-ssh
 .. _pull request: https://help.github.com/articles/creating-a-pull-request
	.. _contribute:

	##########
	Contribute
	##########
	Contributions to OP-TEE are managed by the OP-TEE :ref:`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.

	.. _DCO:

	Developer Certificate of Origin
	*******************************

	.. code-block:: none

	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:

	.. code-block:: none

	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 :ref:`DCO` (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:

	.. code-block:: none

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

	Then you would do:

	.. code-block:: bash

	$ git rebase -i <sha1-commit1>^

	Edit the commit script so it looks like so:

	.. code-block:: none

	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.

	.. code-block:: bash

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

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

	.. _fork a repo: https://help.github.com/articles/fork-a-repo
	.. _GitHub: https://github.com
	.. _Connecting to GitHub with SSH: https://help.github.com/articles/connecting-to-github-with-ssh
	.. _pull request: https://help.github.com/articles/creating-a-pull-request