Correct a previous mistake indicating syntax highlighting is
autoguessed.
Add recommendations and samples around languages that documentation
authors are encouraged to use.
Signed-off-by: Benjamin Cabé <benjamin@zephyrproject.org>
Add a note about requirements for specialized drivers, clarifying the
requirements about using Zephyr APIs.
Signed-off-by: Fabio Baltieri <fabiobaltieri@google.com>
Since there are multiple static analysis tools being used
now, it is better to change references for a particular one
and just point to static analysis section in the documentation.
JIRA is no longer used for tracking security issues. Update it
to Github.
Signed-off-by: Flavio Ceolin <flavio.ceolin@intel.com>
This commit fixes syntax higlighting of all the reStructuredText
snippets in the documentation guidelines by setting default
higlighting language to rst.
Signed-off-by: Benjamin Cabé <benjamin@zephyrproject.org>
The "Contributing to Zephyr" page used to be a simple table of contents
with pointers to sub-pages. This bland page was not very inviting to new
contributors, and provided little to no context as to what to expect in
each sub-section. This commit improves the landing page by implenmenting
the following changes:
- Remove auto toctree and replace with manually curated entries that
provide more context about each sub-section.
- Add a section about the Zephyr Contributor Badge.
- Add a section about getting help, with links to Discord and dev
mailing list.
Signed-off-by: Benjamin Cabé <benjamin@zephyrproject.org>
The intro of this document was starting to show its age. Simplified
some of the wording and added a reference to the documentation build
instructions.
Signed-off-by: Benjamin Cabé <benjamin@zephyrproject.org>
"Numbered steps" were dropped a long time ago in a previous revamp of
the stylesheet, so dropping instructions related to them in the
documentation guidelines.
Also remove unecessary mention to "how to build the doc" as it's
already mentioned as a note at the top of the document.
Signed-off-by: Benjamin Cabé <benjamin@zephyrproject.org>
The Python dependencies specific to building the documentation were
recently removed from the common requirements. Point users to the
documentation generation instructions and provide details on installing
the doc specific dependencies.
Signed-off-by: Keith Short <keithshort@google.com>
Zephyr scripts do not require documentation dependencies, so let's
move them from scripts/ to doc/.
Signed-off-by: Gerard Marull-Paretas <gerard.marull@nordicsemi.no>
The link to the zephyr_licensing page was broken
=> fix it.
Also add a relatively evident if to the list:
There is no need to add an entry to the licensing
list if the integrated code is Apache 2.
Signed-off-by: Alberto Escolar Piedras <alberto.escolar.piedras@nordicsemi.no>
prefix with numbers to get sorting based on usage. Most common files
issue types should come first, with bugs being at the top.
Signed-off-by: Anas Nashif <anas.nashif@intel.com>
This commit adds the "Rule A.5: C Standard Library Usage Restrictions
in Zephyr Codebase" to the coding guidelines.
The initial list of allowed non-ISO C libc functions is based on the
non-ISO C functions available in the minimal libc.
Signed-off-by: Stephanos Ioannidis <stephanos.ioannidis@nordicsemi.no>
This commit adds the "Rule A.4: C Standard Library Usage Restrictions
in Zephyr kernel" to the coding guidelines.
Signed-off-by: Stephanos Ioannidis <stephanos.ioannidis@nordicsemi.no>
Topic branches are not in widespread use and the details on how are
managed are being reworked.
Drop the topic branches reference (now being renamed "collab" branches)
from the contribution guideline and just ask to open PRs against main,
as that's the common case right now, saves first time users from having
to dig through the various branches in the repository.
Signed-off-by: Fabio Baltieri <fabiobaltieri@google.com>
Add a generic section that covers changes to the main manifest,
requiring those to have TSC approval.
Signed-off-by: Carles Cufi <carles.cufi@nordicsemi.no>
Since tools that are not software that is compiled into the final images
may have very different requirements from regular external components,
introduce a new section outlining the process and rules to introduce new
tools into the project.
Signed-off-by: Carles Cufi <carles.cufi@nordicsemi.no>
The RFC proposal documentation better belongs with the other
documentation related to contributing to the Zephyr project.
Signed-off-by: Keith Short <keithshort@google.com>
Collect up all the contributor expectations and PR requirements into a
single place. Add additional guidelines about creating small PRs and how
to break up PRs into multiple commits.
Signed-off-by: Keith Short <keithshort@google.com>
Zephyr's coding style is based on the Linux kernel coding style, which
indicates a preferred limit of 80 columns. Zephyr's .clang-format sets
the ColumnLimit to 100. Update the documentation to match the
.clang-format parameters.
Signed-off-by: Keith Short <keithshort@google.com>
The current content does have all the critical information, but you
have to read carefully to catch several important details. This makes
it less likely that people will be able to follow the rules, which
wastes maintainers' time in PRs from new contributors, since we have
to explain the details repeatedly.
Fix it by making the introduction shorter while still covering all the
bases, and adding details with more concrete examples in the following
subsections.
Keep some other text in the document up to date and fix some
cross-references as needed.
Signed-off-by: Marti Bolivar <marti.bolivar@nordicsemi.no>
Add a note about the "branch out of date" and "Update branch" GitHub
feature. That message is confusing for new users and we often see people
losing approvals and introducing merge commits with it. Adding a note
in the contribution guidelines would hopefully help some.
Signed-off-by: Fabio Baltieri <fabiobaltieri@google.com>
There hasn't been any topic branch in widespread use. This point is
still relevant for backports or some advanced usage, but since this list
is meant to help contributor approaching the project it may be a good
idea to drop the point and make the list a tiny bit shorter and less
intimidating.
Instead, mention that main should be used "if unsure" in the previous
point.
Signed-off-by: Fabio Baltieri <fabiobaltieri@google.com>
This pull request documents additional requirements for treewide
changes which were discussed at the process WG (see
issue #48886 for details).
These requirements apply to especially impactful changes. They exist
both to try to make sure the changes get enough review, and to give
users a heads-up mechanism about incoming treewide changes.
Signed-off-by: Martí Bolívar <marti.bolivar@nordicsemi.no>
This commit fixes the incorrect reference to the `doc/Makefile` and
updates the text to better integrate the reference.
Signed-off-by: Stephanos Ioannidis <stephanos.ioannidis@nordicsemi.no>
This commit fixes incorrect depiction of the internal link with custom
text usage.
Signed-off-by: Stephanos Ioannidis <stephanos.ioannidis@nordicsemi.no>
This commit updates the documentation guidelines to reflect the
refactored documentation paths.
It also corrects the unnecessary escapes of the backticks.
Signed-off-by: Stephanos Ioannidis <stephanos.ioannidis@nordicsemi.no>
Add the missing piece of documentation for binary blobs: the submission
process. This follows the external source code process relatively close,
but it is relatively simpler.
The proposal includes a new issue template for requesting inclusion of
blob(s) for a particular module.
Fixes#7516.
Signed-off-by: Carles Cufi <carles.cufi@nordicsemi.no>
From a user perspective, it doesn't really matter that west blobs is
an extension. And again from a user perspective, the fact that the
command is called "blobs" is much more important than knowing that
it's an extension. Similarly, the fact that we host it in zephyr and
why isn't super relevant.
Re-work the docs so that we refer to the command as "west blobs"
instead of "a/the west extension" or "west", for ease of reading.
Signed-off-by: Martí Bolívar <marti.bolivar@nordicsemi.no>
Extend the existing documentation by documenting the command itself and
the format of the module.yml blobs section.
Signed-off-by: Carles Cufi <carles.cufi@nordicsemi.no>
Prefer clang-format over uncrustify for source code formatting.
uncrustify configuration files will be removed in future commits.
Signed-off-by: Gerard Marull-Paretas <gerard.marull@nordicsemi.no>
Add rule based page hooks to allow to jump to
the respective rule in a webbrowser directly.
Example:
.../coding_guidelines/index.html#misrac-rule-2-2
Signed-off-by: Roman Kellner <rkellner@baumer.com>
It is quite confusing to describe Zephyr's source tree layout in the
section for application development, given that applications do not need
to follow the exact same layout as the main tree.
Instead move this section to the contribution guidelines chapter.
Signed-off-by: Carles Cufi <carles.cufi@nordicsemi.no>
The layout of this table unreasonably assigns narrow widths for
for column(s) with lots of content, and wise-versa.
Define relative column widths to be more in sync with column
content. This will potentially produce more compact table, making
it more readable, clearer and more visually pleasing.
Signed-off-by: Aleksandar Markovic <aleksandar.markovic.sa@gmail.com>
Rework the contribution guide's Signed-off-by: language to be clearer
and reflect the TSC guidance that legal names are required. Also
clarify that existing s-o-b lines should be preserved.
Signed-off-by: Martí Bolívar <marti.bolivar@nordicsemi.no>
Recently we started to use Parasoft Codescan Static Analysis tool
to fix MISRA violations and align code to follow our Coding Guidelines.
I started fixing violations, and adding suppression tages to fix
false-positive findings. Developers started to ask me, what I'm doing
here and where is the documentation page about that.
Add a new section describing violations fixing process using Parasoft
tool.
Signed-off-by: Maksim Masalski <maksim.masalski@intel.com>
Updates wording in Coding Guidelines page to remove outdated timelines
and correct the criteria for each stage. Changes reflect that we are
in stage 1 and will not reach stage 2 until the CI for enforcing
coding guidelines has been established.
Signed-off-by: Lauren Murphy <lauren.murphy@intel.com>
After the Technical Steering Committee decided to approve the transition
from Slack to Discord, it is necessary to update all the documentation
to reflect this change.
Signed-off-by: Carles Cufi <carles.cufi@nordicsemi.no>
This guideline seems to be missed during the Zephyr's code guideline
creation. That is a good guideline that aims to address some problems
like double free or freeing not allocated memory.
Signed-off-by: Flavio Ceolin <flavio.ceolin@intel.com>
This guideline address three undefined behaviors listed in the C99
standard. Although Zephyr does not support/implement these functions,
they are part of the C library and could be implemented in the future.
Also this is mandatory rule in MISRA-C and if one day Zephyr decides to
claim compliance with MISRA-C this guideline has to be followed.
Signed-off-by: Flavio Ceolin <flavio.ceolin@intel.com>
Add a link to best practices about copyright notices and when to and
when not to change them or add them.
Fixes#6777
Signed-off-by: Anas Nashif <anas.nashif@intel.com>
Now that we use 'main' for git development, update the docs to reflect
or point there instead of 'master'.
Signed-off-by: Kumar Gala <kumar.gala@linaro.org>
The current location makes no sense because this is for users, not
contributors. Put it in the GSG since a previous attempt to restore
its location under the user guides was rejected in favor of this
location.
Signed-off-by: Martí Bolívar <marti.bolivar@nordicsemi.no>
We have been adding process related docs in different places.
Consolidate them under one section in the docs and rename the top level
section to reflect that.
Signed-off-by: Anas Nashif <anas.nashif@intel.com>
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>
The Maintairs file will be used to replace the code owners file and will
be used to add reviewers (collaborators + maintainers of affected
areas).
Signed-off-by: Anas Nashif <anas.nashif@intel.com>
Updates the contribution guidelines to document the current board policy
of rejecting non-OSI-approved licenses.
Signed-off-by: Maureen Helm <maureen.helm@nxp.com>
Add a small section that describes the existance of the coding
guidelines page and links to it, in order to raise awareness of the
effort towards complying with those.
Signed-off-by: Carles Cufi <carles.cufi@nordicsemi.no>
Add a link to the page describing our development
processes, as it contains the description of how
to identify issues and pull requests as stale.
Signed-off-by: Ioannis Glaropoulos <Ioannis.Glaropoulos@nordicsemi.no>
Add a small section, clarifying the policies around modifying
contributions submitted by other developers.
Signed-off-by: Ioannis Glaropoulos <Ioannis.Glaropoulos@nordicsemi.no>
Add a small paragraph in the Contribution Guidelines
documentation to stress that cherry-picking of patches
into other pull requests is an allowed practive. Add a
link to additional documentation clarifying policies
around modifying patches of other developers.
Signed-off-by: Ioannis Glaropoulos <Ioannis.Glaropoulos@nordicsemi.no>
We modify the content around the Release Team formation,
and maintenance, describing in detail how maintainers
may be added to the team. Add a comment about Release
Managers that stresses that they must be members of the
team. Add details on how the TSC shall ensure a functional
release team. Add details on how the release team will
be picking release managers (cadence and selection process).
Signed-off-by: Ioannis Glaropoulos <Ioannis.Glaropoulos@nordicsemi.no>
We add a section that clarifies how the project
roles may be removed. We stress that the rules
will apply to elected project roles that the TSC
may define in the future.
Signed-off-by: Ioannis Glaropoulos <Ioannis.Glaropoulos@nordicsemi.no>
We need to clarify how Maintainers may become voting
TSC member, and direct this to the Charter guidelines.
Signed-off-by: Ioannis Glaropoulos <Ioannis.Glaropoulos@nordicsemi.no>
Add a link and a note about the Project Roles' documentation in
contribute/index.rst.
Signed-off-by: Ioannis Glaropoulos <Ioannis.Glaropoulos@nordicsemi.no>
Add initial version of Project Roles documentation.
The initial version contains the content that has
already been approved by the TSC on Feb 5, 2020.
Signed-off-by: Ioannis Glaropoulos <Ioannis.Glaropoulos@nordicsemi.no>
Clarify the roles and responsibilities of the Zephyr community
and contributors with respect to PRs, Bugs, and Features.
Signed-off-by: David Leach <david.leach@nxp.com>
A few new contributors, after reading the uncrustify section
of the contribution guidelines, have decided to run
existing Zephyr files thru uncrustify, and include in commits
with minor fixes lots of styles changes.
This is something we do not want to encourage.
To avoid this, modify a bit the uncrustify section to
discourage people from doing just that.
Signed-off-by: Alberto Escolar Piedras <alpi@oticon.com>
builds@lists.zephyrproject.org archives the CI build results for every
and nightly build. Add references to this in the contribution
guidelines and introduction (pulled from README).
Also added a reference to the "Asking for Help" doc (there was a note to
add this once that doc was merged).
Fixes: #15652
Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
Zephyr requires braces on every code block that a keyword introduces, so
list the complete set in the documentation.
Signed-off-by: Carles Cufi <carles.cufi@nordicsemi.no>
The command `recheck` was always experimental and should not be part of
the contribution guidelines and flow. It is not working now, so remove
it from the docs.
Signed-off-by: Anas Nashif <anas.nashif@intel.com>
