patrick/zephyr
1
0
Fork 0
Code Issues Pull requests Actions 8 Packages Projects Releases Wiki Activity

doc: contribute: Rework the process for external code inclusion

Browse source 
As per the agreements in the Process Group Meeting, rework the procedure
to include external code so that it reflects the reality of Zehyr today
with the choice between modules and integration into the main tree, and
decouple the non-Apache v2.0 license side of the question from the
process from importing 3rd-party code.

Signed-off-by: Carles Cufi <carles.cufi@nordicsemi.no>
This commit is contained in:
Carles Cufi 2021-02-17 17:31:12 +01:00 committed by Carles Cufí
parent 6c3fecd0a3
commit f938cc427e
6 changed files with 257 additions and 162 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

62
.github/ISSUE_TEMPLATE/ext-source.md vendored Normal file
View file

@ -0,0 +1,62 @@
---
name: External Source Code
about: Submit a proposal to integrate external source code
title: ''
labels: TSC
assignees: ''
---
## Origin
Name of project hosting the original open source code
Provide a link to the source
## Purpose
Brief description of what this software does
## Mode of integration
Describe whether you'd like to integrate this exernal component in the main tree
or as a module, and why. If the mode of integration is a module, suggest a
repository name for the module
## Pull Request
Pull request (if any) with the actual implementation of the integration, be it
in the main tree or as a module (pointing to your own fork for now). Make sure
the PR is correctly labeled as "DNM"
## Description
Long description that will help reviewers discuss suitability of the
component to solve the problem at hand (there may be a better options
available.)
What is its primary functionality (e.g., SQLLite is a lightweight
database)?
What problem are you trying to solve? (e.g., a state store is
required to maintain ...)
Why is this the right component to solve it (e.g., SQLite is small,
easy to use, and has a very liberal license.)
# Dependencies
What other components does this package depend on?
Will the Zephyr project have a direct dependency on the component, or
will it be included via an abstraction layer with this component as a
replaceable implementation?
## Revision
Version or SHA you would like to integrate initially
## License
Please use an SPDX identifier (https://spdx.org/licenses/), such as
``BSD-3-Clause``

50
doc/contribute/code_component_README
View file

@ -1,50 +0,0 @@
[Code Component Name]
#####################
Origin:
[Name of project hosting the original open source code]
[Provide a link to the source]
Status:
[Current version of this component, supported by Zephyr]
Purpose:
[Brief description of what this software does]
Description:
[Long description that will help reviewers discuss suitability of the
package to solve the problem at hand (there may be a better package
available.)
What is its primary functionality (e.g., SQLLite is a lightweight
database)?
What problem are you trying to solve? (e.g., a state store is
required to maintain ...)
Why is this the right package to solve it (e.g., SQLite is small,
easy to use, and has a very liberal license.)]
Dependencies:
[What other components does this package depend on? Does the software
include any dynamic or static linking, or automatic downloading of any
code?
Will the Zephyr project have a direct dependency on the component, or
will it be included via an abstraction layer with this component as a
replacable implementation?]
URL:
[location to the project's home, e.g., a github repo]
commit:
[08ded7f21529c39e5133688ffb9a9d0c94e5c6e]
Maintained-by:
[External]
License:
[use SPDX identifier (https://spdx.org/licenses/), such as BSD-3-Clause]
License Link:
[link to the project's LICENSE file, e.g., https://github.com/xyz/LICENSE]

168
doc/contribute/external.rst Normal file
View file

@ -0,0 +1,168 @@
.. _external-contributions:
Contributing source code from external projects
***********************************************
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
:ref:`external-src-process` section for more details.
.. _Zephyr governing board:
https://www.zephyrproject.org/governance/
.. _Zephyr project charter:
https://www.zephyrproject.org/wp-content/uploads/sites/38/2020/09/CLEAN-LF-Zephyr-Charter-20200624-effective-20200901.pdf
.. _Open Source Initiative (OSI):
https://opensource.org/licenses/alphabetical
By carefully reviewing potential contributions and also enforcing a :ref:`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 :ref:`coding_style`
- The code adheres to the project's :ref:`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 :ref:`module <modules>`.
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 :file:`MAINTAINERS.yaml` as part of the
process.
.. _external-src-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 :ref:`external-contributions` 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 esternal 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:
.. figure:: media/ext-src-flowchart.svg
:align: center
Submission process
.. _New External Source Code Issue:
https://github.com/zephyrproject-rtos/zephyr/issues/new?assignees=&labels=RFC&template=ext-source.md&title=

102
doc/contribute/index.rst
View file

@ -59,7 +59,7 @@ By carefully reviewing potential contributions and also enforcing a
the Zephyr community can develop products with the Zephyr Project
without concerns over patent or copyright issues.
See :ref:`contribute_non-Apache` for more information about
See :ref:`external-contributions` for more information about
this contributing and review process for imported components.
.. only:: latex
@ -685,12 +685,10 @@ 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).
In cases where the file is :ref:`imported from an external project
<external-contributions>`, 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 and the intended purpose.
For example, a copy of a locally maintained import::
@ -699,100 +697,22 @@ For example, a copy of a locally maintained import::
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::
For example, a copy of an externally maintained import in a module repository::
Origin: Tiny Crypt
License: BSD 3-Clause
URL: https://github.com/01org/tinycrypt
commit: 08ded7f21529c39e5133688ffb93a9d0c94e5c6e
Purpose: Introduction of TinyCrypt
Maintained-by: External
.. _contribute_non-Apache:
Contributing External Components
********************************
Contributing non-Apache 2.0 licensed components
***********************************************
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`_. The board will
automatically reject licenses that have not been approved by the `Open Source
Initiative (OSI)`_.
.. _Zephyr governing board:
https://www.zephyrproject.org/governance/
.. _Open Source Initiative (OSI):
https://opensource.org/licenses/alphabetical
By carefully reviewing potential contributions and also enforcing a
:ref:`DCO` for contributed code, we ensure that
the Zephyr community can develop products with the Zephyr Project
without concerns over patent or copyright issues.
Submission and review process
=============================
All contributions to the Zephyr project are submitted through GitHub
pull requests (PR) following the Zephyr Project's :ref:`Contribution workflow`.
Before you begin working on including a new component to the Zephyr
Project (Apache-2.0 licensed or not), you should start up a conversation
on the `developer mailing list <https://lists.zephyrproject.org/g/devel>`_
to see what the Zephyr community thinks about the idea. Maybe there's
someone else working on something similar you can collaborate with, or a
different approach may make the new component unnecessary.
If the conclusion is that including a new component is the best
solution, and this new component uses a license other than Apache-2.0,
these additional steps must be followed:
#. Complete a README for your code component and add it to your source
code pull request (PR). A recommended README template can be found in
:zephyr_file:`doc/contribute/code_component_README` (and included
`below`_ for reference)
#. The Zephyr Technical Steering Committee (TSC) will evaluate the code
component README as part of the PR
commit and vote on accepting it using the GitHub PR review tools.
- If rejected by the TSC, a TSC member will communicate this to
the contributor and the PR will be closed.
- If approved by the TSC, the TSC chair will forward the README 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, final review of
the PR may be made to ensure its proper placement in the
Zephyr Project :ref:`source_tree_v2`, (in the ``ext`` folder), and
inclusion in the :ref:`zephyr_licensing` document.
.. note::
External components not under the Apache-2.0 license **cannot** be
included in a Zephyr OS release without approval of both the Zephyr TSC
and the Zephyr governing board.
.. _below:
Code component README template
==============================
.. literalinclude:: code_component_README
.. toctree::
:maxdepth: 1
external.rst
Contribution Roles and Responsibilities
***************************************

3
doc/contribute/media/ext-src-flowchart.svg Normal file
View file

File diff suppressed because one or more lines are too long
Side by side

After

Width:  |  Height:  |  Size: 23 KiB

34
doc/guides/modules.rst
View file

@ -817,9 +817,6 @@ yourself, then no additional modules are added to the build. You will still be
able to build any applications that don't require code or Kconfig options
defined in an external repository.
.. _submitting_new_modules:
Submitting changes to modules
******************************
@ -842,33 +839,28 @@ Note that multiple and dependent changes to different modules can be submitted
using exactly the same process. In this case you will change multiple entries of
all modules that have a pull request against them.
.. _submitting_new_modules:
Process for submitting a new module
===================================
A request for a new module should be initialized using an RFC issue in the
Zephyr project issue tracking system with details about the module and how it
integrates into the project. If the request is approved, a new repository will
Please follow the process in :ref:`external-src-process` and obtain the TSC
approval to integrate the external source code as a module
If the request is approved, a new repository will
created by the project team and initialized with basic information that would
allow submitting code to the module project following the project contribution
guidelines.
If a module is maintained as a fork of another project on Github, the Zephyr module
related files and changes in relation to upstream need to be maintained in a
special branch named ``zephyr``.
If a module is maintained as a fork of another project on Github, the Zephyr
module related files and changes in relation to upstream need to be maintained
in a special branch named ``zephyr``.
Follow the following steps to request a new module:
#. Use `GitHub issues`_ to open an issue with details about the module to be
created
#. Propose a name for the repository to be created under the Zephyr project
organization on Github.
#. Maintainers from the Zephyr project will create the repository and initialize
it. You will be added as a collaborator in the new repository.
#. Submit the module content (code) to the new repository following the
guidelines described :ref:`here <modules_using_west>`.
#. Add a new entry to the :zephyr_file:`west.yml` with the following
information:
Maintainers from the Zephyr project will create the repository and initialize
it. You will be added as a collaborator in the new repository. Submit the
module content (code) to the new repository following the guidelines described
:ref:`here <modules_using_west>`, and then add a new entry to the
:zephyr_file:`west.yml` with the following information:
.. code-block:: console