CONTRIBUTING.rst - third_party/github/zephyrproject-rtos/zephyr - Git at Google

 Contribution Guidelines
 #######################

 As an open-source project, we welcome and encourage the community to submit
 patches directly to the project.  In our collaborative open source environment,
 standards and methods for submitting changes help reduce the chaos that can result
 from an active development community.

 This document explains how to participate in project conversations, log bugs
 and enhancement requests, and submit patches to the project so your patch will
 be accepted quickly in the codebase.


 Licensing
 *********

 Licensing is very important to open source projects. It helps ensure the
 software continues to be available under the terms that the author desired.

 .. _Apache 2.0 license:
    https://github.com/zephyrproject-rtos/zephyr/blob/master/LICENSE

 .. _GitHub repo: https://github.com/zephyrproject-rtos/zephyr

 Zephyr uses the `Apache 2.0 license`_ (as found in the LICENSE file in
 the project's `GitHub repo`_) to strike a balance between open
 contribution and allowing you to use the software however you would like
 to.  The Apache 2.0 license is a permisive open source license that
 allows you to freely use, modify, distribute and sell your own products
 that include Apache 2.0 licensed software.  (For more information about
 this, check out articles such as `Why choose Apache 2.0 licensing`_ and
 `Top 10 Apache License Questions Answered`_).

 .. _Why choose Apache 2.0 licensing:
    https://www.zephyrproject.org/about/#faq

 .. _Top 10 Apache License Questions Answered:
    https://www.whitesourcesoftware.com/whitesource-blog/top-10-apache-license-questions-answered/

 A license tells you what rights you have as a developer, as provided by the
 copyright holder. It is important that the contributor fully understands the
 licensing rights and agrees to them. Sometimes the copyright holder isn't the
 contributor, such as when the contributor is doing work on behalf of a
 company.

 Components using other Licenses
 ===============================

 There are some imported or reused components of the Zephyr project that
 use other licensing, as described in `Zephyr Licensing`_.

 .. _Zephyr Licensing:
    https://www.zephyrproject.org/doc/LICENSING.html

 Importing code into the Zephyr OS from other projects that use a license
 other than the Apache 2.0 license needs to be fully understood in
 context and approved by the Zephyr governing board.

 By carefully reviewing potential contributions and also enforcing a
 :ref:`DCO` for contributed code, we can ensure that
 the Zephyr community can develop products with the Zephyr Project
 without concerns over patent or copyright issues.

 See `Contributing non-Apache 2.0 components`_ for more information about
 this contributing and review process for imported components.

 .. _Contributing non-Apache 2.0 components:
    https://www.zephyrproject.org/doc/contribute/contribute_non-apache.html

 .. _DCO:

 Developer Certification of Origin (DCO)
 ***************************************

 To make a good faith effort to ensure licensing criteria are met, the Zephyr
 project requires the Developer Certificate of Origin (DCO) process to be
 followed.

 The DCO is an attestation attached to every contribution made by every
 developer. In the commit message of the contribution, (described more fully
 later in this document), the developer simply adds a ``Signed-off-by``
 statement and thereby agrees to the DCO.

 When a developer submits a patch, it is a commitment that the contributor has
 the right to submit the patch per the license.  The DCO agreement is shown
 below and at http://developercertificate.org/.


 .. code-block:: none

     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.

 DCO Sign-Off Methods
 ====================

 The DCO requires a sign-off message in the following format appear on each
 commit in the pull request::

    Signed-off-by: Zephyrus Zephyr <zephyrus@zephyrproject.org>

 The DCO text can either be manually added to your commit body, or you can add
 either ``-s`` or ``--signoff`` to your usual Git commit commands. If you forget
 to add the sign-off you can also amend a previous commit with the sign-off by
 running ``git commit --amend -s``. If you've pushed your changes to GitHub
 already you'll need to force push your branch after this with ``git push -f``.


 Prerequisites
 *************

 .. _Zephyr Project website: https://zephyrproject.org

 As a contributor, you'll want to be familiar with the Zephyr project, how to
 configure, install, and use it as explained in the `Zephyr Project website`_
 and how to set up your development environment as introduced in the Zephyr
 `Getting Started Guide`_.

 .. _Getting Started Guide:
    https://www.zephyrproject.org/doc/getting_started/getting_started.html

 The examples below use a Linux host environment for Zephyr development.
 You should be familiar with common developer tools such as Git and CMake, and
 platforms such as GitHub.

 If you haven't already done so, you'll need to create a (free) GitHub account
 on http://github.com and have Git tools available on your development system.

 Repository layout
 *****************

 To clone the main Zephyr Project repository use::

     $ git clone https://github.com/zephyrproject-rtos/zephyr

 The Zephyr project directory structure is described in `Source Tree Structure`_
 documentation. In addition to the Zephyr kernel itself, you'll also find the
 sources for technical documentation, sample code, supported board
 configurations, and a collection of subsystem tests.  All of these are
 available for developers to contribute to and enhance.

 .. _Source Tree Structure:
    https://www.zephyrproject.org/doc/kernel/overview/source_tree.html

 Pull Requests and Issues
 ************************

 .. _Zephyr Project Issues: https://github.com/zephyrproject-rtos/zephyr/issues

 .. _open pull requests: https://github.com/zephyrproject-rtos/zephyr/pulls

 .. _Zephyr-devel mailing list:
    https://lists.zephyrproject.org/mailman/listinfo/zephyr-devel

 Before starting on a patch, first check in our issues `Zephyr Project Issues`_
 system to see what's been reported on the issue you'd like to address.  Have a
 conversation on the `Zephyr-devel mailing list`_ (or the #zephyrproject IRC
 channel on freenode.net) to see what others think of your issue (and proposed
 solution).  You may find others that have encountered the issue you're
 finding, or that have similar ideas for changes or additions.  Send a message
 to the `Zephyr-devel mailing list`_ to introduce and discuss your idea with
 the development community.

 Please note that it's common practice on IRC to be away from the
 channel, but still have a client logged in to receive traffic. If you
 ask a question to a particular person and they don't answer, **try
 to stay signed in to the channel** if you can, so they have time to
 respond to you. This is especially important given the many different
 timezones Zephyr developers live in. If you don't get a timely
 response on IRC, try sending a message to the mailing list instead.

 It's always a good practice to search for existing or related issues before
 submitting your own. When you submit an issue (bug or feature request), the
 triage team will review and comment on the submission, typically within a few
 business days.

 You can find all `open pull requests`_ on GitHub and open `Zephyr Project
 Issues`_ in Github issues.

 Development Tools and Git Setup
 *******************************

 Signed-off-by
 =============

 The name in the commit message ``Signed-off-by:`` line and your email must
 match the change authorship information. Make sure your *.git/config* is set
 up correctly::

    $ git config --global user.name "David Developer"
    $ git config --global user.email "david.developer@company.com"

 gitlint
 =========

 When you submit a pull request to the project, a series of checks are
 performed to verify your commit messages meet the requirements. The same step
 done during the CI process can be performed locally using the the *gitlint*
 command.

 Install gitlint and run it locally in your tree and branch where your patches
 have been committed::

      $ sudo pip3 install gitlint
      $ gitlint

 Note, gitlint only checks HEAD (the most recent commit), so you should run it
 after each commit, or use the ``--commits`` option to specify a commit range
 covering all the development patches to be submitted.

 sanitycheck
 ===========

 To verify that your changes did not break any tests or samples, please run the
 ``sanitycheck`` script locally before submitting your pull request to GitHub. To
 run the same tests the CI system runs, follow these steps from within your
 local Zephyr source working directory::

     $ source zephyr-env.sh
     $ ./scripts/sanitycheck

 The above will execute the basic sanitycheck script, which will run various
 kernel tests using the QEMU emulator.  It will also do some build tests on
 various samples with advanced features that can't run in QEMU.

 We highly recommend you run these tests locally to avoid any CI
 failures.

 uncrustify
 ==========

 The `uncrustify tool <https://sourceforge.net/projects/uncrustify>`_ can
 be helpful to quickly reformat your source code to our `project coding
 standards <Coding Style>`_ together with a configuration file we've provided:

 .. code-block:: bash

    uncrustify --replace --no-backup -l C -c
      $ZEPHYR_BASE/scripts/uncrustify.cfg   my_source_file.c

 On Linux systems, you can install uncrustify with

 .. code-block:: bash

    sudo apt install uncrustify

 For Windows installation instructions see the `sourceforge listing for
 uncrustify <https://sourceforge.net/projects/uncrustify>`_.

 Coding Style
 ************

 Use these coding guidelines to ensure that your development complies with the
 project's style and naming conventions.

 .. _Linux kernel coding style:
    https://kernel.org/doc/html/latest/process/coding-style.html


 In general, follow the `Linux kernel coding style`_, with the
 following exceptions:

 * Add braces to every ``if`` and ``else`` body, even for single-line code
   blocks. Use the ``--ignore BRACES`` flag to make *checkpatch* stop
   complaining.
 * Use spaces instead of tabs to align comments after declarations, as needed.
 * Use C89-style single line comments, ``/*  */``. The C99-style single line
   comment, ``//``, is not allowed.
 * Use ``/**  */`` for doxygen comments that need to appear in the documentation.

 The Linux kernel GPL-licensed tool ``checkpatch`` is used to check
 coding style conformity. Checkpatch is available in the scripts
 directory. To invoke it when committing code, make the file
 *$ZEPHYR_BASE/.git/hooks/pre-commit* executable and edit it to contain:

 .. code-block:: bash

     #!/bin/sh
     set -e exec
     exec git diff --cached | ${ZEPHYR_BASE}/scripts/checkpatch.pl -

 .. _Contribution workflow:

 Contribution Workflow
 *********************

 One general practice we encourage, is to make small,
 controlled changes. This practice simplifies review, makes merging and
 rebasing easier, and keeps the change history clear and clean.

 When contributing to the Zephyr Project, it is also important you provide as much
 information as you can about your change, update appropriate documentation,
 and test your changes thoroughly before submitting.

 The general GitHub workflow used by Zephyr developers uses a combination of
 command line Git commands and browser interaction with GitHub.  As it is with
 Git, there are multiple ways of getting a task done.  We'll describe a typical
 workflow here:

 .. _Create a Fork of Zephyr:
    https://github.com/zephyrproject-rtos/zephyr#fork-destination-box

 #. `Create a Fork of Zephyr`_
    to your personal account on GitHub.  (Click on the fork button in the top
    right corner of the Zephyr project repo page in GitHub.)

 #. On your development computer, clone the fork you just made::

      $ git clone https://github.com/<your github id>/zephyr

    This would be a good time to let Git know about the upstream repo too::

      $ git remote add upstream https://github.com/zephyrproject-rtos/zephyr.git

    and verify the remote repos::

      $ git remote -v

 #. Create a topic branch (off of master) for your work (if you're addressing
    an issue, we suggest including the issue number in the branch name)::

      $ git checkout master
      $ git checkout -b fix_comment_typo

    Some Zephyr subsystems do development work on a separate branch from
    master so you may need to indicate this in your checkout::

      $ git checkout -b fix_out_of_date_patch origin/net

 #. Make changes, test locally, change, test, test again, ...  (Check out the
    prior chapter on `sanitycheck`_ as well).

 #. When things look good, start the pull request process by adding your changed
    files::

      $ git add [file(s) that changed, add -p if you want to be more specific]

    You can see files that are not yet staged using::

      $ git status

 #. Verify changes to be committed look as you expected::

      $ git diff --cached

 #. Commit your changes to your local repo::

      $ git commit -s

    The ``-s`` option automatically adds your ``Signed-off-by:`` to your commit
    message.  Your commit will be rejected without this line that indicates your
    agreement with the `DCO`_.  See the `Commit Guidelines`_ section for
    specific guidelines for writing your commit messages.

 #. Push your topic branch with your changes to your fork in your personal
    GitHub account::

      $ git push origin fix_comment_typo

 #. In your web browser, go to your forked repo and click on the
    ``Compare & pull request`` button for the branch you just worked on and
    you want to open a pull request with.

 #. Review the pull request changes, and verify that you are opening a
    pull request for the appropriate branch. The title and message from your
    commit message should appear as well.

 #. If you're working on a subsystem branch that's not ``master``,
    you may need to change the intended branch for the pull request
    here, for example, by changing the base branch from ``master`` to ``net``.

 #. GitHub will assign one or more suggested reviewers (based on the
    CODEOWNERS file in the repo). If you are a project member, you can
    select additional reviewers now too.

 #. Click on the submit button and your pull request is sent and awaits
    review.  Email will be sent as review comments are made, or you can check
    on your pull request at https://github.com/zephyrproject-rtos/zephyr/pulls.

 #. While you're waiting for your pull request to be accepted and merged, you
    can create another branch to work on another issue. (Be sure to make your
    new branch off of master and not the previous branch.)::

      $ git checkout master
      $ git checkout -b fix_another_issue

    and use the same process described above to work on this new topic branch.

 #. If reviewers do request changes to your patch, you can interactively rebase
    commit(s) to fix review issues.  In your development repo::

      $ git fetch --all
      $ git rebase --ignore-whitespace upstream/master

    The ``--ignore-whitespace`` option stops ``git apply`` (called by rebase)
    from changing any whitespace. Continuing::

      $ git rebase -i <offending-commit-id>^

    In the interactive rebase editor, replace ``pick`` with ``edit`` to select
    a specific commit (if there's more than one in your pull request), or
    remove the line to delete a commit entirely.  Then edit files to fix the
    issues in the review.

    As before, inspect and test your changes. When ready, continue the
    patch submission::

      $ git add [file(s)]
      $ git rebase --continue

    Update commit comment if needed, and continue::

      $ git push --force origin fix_comment_typo

    By force pushing your update, your original pull request will be updated
    with your changes so you won't need to resubmit the pull request.


 Commit Guidelines
 *****************

 Changes are submitted as Git commits. Each commit message must contain:

 * A short and descriptive subject line that is less than 72 characters,
   followed by a blank line. The subject line must include a prefix that
   identifies the subsystem being changed, followed by a colon, and a short
   title, for example:  ``doc: update wiki references to new site``.
   (If you're updating an existing file, you can use
   ``git log <filename>`` to see what developers used as the prefix for
   previous patches of this file.)

 * A change description with your logic or reasoning for the changes, followed
   by a blank line.

 * A Signed-off-by line, ``Signed-off-by: <name> <email>`` typically added
   automatically by using ``git commit -s``

 * If the change addresses an issue, include a line of the form::

       Fixes #<issue number>.


 All changes and topics sent to GitHub must be well-formed, as described above.

 Commit Message Body
 ===================

 When editing the commit message, please briefly explain what your change
 does and why it's needed. A change summary of ``"Fixes stuff"`` will be rejected.

 .. warning::
    An empty change summary body is not permitted. Even for trivial changes, please
    include a summary body in the commmit message.

 The description body of the commit message must include:

 * **what** the change does,
 * **why** you chose that approach,
 * **what** assumptions were made, and
 * **how** you know it works -- for example, which tests you ran.

 For examples of accepted commit messages, you can refer to the Zephyr GitHub
 `changelog <https://github.com/zephyrproject-rtos/zephyr/commits/master>`__.

 Other Commit Expectations
 =========================

 * Commits must build cleanly when applied on top of each other, thus avoiding
   breaking bisectability.

 * Commits must pass the *scripts/checkpatch.pl* requirements.

 * Each commit must address a single identifiable issue and must be
   logically self-contained. Unrelated changes should be submitted as
   separate commits.

 * You may submit pull request RFCs (requests for comments) to send work
   proposals, progress snapshots of your work, or to get early feedback on
   features or changes that will affect multiple areas in the code base.

 Identifying Contribution Origin
 ===============================

 When adding a new file to the tree, it is important to detail the source of
 origin on the file, provide attributions, and detail the intended usage. In
 cases where the file is an original to Zephyr, the commit message should
 include the following ("Original" is the assumption if no Origin tag is
 present)::

     Origin: Original

 In cases where the file is imported from an external project, the commit
 message shall contain details regarding the original project, the location of
 the project, the SHA-id of the origin commit for the file, the intended
 purpose, and if the file will be maintained by the Zephyr project,
 (whether or not the Zephyr project will contain a localized branch or if
 it is a downstream copy).

 For example, a copy of a locally maintained import::

     Origin: Contiki OS
     License: BSD 3-Clause
     URL: http://www.contiki-os.org/
     commit: 853207acfdc6549b10eb3e44504b1a75ae1ad63a
     Purpose: Introduction of networking stack.
     Maintained-by: Zephyr

 For example, a copy of an externally maintained import::

     Origin: Tiny Crypt
     License: BSD 3-Clause
     URL: https://github.com/01org/tinycrypt
     commit: 08ded7f21529c39e5133688ffb93a9d0c94e5c6e
     Purpose: Introduction of TinyCrypt
     Maintained-by: External
	Contribution Guidelines
	#######################

	As an open-source project, we welcome and encourage the community to submit
	patches directly to the project. In our collaborative open source environment,
	standards and methods for submitting changes help reduce the chaos that can result
	from an active development community.

	This document explains how to participate in project conversations, log bugs
	and enhancement requests, and submit patches to the project so your patch will
	be accepted quickly in the codebase.


	Licensing
	*********

	Licensing is very important to open source projects. It helps ensure the
	software continues to be available under the terms that the author desired.

	.. _Apache 2.0 license:
	https://github.com/zephyrproject-rtos/zephyr/blob/master/LICENSE

	.. _GitHub repo: https://github.com/zephyrproject-rtos/zephyr

	Zephyr uses the `Apache 2.0 license`_ (as found in the LICENSE file in
	the project's `GitHub repo`_) to strike a balance between open
	contribution and allowing you to use the software however you would like
	to. The Apache 2.0 license is a permisive open source license that
	allows you to freely use, modify, distribute and sell your own products
	that include Apache 2.0 licensed software. (For more information about
	this, check out articles such as `Why choose Apache 2.0 licensing`_ and
	`Top 10 Apache License Questions Answered`_).

	.. _Why choose Apache 2.0 licensing:
	https://www.zephyrproject.org/about/#faq

	.. _Top 10 Apache License Questions Answered:
	https://www.whitesourcesoftware.com/whitesource-blog/top-10-apache-license-questions-answered/

	A license tells you what rights you have as a developer, as provided by the
	copyright holder. It is important that the contributor fully understands the
	licensing rights and agrees to them. Sometimes the copyright holder isn't the
	contributor, such as when the contributor is doing work on behalf of a
	company.

	Components using other Licenses
	===============================

	There are some imported or reused components of the Zephyr project that
	use other licensing, as described in `Zephyr Licensing`_.

	.. _Zephyr Licensing:
	https://www.zephyrproject.org/doc/LICENSING.html

	Importing code into the Zephyr OS from other projects that use a license
	other than the Apache 2.0 license needs to be fully understood in
	context and approved by the Zephyr governing board.

	By carefully reviewing potential contributions and also enforcing a
	:ref:`DCO` for contributed code, we can ensure that
	the Zephyr community can develop products with the Zephyr Project
	without concerns over patent or copyright issues.

	See `Contributing non-Apache 2.0 components`_ for more information about
	this contributing and review process for imported components.

	.. _Contributing non-Apache 2.0 components:
	https://www.zephyrproject.org/doc/contribute/contribute_non-apache.html

	.. _DCO:

	Developer Certification of Origin (DCO)
	***************************************

	To make a good faith effort to ensure licensing criteria are met, the Zephyr
	project requires the Developer Certificate of Origin (DCO) process to be
	followed.

	The DCO is an attestation attached to every contribution made by every
	developer. In the commit message of the contribution, (described more fully
	later in this document), the developer simply adds a ``Signed-off-by``
	statement and thereby agrees to the DCO.

	When a developer submits a patch, it is a commitment that the contributor has
	the right to submit the patch per the license. The DCO agreement is shown
	below and at http://developercertificate.org/.


	.. code-block:: none

	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.

	DCO Sign-Off Methods
	====================

	The DCO requires a sign-off message in the following format appear on each
	commit in the pull request::

	Signed-off-by: Zephyrus Zephyr <zephyrus@zephyrproject.org>

	The DCO text can either be manually added to your commit body, or you can add
	either ``-s`` or ``--signoff`` to your usual Git commit commands. If you forget
	to add the sign-off you can also amend a previous commit with the sign-off by
	running ``git commit --amend -s``. If you've pushed your changes to GitHub
	already you'll need to force push your branch after this with ``git push -f``.


	Prerequisites
	*************

	.. _Zephyr Project website: https://zephyrproject.org

	As a contributor, you'll want to be familiar with the Zephyr project, how to
	configure, install, and use it as explained in the `Zephyr Project website`_
	and how to set up your development environment as introduced in the Zephyr
	`Getting Started Guide`_.

	.. _Getting Started Guide:
	https://www.zephyrproject.org/doc/getting_started/getting_started.html

	The examples below use a Linux host environment for Zephyr development.
	You should be familiar with common developer tools such as Git and CMake, and
	platforms such as GitHub.

	If you haven't already done so, you'll need to create a (free) GitHub account
	on http://github.com and have Git tools available on your development system.

	Repository layout
	*****************

	To clone the main Zephyr Project repository use::

	$ git clone https://github.com/zephyrproject-rtos/zephyr

	The Zephyr project directory structure is described in `Source Tree Structure`_
	documentation. In addition to the Zephyr kernel itself, you'll also find the
	sources for technical documentation, sample code, supported board
	configurations, and a collection of subsystem tests. All of these are
	available for developers to contribute to and enhance.

	.. _Source Tree Structure:
	https://www.zephyrproject.org/doc/kernel/overview/source_tree.html

	Pull Requests and Issues
	************************

	.. _Zephyr Project Issues: https://github.com/zephyrproject-rtos/zephyr/issues

	.. _open pull requests: https://github.com/zephyrproject-rtos/zephyr/pulls

	.. _Zephyr-devel mailing list:
	https://lists.zephyrproject.org/mailman/listinfo/zephyr-devel

	Before starting on a patch, first check in our issues `Zephyr Project Issues`_
	system to see what's been reported on the issue you'd like to address. Have a
	conversation on the `Zephyr-devel mailing list`_ (or the #zephyrproject IRC
	channel on freenode.net) to see what others think of your issue (and proposed
	solution). You may find others that have encountered the issue you're
	finding, or that have similar ideas for changes or additions. Send a message
	to the `Zephyr-devel mailing list`_ to introduce and discuss your idea with
	the development community.

	Please note that it's common practice on IRC to be away from the
	channel, but still have a client logged in to receive traffic. If you
	ask a question to a particular person and they don't answer, **try
	to stay signed in to the channel** if you can, so they have time to
	respond to you. This is especially important given the many different
	timezones Zephyr developers live in. If you don't get a timely
	response on IRC, try sending a message to the mailing list instead.

	It's always a good practice to search for existing or related issues before
	submitting your own. When you submit an issue (bug or feature request), the
	triage team will review and comment on the submission, typically within a few
	business days.

	You can find all `open pull requests`_ on GitHub and open `Zephyr Project
	Issues`_ in Github issues.

	Development Tools and Git Setup
	*******************************

	Signed-off-by
	=============

	The name in the commit message ``Signed-off-by:`` line and your email must
	match the change authorship information. Make sure your .git/config is set
	up correctly::

	$ git config --global user.name "David Developer"
	$ git config --global user.email "david.developer@company.com"

	gitlint
	=========

	When you submit a pull request to the project, a series of checks are
	performed to verify your commit messages meet the requirements. The same step
	done during the CI process can be performed locally using the the gitlint
	command.

	Install gitlint and run it locally in your tree and branch where your patches
	have been committed::

	$ sudo pip3 install gitlint
	$ gitlint

	Note, gitlint only checks HEAD (the most recent commit), so you should run it
	after each commit, or use the ``--commits`` option to specify a commit range
	covering all the development patches to be submitted.

	sanitycheck
	===========

	To verify that your changes did not break any tests or samples, please run the
	``sanitycheck`` script locally before submitting your pull request to GitHub. To
	run the same tests the CI system runs, follow these steps from within your
	local Zephyr source working directory::

	$ source zephyr-env.sh
	$ ./scripts/sanitycheck

	The above will execute the basic sanitycheck script, which will run various
	kernel tests using the QEMU emulator. It will also do some build tests on
	various samples with advanced features that can't run in QEMU.

	We highly recommend you run these tests locally to avoid any CI
	failures.

	uncrustify
	==========

	The `uncrustify tool <https://sourceforge.net/projects/uncrustify>`_ can
	be helpful to quickly reformat your source code to our `project coding
	standards <Coding Style>`_ together with a configuration file we've provided:

	.. code-block:: bash

	uncrustify --replace --no-backup -l C -c
	$ZEPHYR_BASE/scripts/uncrustify.cfg my_source_file.c

	On Linux systems, you can install uncrustify with

	.. code-block:: bash

	sudo apt install uncrustify

	For Windows installation instructions see the `sourceforge listing for
	uncrustify <https://sourceforge.net/projects/uncrustify>`_.

	Coding Style
	************

	Use these coding guidelines to ensure that your development complies with the
	project's style and naming conventions.

	.. _Linux kernel coding style:
	https://kernel.org/doc/html/latest/process/coding-style.html


	In general, follow the `Linux kernel coding style`_, with the
	following exceptions:

	* Add braces to every ``if`` and ``else`` body, even for single-line code
	blocks. Use the ``--ignore BRACES`` flag to make checkpatch stop
	complaining.
	* Use spaces instead of tabs to align comments after declarations, as needed.
	* Use C89-style single line comments, ``/* */``. The C99-style single line
	comment, ``//``, is not allowed.
	* Use ``/** */`` for doxygen comments that need to appear in the documentation.

	The Linux kernel GPL-licensed tool ``checkpatch`` is used to check
	coding style conformity. Checkpatch is available in the scripts
	directory. To invoke it when committing code, make the file
	$ZEPHYR_BASE/.git/hooks/pre-commit executable and edit it to contain:

	.. code-block:: bash

	#!/bin/sh
	set -e exec
	exec git diff --cached \| ${ZEPHYR_BASE}/scripts/checkpatch.pl -

	.. _Contribution workflow:

	Contribution Workflow
	*********************

	One general practice we encourage, is to make small,
	controlled changes. This practice simplifies review, makes merging and
	rebasing easier, and keeps the change history clear and clean.

	When contributing to the Zephyr Project, it is also important you provide as much
	information as you can about your change, update appropriate documentation,
	and test your changes thoroughly before submitting.

	The general GitHub workflow used by Zephyr developers uses a combination of
	command line Git commands and browser interaction with GitHub. As it is with
	Git, there are multiple ways of getting a task done. We'll describe a typical
	workflow here:

	.. _Create a Fork of Zephyr:
	https://github.com/zephyrproject-rtos/zephyr#fork-destination-box

	#. `Create a Fork of Zephyr`_
	to your personal account on GitHub. (Click on the fork button in the top
	right corner of the Zephyr project repo page in GitHub.)

	#. On your development computer, clone the fork you just made::

	$ git clone https://github.com/<your github id>/zephyr

	This would be a good time to let Git know about the upstream repo too::

	$ git remote add upstream https://github.com/zephyrproject-rtos/zephyr.git

	and verify the remote repos::

	$ git remote -v

	#. Create a topic branch (off of master) for your work (if you're addressing
	an issue, we suggest including the issue number in the branch name)::

	$ git checkout master
	$ git checkout -b fix_comment_typo

	Some Zephyr subsystems do development work on a separate branch from
	master so you may need to indicate this in your checkout::

	$ git checkout -b fix_out_of_date_patch origin/net

	#. Make changes, test locally, change, test, test again, ... (Check out the
	prior chapter on `sanitycheck`_ as well).

	#. When things look good, start the pull request process by adding your changed
	files::

	$ git add [file(s) that changed, add -p if you want to be more specific]

	You can see files that are not yet staged using::

	$ git status

	#. Verify changes to be committed look as you expected::

	$ git diff --cached

	#. Commit your changes to your local repo::

	$ git commit -s

	The ``-s`` option automatically adds your ``Signed-off-by:`` to your commit
	message. Your commit will be rejected without this line that indicates your
	agreement with the `DCO`_. See the `Commit Guidelines`_ section for
	specific guidelines for writing your commit messages.

	#. Push your topic branch with your changes to your fork in your personal
	GitHub account::

	$ git push origin fix_comment_typo

	#. In your web browser, go to your forked repo and click on the
	``Compare & pull request`` button for the branch you just worked on and
	you want to open a pull request with.

	#. Review the pull request changes, and verify that you are opening a
	pull request for the appropriate branch. The title and message from your
	commit message should appear as well.

	#. If you're working on a subsystem branch that's not ``master``,
	you may need to change the intended branch for the pull request
	here, for example, by changing the base branch from ``master`` to ``net``.

	#. GitHub will assign one or more suggested reviewers (based on the
	CODEOWNERS file in the repo). If you are a project member, you can
	select additional reviewers now too.

	#. Click on the submit button and your pull request is sent and awaits
	review. Email will be sent as review comments are made, or you can check
	on your pull request at https://github.com/zephyrproject-rtos/zephyr/pulls.

	#. While you're waiting for your pull request to be accepted and merged, you
	can create another branch to work on another issue. (Be sure to make your
	new branch off of master and not the previous branch.)::

	$ git checkout master
	$ git checkout -b fix_another_issue

	and use the same process described above to work on this new topic branch.

	#. If reviewers do request changes to your patch, you can interactively rebase
	commit(s) to fix review issues. In your development repo::

	$ git fetch --all
	$ git rebase --ignore-whitespace upstream/master

	The ``--ignore-whitespace`` option stops ``git apply`` (called by rebase)
	from changing any whitespace. Continuing::

	$ git rebase -i <offending-commit-id>^

	In the interactive rebase editor, replace ``pick`` with ``edit`` to select
	a specific commit (if there's more than one in your pull request), or
	remove the line to delete a commit entirely. Then edit files to fix the
	issues in the review.

	As before, inspect and test your changes. When ready, continue the
	patch submission::

	$ git add [file(s)]
	$ git rebase --continue

	Update commit comment if needed, and continue::

	$ git push --force origin fix_comment_typo

	By force pushing your update, your original pull request will be updated
	with your changes so you won't need to resubmit the pull request.


	Commit Guidelines
	*****************

	Changes are submitted as Git commits. Each commit message must contain:

	* A short and descriptive subject line that is less than 72 characters,
	followed by a blank line. The subject line must include a prefix that
	identifies the subsystem being changed, followed by a colon, and a short
	title, for example: ``doc: update wiki references to new site``.
	(If you're updating an existing file, you can use
	``git log <filename>`` to see what developers used as the prefix for
	previous patches of this file.)

	* A change description with your logic or reasoning for the changes, followed
	by a blank line.

	* A Signed-off-by line, ``Signed-off-by: <name> <email>`` typically added
	automatically by using ``git commit -s``

	* If the change addresses an issue, include a line of the form::

	Fixes #<issue number>.


	All changes and topics sent to GitHub must be well-formed, as described above.

	Commit Message Body
	===================

	When editing the commit message, please briefly explain what your change
	does and why it's needed. A change summary of ``"Fixes stuff"`` will be rejected.

	.. warning::
	An empty change summary body is not permitted. Even for trivial changes, please
	include a summary body in the commmit message.

	The description body of the commit message must include:

	* what the change does,
	* why you chose that approach,
	* what assumptions were made, and
	* how you know it works -- for example, which tests you ran.

	For examples of accepted commit messages, you can refer to the Zephyr GitHub
	`changelog <https://github.com/zephyrproject-rtos/zephyr/commits/master>`__.

	Other Commit Expectations
	=========================

	* Commits must build cleanly when applied on top of each other, thus avoiding
	breaking bisectability.

	* Commits must pass the scripts/checkpatch.pl requirements.

	* Each commit must address a single identifiable issue and must be
	logically self-contained. Unrelated changes should be submitted as
	separate commits.

	* You may submit pull request RFCs (requests for comments) to send work
	proposals, progress snapshots of your work, or to get early feedback on
	features or changes that will affect multiple areas in the code base.

	Identifying Contribution Origin
	===============================

	When adding a new file to the tree, it is important to detail the source of
	origin on the file, provide attributions, and detail the intended usage. In
	cases where the file is an original to Zephyr, the commit message should
	include the following ("Original" is the assumption if no Origin tag is
	present)::

	Origin: Original

	In cases where the file is imported from an external project, the commit
	message shall contain details regarding the original project, the location of
	the project, the SHA-id of the origin commit for the file, the intended
	purpose, and if the file will be maintained by the Zephyr project,
	(whether or not the Zephyr project will contain a localized branch or if
	it is a downstream copy).

	For example, a copy of a locally maintained import::

	Origin: Contiki OS
	License: BSD 3-Clause
	URL: http://www.contiki-os.org/
	commit: 853207acfdc6549b10eb3e44504b1a75ae1ad63a
	Purpose: Introduction of networking stack.
	Maintained-by: Zephyr

	For example, a copy of an externally maintained import::

	Origin: Tiny Crypt
	License: BSD 3-Clause
	URL: https://github.com/01org/tinycrypt
	commit: 08ded7f21529c39e5133688ffb93a9d0c94e5c6e
	Purpose: Introduction of TinyCrypt
	Maintained-by: External