From ae0ad38e6b49db7a72c8a1f3fd9232212942d372 Mon Sep 17 00:00:00 2001 From: Grzegorz Ferenc Date: Tue, 28 Nov 2023 13:55:17 +0100 Subject: [PATCH] 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 --- doc/contribute/bin_blobs.rst | 26 ++++++++++----------- doc/contribute/contributor_expectations.rst | 11 ++++----- doc/contribute/external.rst | 22 ++++++++--------- 3 files changed, 28 insertions(+), 31 deletions(-) diff --git a/doc/contribute/bin_blobs.rst b/doc/contribute/bin_blobs.rst index efc25b609e17a6..14c181e4058dc1 100644 --- a/doc/contribute/bin_blobs.rst +++ b/doc/contribute/bin_blobs.rst @@ -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 ` 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 diff --git a/doc/contribute/contributor_expectations.rst b/doc/contribute/contributor_expectations.rst index aeb90c33d68e67..cba1627a1b9be3 100644 --- a/doc/contribute/contributor_expectations.rst +++ b/doc/contribute/contributor_expectations.rst @@ -3,9 +3,6 @@ Contributor Expectations ######################## -Overview -******** - The Zephyr project encourages :ref:`contributors ` 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 ` 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. diff --git a/doc/contribute/external.rst b/doc/contribute/external.rst index e602c94df09803..c154bc3a698a81 100644 --- a/doc/contribute/external.rst +++ b/doc/contribute/external.rst @@ -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