doc: contribute: fix heading formatting
Fixed several headings in the contribute section that were not following the documentation guidelines for headings. Signed-off-by: Grzegorz Ferenc <Grzegorz.Ferenc@nordicsemi.no>
This commit is contained in:
Grzegorz Ferenc
Alberto Escolar
parent
96c20d831e
commit
ae0ad38e6b
|
|
@ -1,7 +1,7 @@
|
|||
.. _bin-blobs:
|
||||
|
||||
Binary Blobs
|
||||
************
|
||||
############
|
||||
|
||||
In the context of an operating system that supports multiple architectures and
|
||||
many different IC families, some functionality may be unavailable without the
|
||||
|
|
@ -22,7 +22,7 @@ therefore free to create Zephyr-based downstream software which uses binary
|
|||
blobs if they cannot meet the requirements described in this page.
|
||||
|
||||
Software license
|
||||
================
|
||||
****************
|
||||
|
||||
Most binary blobs are distributed under proprietary licenses which vary
|
||||
significantly in nature and conditions. It is up to the vendor to specify the
|
||||
|
|
@ -30,7 +30,7 @@ license as part of the blob submission process. Blob vendors may impose a
|
|||
click-through or other EULA-like workflow when users fetch and install blobs.
|
||||
|
||||
Hosting
|
||||
=======
|
||||
*******
|
||||
|
||||
Blobs must be hosted on the Internet and managed by third-party infrastructure.
|
||||
Two potential examples are Git repositories and web servers managed by
|
||||
|
|
@ -40,7 +40,7 @@ The Zephyr Project does not host binary blobs in its Git repositories or
|
|||
anywhere else.
|
||||
|
||||
Fetching blobs
|
||||
==============
|
||||
**************
|
||||
|
||||
Blobs are fetched from official third-party sources by the :ref:`west blobs
|
||||
<west-blobs>` command.
|
||||
|
|
@ -76,7 +76,7 @@ Any accompanying code, including interface header files for the blobs, must be
|
|||
present in the corresponding module repository.
|
||||
|
||||
Tainting
|
||||
========
|
||||
********
|
||||
|
||||
Inclusion of binary blobs will taint the Zephyr build. The definition of
|
||||
tainting originates in the `Linux kernel
|
||||
|
|
@ -96,7 +96,7 @@ Tainting will be communicated to the user in the following manners:
|
|||
.. _bin-blobs-types:
|
||||
|
||||
Allowed types
|
||||
=============
|
||||
*************
|
||||
|
||||
The following binary blob types are acceptable in Zephyr:
|
||||
|
||||
|
|
@ -121,7 +121,7 @@ In case of disagreement, the TSC is the arbiter of whether a particular blob
|
|||
fits in one of the above types.
|
||||
|
||||
Precompiled library-specific requirements
|
||||
=========================================
|
||||
*****************************************
|
||||
|
||||
This section contains additional requirements specific to precompiled library
|
||||
blobs.
|
||||
|
|
@ -132,14 +132,14 @@ distribution if it is discovered that the blob fails to meet these requirements
|
|||
later on.
|
||||
|
||||
Interface header files
|
||||
----------------------
|
||||
======================
|
||||
|
||||
The precompiled library must be accompanied by one or more header files,
|
||||
distributed under a non-copyleft OSI approved license, that define the interface
|
||||
to the library.
|
||||
|
||||
Allowed dependencies
|
||||
--------------------
|
||||
====================
|
||||
|
||||
This section defines requirements related to external symbols that a library
|
||||
blob requires the build system to provide.
|
||||
|
|
@ -155,7 +155,7 @@ blob requires the build system to provide.
|
|||
released under an OSI approved license and documented using Doxygen
|
||||
|
||||
Toolchain requirements
|
||||
----------------------
|
||||
======================
|
||||
|
||||
Precompiled library blobs must be in a data format which is compatible with and
|
||||
can be linked by a toolchain supported by the Zephyr Project. This is required
|
||||
|
|
@ -164,7 +164,7 @@ compiler and/or linker flags, however. For example, a porting layer may require
|
|||
special flags, or a static archive may require use of specific linker flags.
|
||||
|
||||
Limited scope
|
||||
-------------
|
||||
=============
|
||||
|
||||
Allowing arbitrary library blobs carries a risk of degrading the degree to
|
||||
which the upstream Zephyr software distribution is open source. As an extreme
|
||||
|
|
@ -188,7 +188,7 @@ At the discretion of the release team, the project may remove support for a
|
|||
hardware target if it cannot pass this test suite.
|
||||
|
||||
Support and maintenance
|
||||
=======================
|
||||
***********************
|
||||
|
||||
The Zephyr Project is not expected to be responsible for the maintenance and
|
||||
support of contributed binary blobs. As a consequence, at the discretion of the
|
||||
|
|
@ -226,7 +226,7 @@ regularly scheduled execution of the CI infrastructure.
|
|||
.. _blobs-process:
|
||||
|
||||
Submission and review process
|
||||
=============================
|
||||
*****************************
|
||||
|
||||
For references to binary blobs to be included in the project, they must be
|
||||
reviewed and accepted by the Technical Steering Committee (TSC). This process is
|
||||
|
|
|
|||
|
|
@ -3,9 +3,6 @@
|
|||
Contributor Expectations
|
||||
########################
|
||||
|
||||
Overview
|
||||
********
|
||||
|
||||
The Zephyr project encourages :ref:`contributors <contributor>` to submit
|
||||
changes as smaller pull requests. Smaller pull requests (PRs) have the following
|
||||
benefits:
|
||||
|
|
@ -30,7 +27,7 @@ benefits:
|
|||
|
||||
|
||||
Defining Smaller PRs
|
||||
====================
|
||||
********************
|
||||
|
||||
- Smaller PRs should encompass one self-contained logical change.
|
||||
|
||||
|
|
@ -55,7 +52,7 @@ Defining Smaller PRs
|
|||
|
||||
|
||||
Multiple Commits on a Single PR
|
||||
===============================
|
||||
*******************************
|
||||
|
||||
Contributors are further encouraged to break up PRs into multiple commits. Keep
|
||||
in mind each commit in the PR must still build cleanly and pass all the CI
|
||||
|
|
@ -72,7 +69,7 @@ the PR into multiple commits targeting these specific changes:
|
|||
#. Update the documentation
|
||||
|
||||
Large Changes
|
||||
=============
|
||||
*************
|
||||
|
||||
Large changes to the Zephyr project must submit an :ref:`RFC proposal <rfcs>`
|
||||
describing the full scope of change and future work. The RFC proposal provides
|
||||
|
|
@ -265,7 +262,7 @@ the steps below:
|
|||
.. _reviewer-expectations:
|
||||
|
||||
Reviewer Expectations
|
||||
#####################
|
||||
*********************
|
||||
|
||||
- Be respectful when commenting on PRs. Refer to the Zephyr `Code of Conduct`_
|
||||
for more details.
|
||||
|
|
|
|||
|
|
@ -1,7 +1,7 @@
|
|||
.. _external-contributions:
|
||||
|
||||
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
|
||||
|
|
@ -21,7 +21,7 @@ code analysis, testing or simulation please refer to the
|
|||
:ref:`external-tooling` section at the end of the page.
|
||||
|
||||
Software License
|
||||
================
|
||||
****************
|
||||
|
||||
.. note::
|
||||
|
||||
|
|
@ -49,7 +49,7 @@ 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
|
||||
|
|
@ -68,14 +68,14 @@ into the project:
|
|||
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
|
||||
|
|
@ -94,7 +94,7 @@ 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
|
||||
|
|
@ -104,7 +104,7 @@ thus it is not automatically subject to the requirements of the previous
|
|||
section.
|
||||
|
||||
Integration in main manifest file (west.yaml)
|
||||
+++++++++++++++++++++++++++++++++++++++++++++
|
||||
---------------------------------------------
|
||||
|
||||
Integrating external code into the main :file:`west.yml` manifest file is
|
||||
limited to code that is used by a Zephyr subsystem (libraries), by a platform,
|
||||
|
|
@ -117,7 +117,7 @@ Integrated modules will not be removed from the tree without a detailed
|
|||
migration plan.
|
||||
|
||||
Integration as optional modules
|
||||
+++++++++++++++++++++++++++++++
|
||||
-------------------------------
|
||||
|
||||
Standalone or loose integration of modules/projects without any incoming
|
||||
dependencies shall be made optional and shall be kept standalone. Optional
|
||||
|
|
@ -137,7 +137,7 @@ repository) and all sample or test code shall be maintained as part of the modul
|
|||
over time.
|
||||
|
||||
Integration as external modules
|
||||
+++++++++++++++++++++++++++++++
|
||||
-------------------------------
|
||||
|
||||
Similar to optional modules, but added to the Zephyr project as an entry in the
|
||||
documentation using a pre-defined template. This type of modules exists outside the
|
||||
|
|
@ -145,7 +145,7 @@ Zephyr project manifest with documentation instructing users and developers how
|
|||
to integrate the functionality.
|
||||
|
||||
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
|
||||
|
|
@ -157,7 +157,7 @@ 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
|
||||
|
|
|
|||
Loading…
Reference in a new issue