Lines Matching +full:zephyr +full:- +full:main +full:- +full:ci +full:- +full:push +full:- +full:1
6 As an open-source project, we welcome and encourage the community to submit
21 As a contributor, you'll want to be familiar with the Zephyr project, how to
22 configure, install, and use it as explained in the `Zephyr Project website`_
23 and how to set up your development environment as introduced in the Zephyr
33 The Zephyr development workflow supports all 3 major operating systems
36 tools yourself, you will need to rely on the Continuous Integration (CI)
52 https://github.com/zephyrproject-rtos/zephyr/blob/main/LICENSE
54 .. _GitHub repo: https://github.com/zephyrproject-rtos/zephyr
56 Zephyr uses the `Apache 2.0 license`_ (as found in the LICENSE file in
66 https://www.zephyrproject.org/faqs/#1571346989065-9216c551-f523
69 https://www.whitesourcesoftware.com/whitesource-blog/top-10-apache-license-questions-answered/
80 There are some imported or reused components of the Zephyr project that
83 Importing code into the Zephyr OS from other projects that use a license
85 context and approved by the Zephyr governing board.
89 the Zephyr community can develop products with the Zephyr Project
92 See :ref:`external-contributions` for more information about
98 :maxdepth: 1
107 The Zephyr Project follows the `Community Best Practice`_ for Copyright Notices from the Linux
112 .. code-block:: C
114 Copyright The Zephyr Project Contributors
117 https://www.linuxfoundation.org/blog/copyright-notices-in-open-source-software-projects/
124 To make a good faith effort to ensure licensing criteria are met, the Zephyr
130 later in this document), the developer simply adds a ``Signed-off-by``
137 .. code-block:: none
162 sign-off) is maintained indefinitely and may be redistributed
166 DCO Sign-Off
169 The "sign-off" in the DCO is a "Signed-off-by:" line in each commit's log
170 message. The Signed-off-by: line must be in the following format::
172 Signed-off-by: Your Name <your.email@example.com>
176 - ``Your Name`` with your legal name (pseudonyms, hacker handles, and the
179 - ``your.email@example.com`` with the same email address you are using to
180 author the commit (CI will fail if there is no match)
182 You can automatically add the Signed-off-by: line to your commit body using
183 ``git commit -s``. Use other commits in the zephyr git history as examples.
189 - If you are altering an existing commit created by someone else, you must add
190 your Signed-off-by: line without removing the existing one.
197 To clone the main Zephyr Project repository use the instructions in
200 This section describes the main repository's source tree. In addition to the
201 Zephyr kernel itself, you'll also find the sources for technical documentation,
205 Understanding the Zephyr source tree can help locate the code
206 associated with a particular Zephyr feature.
211 The top-level file for the CMake build system, containing a lot of the
212 logic required to build Zephyr.
215 The top-level Kconfig file, which refers to the file :file:`Kconfig.zephyr`
216 also found in the top-level directory.
223 the west command-line tool.
225 The Zephyr source tree also contains the following top-level
230 Architecture-specific kernel and system-on-chip (SoC) code.
235 * architecture-specific kernel source files
236 * architecture-specific kernel include files for private APIs
245 Zephyr technical documentation source files and tools used to
252 :ref:`devicetree <dt-guide>` source files used to describe non-discoverable
253 board-specific hardware details.
259 Architecture-independent kernel code.
265 Miscellaneous code that doesn't belong to any of the other top-level
269 Sample applications that demonstrate the use of Zephyr features.
272 Various programs and other files used to build and test Zephyr
276 Additional build scripts needed to build Zephyr.
279 Subsystems of Zephyr, including:
287 Test code and benchmarks for Zephyr features.
290 Additional architecture independent data. It currently contains Zephyr's CMake
296 .. _Zephyr Project Issues: https://github.com/zephyrproject-rtos/zephyr/issues
298 .. _open pull requests: https://github.com/zephyrproject-rtos/zephyr/pulls
304 Before starting on a patch, first check in our issues `Zephyr Project Issues`_
306 conversation on the `Zephyr devel mailing list`_ (or the `Zephyr Discord
309 similar ideas for changes or additions. Send a message to the `Zephyr devel
318 You can find all `open pull requests`_ on GitHub and open `Zephyr Project
331 For example, if your name is ``Zephyr Developer`` and your email
334 .. code-block:: console
336 git config --global user.name "Zephyr Developer"
337 git config --global user.email "z.developer@example.com"
342 address you use to sign your commits. If they don't match, the CI system will
352 compliance with Zephyr standards and facilitate the review process.
354 If in doubt, it's advisible to explore existing Pull Requests within the Zephyr
358 .. _commit-guidelines:
367 .. code-block:: none
371 [Commit message body (must be non-empty)]
373 Signed-off-by: [Your Full Name] <[your.email@address]>
380 .. code-block:: none
389 Signed-off-by: Zephyr Developer <z.developer@example.com>
392 ---------------------------
410 * ``net: ethernet:`` for Ethernet-related networking changes
426 -------------------
432 pull request will fail CI checks if you do not.
441 * **how** you know it works -- for example, which tests you ran.
447 For examples of accepted commit messages, you can refer to the Zephyr GitHub
448 `changelog <https://github.com/zephyrproject-rtos/zephyr/commits/main>`__.
451 Signed-off-by: ...
452 ------------------
457 already. Create your commit with ``git commit -s`` to add the
458 Signed-off-by: line automatically using this information.
461 Signed-off-by: line that looks like this:
463 .. code-block:: none
465 Signed-off-by: [Your Full Name] <[your.email@address]>
467 For example, if your full name is ``Zephyr Developer`` and your email
470 .. code-block:: none
472 Signed-off-by: Zephyr Developer <z.developer@example.com>
481 See the :ref:`contributor-expectations` for a more complete discussion of
485 ------------
488 …https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/autolink…
495 .. code-block:: none
502 .. code-block:: none
510 .. code-block:: none
512 Link: https://github.com/zephyrproject-rtos/zephyr/issues/<issue number>
516 Continuous Integration (CI)
519 The Zephyr Project operates a Continuous Integration (CI) system that runs on
527 CI is run on Github Actions and it uses the same tools described in the
528 `CI Tests`_ section. The CI results must be green indicating "All
529 checks have passed" before the Pull Request can be merged. CI is run when the
532 The current status of the CI run can always be found at the bottom of the
545 non-green) build.
549 Running CI Tests Locally
555 -------------------
558 compliance with Zephyr's established guidelines and best practices. The script
565 .. code-block:: bash
567 ./scripts/ci/check_compliance.py -c upstream/main..
577 -------
584 and let the project CI automatically run the :ref:`twister_script` for you.
586 If a test fails, you can check from the CI run logs how to rerun it locally,
589 .. code-block:: bash
591 west twister -p native_sim -s tests/drivers/build_all/sensor/sensors.generic_test
613 <https://scan.coverity.com/projects/zephyr>`_ website. In order to access the
614 results you have to create an account yourself. From the Zephyr project page,
618 Static analysis of the Zephyr codebase is conducted on a bi-weekly basis. GitHub
639 Update the related Github issue in the zephyr project with the details, and only close
653 When contributing to the Zephyr Project, it is also important you provide as much
657 The general GitHub workflow used by Zephyr developers uses a combination of
662 .. _Create a Fork of Zephyr:
663 https://github.com/zephyrproject-rtos/zephyr#fork-destination-box
665 #. `Create a Fork of Zephyr`_
667 right corner of the Zephyr project repo page in GitHub.)
669 #. On your development computer, change into the :file:`zephyr` folder that was
672 cd zephyrproject/zephyr
675 <https://github.com/zephyrproject-rtos/zephyr>`_ from ``origin`` to
682 git remote add origin https://github.com/<your github id>/zephyr
686 git remote -v
690 origin https://github.com/<your github id>/zephyr (fetch)
691 origin https://github.com/<your github id>/zephyr (push)
692 upstream https://github.com/zephyrproject-rtos/zephyr (fetch)
693 upstream https://github.com/zephyrproject-rtos/zephyr (push)
695 #. Create a topic branch (off of ``main``) for your work (if you're addressing
698 git checkout main
699 git checkout -b fix_comment_typo
701 Some Zephyr subsystems do development work on a separate branch from
702 ``main`` so you may need to indicate this in your checkout::
704 git checkout -b fix_out_of_date_patch origin/net
712 git add [file(s) that changed, add -p if you want to be more specific]
720 git diff --cached
724 git commit -s
726 The ``-s`` option automatically adds your ``Signed-off-by:`` to your commit
728 agreement with the :ref:`DCO`. See the :ref:`commit-guidelines` section for
731 #. Push your topic branch with your changes to your fork in your personal
734 git push origin fix_comment_typo
741 request for the ``main`` branch. The title and message from your commit
750 on your pull request at https://github.com/zephyrproject-rtos/zephyr/pulls.
754 new branch off of ``main`` and not the previous branch.)::
756 git checkout main
757 git checkout -b fix_another_issue
764 git rebase -i <offending-commit-id>^
775 git rebase --continue
779 git push --force origin fix_comment_typo
787 git fetch --all
788 git rebase --ignore-whitespace upstream/main
790 The ``--ignore-whitespace`` option stops ``git apply`` (called by rebase)
791 from changing any whitespace. Resolve the conflicts and push again::
793 git push --force origin fix_comment_typo
796 outside GitHub, and the one recommended by Zephyr, it's not the main
799 one - GitHub complains it can't find older commits. You're also not
804 #. If the CI run fails, you will need to make changes to your code in order
806 Additional information about the CI system can be found in
818 .. _git-rebase:
819 https://git-scm.com/docs/git-rebase#Documentation/git-rebase.txt---keep-base
821 #. When pushing follow-up changes, use the ``--keep-base`` option of
822 `git-rebase`_
834 #. Watch early CI results immediately after submissions and fix issues as they
837 #. Revisit PR after 1-2 hours to see the status of all CI checks, make sure all
841 sure you click the "Re-request review" button on the GitHub UI to notify
849 cases where the file is an original to Zephyr, the commit message should
856 <external-contributions>`, the commit message shall contain details regarding
857 the original project, the location of the project, the SHA-id of the origin
863 License: BSD 3-Clause
864 URL: http://www.contiki-os.org/
871 License: BSD 3-Clause
883 .. _treewide-changes:
896 A *treewide change* is defined as any change to Zephyr APIs, coding practices,
898 throughout the zephyr source code repository or can reasonably be expected to
899 do so for a wide class of external Zephyr-based source code.
905 Project maintainers should use good judgement and prioritize the Zephyr
907 Protracted disagreements can be resolved by the Zephyr Project's Technical
913 - The zephyr repository must apply the 'treewide' GitHub label to any issues or
916 - The person proposing a treewide change must create an `RFC issue
917 …<https://github.com/zephyrproject-rtos/zephyr/issues/new?assignees=&labels=RFC&template=003_rfc-pr…
921 - The project's `Architecture Working Group (WG)
922 <https://github.com/zephyrproject-rtos/zephyr/wiki/Architecture-Working-Group>`_
928 - The Architecture WG must specify the procedure for merging any PRs associated
932 - The person proposing a treewide change must email
941 - the deprecation of version 1 of the :ref:`Logging API <logging_api>` in favor
943 <https://github.com/zephyrproject-rtos/zephyr/commit/262cc55609b73ea61b5f999c6c6daaba20bc5240>`_)
944 - the removal of support for a legacy :ref:`dt-bindings` syntax
946 <https://github.com/zephyrproject-rtos/zephyr/commit/6bf761fc0a2811b037abec0c963d60b00c452acb>`_)
955 Drivers for standalone devices should use the Zephyr bus APIs (SPI, I2C...)
959 If it is not technically possible to achieve full performance using the Zephyr
963 Zephyr APIs) for all other SoCs. Every exception must be approved by the