Lines Matching +full:directory +full:- +full:to +full:- +full:scan
6 As an open-source project, we welcome and encourage the community to submit
7 patches directly to the project. In our collaborative open source environment,
11 This document explains how to participate in project conversations, log bugs
12 and enhancement requests, and submit patches to the project so your patch will
20 Licensing is very important to open source projects. It helps ensure the
21 software continues to be available under the terms that the author desired.
24 https://github.com/zephyrproject-rtos/zephyr/blob/main/LICENSE
26 .. _GitHub repo: https://github.com/zephyrproject-rtos/zephyr
29 the project's `GitHub repo`_) to strike a balance between open
30 contribution and allowing you to use the software however you would like
31 to. The Apache 2.0 license is a permissive open source license that
32 allows you to freely use, modify, distribute and sell your own products
38 https://www.zephyrproject.org/faqs/#1571346989065-9216c551-f523
41 https://www.whitesourcesoftware.com/whitesource-blog/top-10-apache-license-questions-answered/
45 licensing rights and agrees to them. Sometimes the copyright holder isn't the
56 other than the Apache 2.0 license needs to be fully understood in
64 See :ref:`external-contributions` for more information about
84 https://www.linuxfoundation.org/blog/copyright-notices-in-open-source-software-projects/
91 To make a good faith effort to ensure licensing criteria are met, the Zephyr
92 project requires the Developer Certificate of Origin (DCO) process to be
95 The DCO is an attestation attached to every contribution made by every
97 later in this document), the developer simply adds a ``Signed-off-by``
98 statement and thereby agrees to the DCO.
101 the right to submit the patch per the license. The DCO agreement is shown
104 .. code-block:: none
108 By making a contribution to this project, I certify that:
111 have the right to submit it under the open source license
114 (b) The contribution is based upon previous work that, to the
116 source license and I have the right under that license to
119 I am permitted to submit under a different license), as
122 (c) The contribution was provided directly to me by some other
129 sign-off) is maintained indefinitely and may be redistributed
133 DCO Sign-Off
136 The "sign-off" in the DCO is a "Signed-off-by:" line in each commit's log
137 message. The Signed-off-by: line must be in the following format::
139 Signed-off-by: Your Name <your.email@example.com>
143 - ``Your Name`` with your legal name (pseudonyms, hacker handles, and the
146 - ``your.email@example.com`` with the same email address you are using to
149 You can automatically add the Signed-off-by: line to your commit body using
150 ``git commit -s``. Use other commits in the zephyr git history as examples.
156 - If you are altering an existing commit created by someone else, you must add
157 your Signed-off-by: line without removing the existing one.
159 - If you forget to add the Signed-off-by: line, you can add it to your previous
160 commit by running ``git commit --amend -s``.
162 - If you've pushed your changes to GitHub already you'll need to force push
163 your branch after this with ``git push -f``.
169 for the Project to use. Developers are permitted to cherry-pick patches that
174 * the cherry-picked commits or portions of a commit shall preserve the original
175 sign-off messages and the author identity.
186 As a contributor, you'll want to be familiar with the Zephyr project, how to
188 and how to set up your development environment as introduced in the Zephyr
194 If you haven't already done so, you'll need to create a (free) GitHub account
201 tools yourself, you will need to rely on the Continuous Integration (CI)
212 To clone the main Zephyr Project repository use the instructions in
215 This section describes the main repository's source tree. In addition to the
218 tests. All of these are available for developers to contribute to and enhance.
226 The top-level file for the CMake build system, containing a lot of the
227 logic required to build Zephyr.
230 The top-level Kconfig file, which refers to the file :file:`Kconfig.zephyr`
231 also found in the top-level directory.
238 the west command-line tool.
240 The Zephyr source tree also contains the following top-level
245 Architecture-specific kernel and system-on-chip (SoC) code.
250 * architecture-specific kernel source files
251 * architecture-specific kernel include files for private APIs
260 Zephyr technical documentation source files and tools used to
267 :ref:`devicetree <dt-guide>` source files used to describe non-discoverable
268 board-specific hardware details.
274 Architecture-independent kernel code.
280 Miscellaneous code that doesn't belong to any of the other top-level
287 Various programs and other files used to build and test Zephyr
291 Additional build scripts needed to build Zephyr.
311 .. _Zephyr Project Issues: https://github.com/zephyrproject-rtos/zephyr/issues
313 .. _open pull requests: https://github.com/zephyrproject-rtos/zephyr/pulls
320 system to see what's been reported on the issue you'd like to address. Have a
322 Server`_) to see what others think of your issue (and proposed solution). You
324 similar ideas for changes or additions. Send a message to the `Zephyr devel
325 mailing list`_ to introduce and discuss your idea with the development
328 It's always a good practice to search for existing or related issues before
341 We need to know who you are, and how to contact you. To add this
342 information to your Git installation, set the Git configuration
343 variables ``user.name`` to your full name, and ``user.email`` to your
349 .. code-block:: console
351 git config --global user.name "Zephyr Developer"
352 git config --global user.email "z.developer@example.com"
357 address you use to sign your commits. If they don't match, the CI system will
360 If you intend to edit commits using the Github.com UI, ensure that your github profile
366 When opening a new Pull Request, adhere to the following guidelines to ensure
369 If in doubt, it's advisible to explore existing Pull Requests within the Zephyr
370 repository. Use the search filters and labels to locate PRs related to changes
371 similar to the ones you are proposing.
373 .. _commit-guidelines:
382 .. code-block:: none
386 [Commit message body (must be non-empty)]
388 Signed-off-by: [Your Full Name] <[your.email@address]>
390 You need to change text in square brackets (``[like this]``) above to
396 -------
400 .. code-block:: none
404 The abcd1234 sensor driver is failing to check the flags field in
406 occurred. This can lead to reading invalid data from the response
409 Signed-off-by: Zephyr Developer <z.developer@example.com>
412 ---------------------------
429 * ``Bluetooth: Shell:`` for changes to the Bluetooth shell
430 * ``net: ethernet:`` for Ethernet-related networking changes
434 If you're not sure what to use, try running ``git log FILE``, where
442 * ``doc: update wiki references to new site``
446 -------------------
456 rejected. Be sure to include the following as relevant:
461 * **how** you know it works -- for example, which tests you ran.
464 less. Use newlines to wrap longer lines. Exceptions include lines
467 For examples of accepted commit messages, you can refer to the Zephyr GitHub
468 `changelog <https://github.com/zephyrproject-rtos/zephyr/commits/main>`__.
471 Signed-off-by: ...
472 ------------------
477 already. Create your commit with ``git commit -s`` to add the
478 Signed-off-by: line automatically using this information.
481 Signed-off-by: line that looks like this:
483 .. code-block:: none
485 Signed-off-by: [Your Full Name] <[your.email@address]>
490 .. code-block:: none
492 Signed-off-by: Zephyr Developer <z.developer@example.com>
501 See the :ref:`contributor-expectations` for a more complete discussion of
505 ------------
508 …https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/autolink…
515 .. code-block:: none
522 .. code-block:: none
526 You can point to other relevant information that can be found on the web using
530 .. code-block:: none
532 Link: https://github.com/zephyrproject-rtos/zephyr/issues/<issue number>
540 https://kernel.org/doc/html/latest/process/coding-style.html
547 * Add braces to every ``if``, ``else``, ``do``, ``while``, ``for`` and
548 ``switch`` body, even for single-line code blocks.
549 * Use spaces instead of tabs to align comments after declarations, as needed.
550 * Use C89-style single line comments, ``/* */``. The C99-style single line
552 * Use ``/** */`` for doxygen comments that need to appear in the documentation.
554 * Avoid using non-ASCII symbols in code, unless it significantly improves
557 Use these coding guidelines to ensure that your development complies with the
560 The Linux kernel GPL-licensed tool ``checkpatch`` is used to check
566 Checkpatch is available in the scripts directory. To invoke it when committing
567 code, make the file *$ZEPHYR_BASE/.git/hooks/pre-commit* executable and edit
568 it to contain:
570 .. code-block:: bash
573 set -e exec
574 exec git diff --cached | ${ZEPHYR_BASE}/scripts/checkpatch.pl -
576 Instead of running checkpatch at each commit, you may prefer to run it only
577 before pushing on zephyr repo. To do this, make the file
578 *$ZEPHYR_BASE/.git/hooks/pre-push* executable and edit it to contain:
580 .. code-block:: bash
593 exec ${ZEPHYR_BASE}/scripts/series-push-hook.sh $args
598 If you want to override checkpatch verdict and push you branch despite reported
599 issues, you can add option --no-verify to the git push command.
601 A more complete alternative to this is using :ref:`check_compliance_py` script.
603 clang-format
604 ------------
606 The `clang-format tool <https://clang.llvm.org/docs/ClangFormat.html>`_ can
607 be helpful to quickly reformat large amounts of new source code to our
608 `Coding Style`_ standards together with the ``.clang-format`` configuration file
609 provided in the repository. ``clang-format`` is well integrated into most
612 .. code-block:: bash
614 clang-format -i my_source_file.c
616 ``clang-format`` is part of LLVM, which can be downloaded from the project
617 `releases page <https://github.com/llvm/llvm-project/releases>`_. Note that if
618 you are a Linux user, ``clang-format`` will likely be available as a package in
632 every Pull Request (PR) in order to verify several aspects of the PR:
637 * Documentation build to verify any doc changes
652 failure message in order to navigate to ``Github Actions`` and inspect the
654 Once you click on the link you will be taken to the ``Github actions`` summary
655 results page where a table with all the different builds will be shown. To see
657 non-green) build.
667 -------------------
674 Developers are encouraged to run the script locally to validate their changes
677 .. code-block:: bash
679 ./scripts/ci/check_compliance.py -c upstream/main..
682 -------
691 If a test fails, you can check from the CI run logs how to rerun it locally,
694 .. code-block:: bash
696 west twister -p native_sim -s tests/drivers/build_all/sensor/sensors.generic_test
703 Coverity Scan is a free service for static code analysis of Open Source
704 projects. It is based on Coverity's commercial product and is able to analyze
708 abstract interpretation to gain information about the code's control flow and
709 data flow. It's able to follow all possible code paths that a program may take.
711 be freed with free() later. It follows all branches and function calls to see
712 if all possible combinations free the memory. The analyzer is able to detect
717 The results are available on the `Coverity Scan
718 <https://scan.coverity.com/projects/zephyr>`_ website. In order to access the
719 results you have to create an account yourself. From the Zephyr project page,
720 you may select "Add me to project" to be added to the project. New members must
723 Static analysis of the Zephyr codebase is conducted on a bi-weekly basis. GitHub
728 To ensure accountability and efficient issue resolution, they are assigned to
740 positive please set the classification to either "False positive" or
741 "Intentional", the action to "Ignore", owner to your own account and add a
745 it after completing the steps above on scan service website. Any issues
746 closed without a fix or without ignoring the entry in the scan service will be
747 automatically reopened if the issue continues to be present in the code.
754 One general practice we encourage, is to make small,
758 When contributing to the Zephyr Project, it is also important you provide as much
768 https://github.com/zephyrproject-rtos/zephyr#fork-destination-box
771 to your personal account on GitHub. (Click on the fork button in the top
779 Rename the default remote pointing to the `upstream repository
780 <https://github.com/zephyrproject-rtos/zephyr>`_ from ``origin`` to
791 git remote -v
793 The output should look similar to::
797 upstream https://github.com/zephyrproject-rtos/zephyr (fetch)
798 upstream https://github.com/zephyrproject-rtos/zephyr (push)
804 git checkout -b fix_comment_typo
807 ``main`` so you may need to indicate this in your checkout::
809 git checkout -b fix_out_of_date_patch origin/net
817 git add [file(s) that changed, add -p if you want to be more specific]
823 #. Verify changes to be committed look as you expected::
825 git diff --cached
827 #. Commit your changes to your local repo::
829 git commit -s
831 The ``-s`` option automatically adds your ``Signed-off-by:`` to your commit
833 agreement with the :ref:`DCO`. See the :ref:`commit-guidelines` section for
836 #. Push your topic branch with your changes to your fork in your personal
841 #. In your web browser, go to your forked repo and click on the
843 you want to open a pull request with.
855 on your pull request at https://github.com/zephyrproject-rtos/zephyr/pulls.
858 a ``This branch is out-of-date with the base branch`` message and a
861 a branch update from the GitHub UI will cause the PR approvals to be
864 #. While you're waiting for your pull request to be accepted and merged, you
865 can create another branch to work on another issue. (Be sure to make your
869 git checkout -b fix_another_issue
871 and use the same process described above to work on this new topic branch.
873 #. If reviewers do request changes to your patch, you can interactively rebase
874 commit(s) to fix review issues. In your development repo::
876 git rebase -i <offending-commit-id>^
878 In the interactive rebase editor, replace ``pick`` with ``edit`` to select
880 remove the line to delete a commit entirely. Then edit files to fix the
887 git rebase --continue
891 git push --force origin fix_comment_typo
894 with your changes so you won't need to resubmit the pull request.
899 git fetch --all
900 git rebase --ignore-whitespace upstream/main
902 The ``--ignore-whitespace`` option stops ``git apply`` (called by rebase)
905 git push --force origin fix_comment_typo
910 such as not being able to use "View Changes" buttons except for the last
911 one - GitHub complains it can't find older commits. You're also not
912 always able to compare the latest reviewed version with the latest
914 to the latest version.
916 #. If the CI run fails, you will need to make changes to your code in order
917 to fix the issues and amend your commits by rebasing as described above.
926 The following is a list of tips to improve and accelerate the review process of
930 .. _git-rebase:
931 https://git-scm.com/docs/git-rebase#Documentation/git-rebase.txt---keep-base
933 #. When pushing follow-up changes, use the ``--keep-base`` option of
934 `git-rebase`_
949 #. Revisit PR after 1-2 hours to see the status of all CI checks, make sure all
952 #. If you get request for changes and submit a change to address them, make
953 sure you click the "Re-request review" button on the GitHub UI to notify
960 You can request a new feature or submit a proposal by submitting an issue to
962 If you would like to implement a new feature, please submit an issue with a
963 proposal (RFC) for your work first, to be sure that we can use it. Please
967 can be discussed. This will also allow us to better coordinate our efforts,
968 prevent duplication of work, and help you to craft the change so that it is
983 When adding a new file to the tree, it is important to detail the source of
985 cases where the file is an original to Zephyr, the commit message should
992 <external-contributions>`, the commit message shall contain details regarding
993 the original project, the location of the project, the SHA-id of the origin
999 License: BSD 3-Clause
1000 URL: http://www.contiki-os.org/
1007 License: BSD 3-Clause
1012 Contributions to External Modules
1017 submitting changes to :ref:`existing modules <changes_to_existing_module>`.
1019 .. _treewide-changes:
1025 additional associated requirements that apply to them. These requirements exist
1026 to try to give such changes increased review and user visibility due to their
1032 A *treewide change* is defined as any change to Zephyr APIs, coding practices,
1034 throughout the zephyr source code repository or can reasonably be expected to
1035 do so for a wide class of external Zephyr-based source code.
1044 Steering Committee (TSC), but please avoid premature escalation to the TSC.
1049 - The zephyr repository must apply the 'treewide' GitHub label to any issues or
1052 - The person proposing a treewide change must create an `RFC issue
1053 …<https://github.com/zephyrproject-rtos/zephyr/issues/new?assignees=&labels=RFC&template=003_rfc-pr…
1055 requests related to the change can be merged
1057 - The project's `Architecture Working Group (WG)
1058 <https://github.com/zephyrproject-rtos/zephyr/wiki/Architecture-Working-Group>`_
1060 accept or reject the change before any pull requests related to the change
1061 can be merged (with escalation to the TSC if consensus is not reached at the
1064 - The Architecture WG must specify the procedure for merging any PRs associated
1068 - The person proposing a treewide change must email
1070 Architecture WG before any pull requests related to the change can be merged
1077 - the deprecation of version 1 of the :ref:`Logging API <logging_api>` in favor
1079 <https://github.com/zephyrproject-rtos/zephyr/commit/262cc55609b73ea61b5f999c6c6daaba20bc5240>`_)
1080 - the removal of support for a legacy :ref:`dt-bindings` syntax
1082 <https://github.com/zephyrproject-rtos/zephyr/commit/6bf761fc0a2811b037abec0c963d60b00c452acb>`_)
1095 If it is not technically possible to achieve full performance using the Zephyr
1096 APIs due to specialized accelerators in a particular SoC family, one could
1100 Architecture WG in order to be validated and potentially to be learned/improved