Move some of the historical safety related language and
enforcement strategy re coding guidelines to the safety section.
The coding guidelines are and have been in effect for a while now,
but it seems this introduction text is confusing contributors.
Signed-off-by: Anas Nashif <anas.nashif@intel.com>
This change was triggered by a review comment linked below:
https://github.com/zephyrproject-rtos/zephyr/pull/83117#issuecomment-2549120181
It extends the current Reviewer Expectations with additional rules
agreed upon by multiple Zephyr contributors in order to simplify and
standardize the decision-making process during PR reviews.
Signed-off-by: Carles Cufi <carles.cufi@nordicsemi.no>
Signed-off-by: Anas Nashif <anas.nashif@intel.com>
Clarify and extend some of the PR and contribution guidelines so that
they cover practices that have been effectively enforced by maintainers,
but were never properly documented.
Signed-off-by: Carles Cufi <carles.cufi@nordicsemi.no>
Signed-off-by: Anas Nashif <anas.nashif@intel.com>
scripts/checkpatch.pl was written originally for the Linux kernel, and
its code reflects the kernel's coding style. In particular, it has
checks for unneeded braces around single-statement if/else/for/while
conditions. In Zephyr however, braces are always required, and so the
checks needed modifying to verify the opposite condition.
In order to enable the now-compatible checks, we also remove the
--ignore BRACES statement in .checkpatch.conf.
Limitations: the current code works well if there are not conditional
statements (e.g. #if, #ifdef or #endif) next to the if/else/for/while
conditions. This is rarely the case, but triggers with the Bluetooth
controller in code like this:
```
#if defined(CONFIG_BT_PERIPHERAL)
if (!lll->is_hdcd)
#endif /* CONFIG_BT_PERIPHERAL */
{
```
```
} else
#endif /* CONFIG_BT_CTLR_PRIVACY */
{
```
```
#if defined(CONFIG_BT_CTLR_DF_ADV_CTE_TX)
if (lll->cte_started) {
radio_switch_complete(phy_s, 0, phy_s, 0);
} else
#endif /* CONFIG_BT_CTLR_DF_ADV_CTE_TX */
{
```
```
#ifdef DUAL_BANK
while ((FLASH_STM32_REGS(dev)->SR1 & FLASH_SR_QW) ||
(FLASH_STM32_REGS(dev)->SR2 & FLASH_SR_QW))
#else
while (FLASH_STM32_REGS(dev)->SR1 & FLASH_SR_QW)
#endif
{
```
Signed-off-by: Carles Cufi <carles.cufi@nordicsemi.no>
Refrain from using Escalation language when requesting review and
getting awareness from maintainers.
Signed-off-by: Anas Nashif <anas.nashif@intel.com>
Utilize a code spell-checking tool to scan for and correct spelling errors
in various files within the `doc` directory.
Signed-off-by: Pisit Sawangvonganan <pisit@ndrsolution.com>
.. target-notes:: is a useful directive that needs to explicitly be
included for a "References" section to really be useful. This commit
updates the doc guidelines accordingly to help ensure that future docs
are using it correctly.
Signed-off-by: Benjamin Cabé <benjamin@zephyrproject.org>
This updates the documentation of all the Seeed Studio boards to use
the new `zephyr:board::` directive.
Signed-off-by: Benjamin Cabé <benjamin@zephyrproject.org>
A new zephyr:board:: Sphinx directive allows to flag a documentation
page as being the documentation for a specific board, allowing to
auto-populate some of the contents, ex. by adding a board overview a la
Wikipedia, and later things like supported HW features, etc.
A corresponding :zephyr:board: role allows to link to a board doc page.
Signed-off-by: Benjamin Cabé <benjamin@zephyrproject.org>
Due to the (potentially) hard to understand effects of blobs, it seems
prudent to make their presence more noticeable.
Hopefully, this will make it easier to identify issues (such as those
reported on GitHub) that have been observed on devices running a tainted
build.
Signed-off-by: Reto Schneider <reto.schneider@husqvarnagroup.com>
While not visible in the rendered documentation, double spaces look bad
when reading plaintext file.
Signed-off-by: Reto Schneider <reto.schneider@husqvarnagroup.com>
This commit adds support for generating an interactive catalog of all
the supported boards that can be included in the documentation using
the `.. zephyr:board-catalog::` directive.
Signed-off-by: Benjamin Cabé <benjamin@zephyrproject.org>
Fixes 78713
Add instructions to the "Git Setup" section to ensure that the user's
GitHub profile name is their full name (first and last) and that the
GitHub profile name and email address match the git config user.name
and user.email.
Page: contribute/guidelines
Tested with:
ninja html
python3 -m http.server 8000
Signed-off-by: Arrel Neumiller <rlneumiller@gmail.com>
This commit adds support for categorizing code samples in the
documentation.
It introduces two new directives:
- `zephyr:code-sample-category::` to create a category and associated
brief description, that implicitly acts as a toctree too.
- `zephyr:code-sample-listing::` to allow dumping a list of samples
corresponding to a category anywhere in the documentation.
Fixes#62453.
Signed-off-by: Benjamin Cabé <benjamin@zephyrproject.org>
- Improved document structure (was *very* flat before) by adding more
meaningful top-level headings and re-ordering some of the existing
sections
- Provide detailed and structured docs for all the custom Sphinx roles
and directives available in Zephyr, including moving the docs for
``.. zephyr-app-commands`` directive and `:dtcompatible:` roles away
from the extensions' source files to align with how Sphinx typically
handles docs for custom roles/directives.
- Added more content regarding diagrams guidelines, images,
cross-referencing of Doxygen documentation, ...
Signed-off-by: Benjamin Cabé <benjamin@zephyrproject.org>
Commit 204860857e (PR #41061) dropped
support for "any" as the default role, so this should be dropped from
the documentation guidelines as well.
Signed-off-by: Benjamin Cabé <benjamin@zephyrproject.org>
Fixes bad usage of single backticks in lieu of double backticks for
rendering inline literals, or simple '*' for italics.
When appropriate, a better construct than double backticks has been
selected (ex. :file:, :kconfig:option:, :c:func:, ...), or proper :ref:
have been used if the original intention was to have a link.
Signed-off-by: Benjamin Cabé <benjamin@zephyrproject.org>
This link probably never worked. This commit fixes the relative
URL to properly point to where Doxygen docs live.
Fixes#78016.
Signed-off-by: Benjamin Cabé <benjamin@zephyrproject.org>
Add two new commands that automatically locally host the generated
documentation upon completion and rebuild/rehost when the input files
change without any user interaction.
For more info see: https://pypi.org/project/sphinx-autobuild/
Signed-off-by: Jordan Yates <jordan@embeint.com>
Refactor the guidelines rule table and add a zephyr rule number
to make it more clear that the coding guideline rules are a
subset of the MISRA-C:2012 rules.
Signed-off-by: Simon Hein <Shein@baumer.com>
Commit 698a0c3193 changed the bluetooth_api
section title, which made the reference in the Coding guidelines turn into
"API", which is confusing.
Use a fixed title for that reference to fix the issue.
Signed-off-by: Mathieu Choplain <mathieu.choplain@st.com>
Remove the references to the breathe extension in the
Schematic of the documentation build process graph and
the filtering expected warnings section.
Signed-off-by: Simon Hein <Shein@baumer.com>
The project charter has apparently changed location on
the main zephyrproject.org website.
This fixes a couple occurences of the old URL.
fixes#76433
Signed-off-by: Benjamin Cabé <benjamin@zephyrproject.org>
Make a PR description an expectation/requirement for
pull requests submitted to the zephyr project.
Signed-off-by: Declan Snyder <declan.snyder@nxp.com>
Remove references to a timline for the coding guidelines enforcement
stages. Mark the current stage better and add notes about the
current stage.
Signed-off-by: Simon Hein <Shein@baumer.com>
Our documentation uses image formats such as WebP that are not supported
by LaTeX. This commit enables Sphinx's sphinx.ext.imageconverter
extension, and updates the documentation to indicate ImageMagick is
required to build docs.
Signed-off-by: Benjamin Cabé <benjamin@zephyrproject.org>
Restructure the Contribution Guidelines page in the documentation.
Create the 'Pull Request Guidelines' section containing the best
practices for creating Pull Requests.
Improve commit message guidelines: instruct contributors to refer to
GitHub issue in the PR message instead of commit message when
submitting a fix; add a description of `Link:` tags for refering to
other relevant information.
Move 'clang-format' and 'twister' subsections to the new PR
Guidelines section.
Delete outdated/incorrect information about how to run tests locally
with twister.
Describe the `check_compliance.py` script as the recommended tool for
checking compliance of changes and how to run the script locally.
Remove 'gitlint' subsection.
Add a list of recommended steps for getting a new PR accepted quickly.
Signed-off-by: Gustavo Silva <gustavograzs@gmail.com>
Clarification of reviewer expectations and role. Emphasis
on clarifying when a PR can be closed.
Highlighting reviewers and assignee objective to guide PR
to a mergeable state, if possible.
Signed-off-by: David Leach <david.leach@nxp.com>
- Adds -U upgrade flag to the install requirements command.
- Fixes a possible documentation generation issue,
reported in https://github.com/zephyrproject-rtos/zephyr/issues/73082
Signed-off-by: Andrej Butok <andrey.butok@nxp.com>
According to commit 400c1fa744 which
introduced rule A.5 to the coding guidelines, the initial exception list
was based on the non-standard function availability in minimal libc.
gmtime_r() however, has not been included to the list, although it's
present in minimal libc since 3e8df8b369.
This commit fixes this, by adding gmtime_r() to the rule A.5 exception
list.
Signed-off-by: Robert Lubos <robert.lubos@nordicsemi.no>
Rule A.5 is meant for code build with the embedded libCs and
which runs in embedded targets. Let's be more clear about this
and explicitly indicate that host tooling is not covered by it.
Otherwise, the current
"The "Zephyr codebase" in this context refers to all source
code files committed to the main Zephyr repository"
covers too much.
Signed-off-by: Alberto Escolar Piedras <alberto.escolar.piedras@nordicsemi.no>
Update the reference to the Bluetooth Appropriate Language Mapping
Tables document. The link is now the same as the Bluetooth SIG website
uses.
Signed-off-by: Johan Hedberg <johan.hedberg@intel.com>
Drop the section of the coding guidelines that's referring to Parasoft
Codescan as it's not used by the project anymore.
Signed-off-by: Benjamin Cabé <benjamin@zephyrproject.org>
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>
Sets static analysis an indispensable requirement for our project
releases.
Static analysis is not merely a tool but a proactive
strategy to unearth and address potential issues in the early stages
of development, long before they mature into critical
vulnerabilities. By scrutinizing code at rest, static analysis unveils
latent defects and potential security risks, thus bolstering the
resilience of our software against future threats.
Fixes: #64591
Signed-off-by: Flavio Ceolin <flavio.ceolin@intel.com>
