If you need urgent consulting help click here

Contributing External Components

In some cases it is desirable to leverage existing, external source code in order to avoid re-implementing basic functionality or features that are readily available in other open source projects.

This section describes the circumstances under which external source code can be imported into Zephyr, and the process that governs the inclusion.

There are three main factors that will be considered during the inclusion process in order to determine whether it will be accepted. These will be described in the following sections.

Software License

Note

External source code licensed under the Apache-2.0 license is not subject to this section.

Integrating code into the Zephyr Project 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, as described in the Zephyr project charter. The board will automatically reject licenses that have not been approved by the Open Source Initiative (OSI). See the Submission and review process section for more details.

By carefully reviewing potential contributions and also enforcing a Developer Certification of Origin (DCO) for contributed code, we ensure that the Zephyr community can develop products with the Zephyr Project without concerns over patent or copyright issues.

Merit

Just like with any other regular contribution, one that contains external code needs to be evaluated for merit. However, in the particular case of code that comes from an existing project, there are additional questions that must be answered in order to accept the contribution. More specifically, the following will be considered by the Technical Steering Committee and evaluated carefully before the external source code is accepted into the project:

Is this the most optimal way to introduce the functionality to the project? Both the cost of implementing this internally and the one incurred in maintaining an externally developed codebase need to be evaluated.
Is the external project being actively maintained? This is particularly important for source code that deals with security or cryptography.
Have alternatives to the particular implementation proposed been considered? Are there other open source project that implement the same functionality?

Mode of integration

There are two ways of integrating external source code into the Zephyr Project, and careful consideration must be taken to choose the appropriate one for each particular case.

Integration in the main tree

The first way to integrate external source code into the project is to simply import the source code files into the main zephyr repository. This automatically implies that the imported source code becomes part of the “mainline” codebase, which in turn requires that:

The code is formatted according to the Zephyr Coding Style
The code adheres to the project’s Coding Guidelines
The code is subject to the same checks and verification requirements as the rest of the code in the main tree, including static analysis
All files contain an SPDX tag if not already present
An entry is added to the licensing page <zephyr_licensing>

This mode of integration can be applicable to both small and large external codebases, but it is typically used more commonly with the former.

Integration as a module

The second way of integrating external source code into the project is to import the whole or parts of the third-party open source project into a separate repository, and then include it under the form of a module. With this approach the code is considered as being developed externally, and thus it is not automatically subject to the requirements of the previous section.

Ongoing maintenance

Regardless of the mode of integration, external source code that is integrated in Zephyr requires regular ongoing maintenance. The submitter of the proposal to integrate external source code must therefore commit to maintain the integration of such code for the foreseeable future. This may require adding an entry in the MAINTAINERS.yml as part of the process.

Submission and review process

Before external source code can be included in the project, it must be reviewed and accepted by the Technical Steering Committee (TSC) and, in some cases, by the Zephyr governing board.

A request for external source code integration must be made by creating a new issue in the Zephyr project issue tracking system on GitHub with details about the source code and how it integrates into the project.

Follow the steps below to begin the submission process:

Make sure to read through the Contributing External Components section in detail, so that you are informed of the criteria used by the TSC and board in order to approve or reject a request
Use the New External Source Code Issue to open an issue
Fill out all required sections, making sure you provide enough detail for the TSC to assess the merit of the request. Optionally you can also create a Pull Request that demonstrates the integration of the external source code and link to it from the issue
Wait for feedback from the TSC, respond to any additional questions added as GitHub issue comments

If, after consideration by the TSC, the conclusion is that integrating external source code is the best solution, and the external source code is licensed under the Apache-2.0 license, the submission process is complete and the external source code can be integrated.

If, however, the external source code uses a license other than Apache-2.0, then these additional steps must be followed:

The TSC chair will forward the link to the GitHub issue created during the early submission process to the Zephyr governing board for further review
The Zephyr governing board has two weeks to review and ask questions:
- If there are no objections, the matter is closed. Approval can be accelerated by unanimous approval of the board before the two weeks are up
- If a governing board member raises an objection that cannot be resolved via email, the board will meet to discuss whether to override the TSC approval or identify other approaches that can resolve the objections
On approval of the Zephyr TSC and governing board the submission process is complete

The flowchart below shows an overview of the process:

Fig. 37 Submission process