For functions returning nothing, there is no need to document
with @return, as Doxgen complains about "documented empty
return type of ...".
Signed-off-by: Daniel Leung <daniel.leung@intel.com>
Asking that a pull request restructure its commits is not
automatically an unjustified structural change. Remove it from the
list of unjustified changes. Commit structure is important for
maintaining bisectability.
Signed-off-by: Martí Bolívar <marti.bolivar@nordicsemi.no>
Create a template for nominating GitHub users for an elevated
permission levels. Update the TSC Project Roles page to reference the
nomination template and add clarity to the GitHub permissions allowed at
each level.
Signed-off-by: Keith Short <keithshort@google.com>
Add a paragraph to mention git bisect as a way to pre-analyze
regressions.
Aim is to reference this section from github issues when regressions
are reported and encourage users to do this first round of
pre-analyzis
Signed-off-by: Erwan Gouriou <erwan.gouriou@linaro.org>
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>
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>
RFC template mentioned in the doc is broken.
Fixing it to direct to the correct one.
Signed-off-by: Spoorthy Priya Yerabolu <spoorthy.priya.yerabolu@intel.com>
Action to create release when tag is pushed. This will additionally
create an SPDX file and the changelog since the last tag.
The release is created as a draft and will have to be modified by the
release engineer and published when ready.
Signed-off-by: Anas Nashif <anas.nashif@intel.com>
Add a section that summarizes the recommended
contribution workflow in zephyr modules.
Signed-off-by: Ioannis Glaropoulos <Ioannis.Glaropoulos@nordicsemi.no>
The CI style checking solution can produce false positives when it's
given code that it mis-parses, or that follows conventions it doesn't
allow. Document a couple examples, and explicitly note that
maintainers should override the -1 vote if they're encountered.
For those following along in the commit history:
static uint8_t __aligned(PAGE_SIZE) page_pool[PAGE_SIZE * POOL_PAGES];
checkpatch sees "uint8_t __aligned(PAGE_SIZE)" and infers a prototype
for a function "__aligned" that takes an unnamed parameter of type
"PAGE_SIZE". So it adds "PAGE_SIZE" as a known type name.
IOPCTL_Type *base = config->base;
This is common in driver code where the vendor HAL allows typedefs for
structure types. checkpatch was designed for an environment with
limited use of typedefs; "struct IPCTL_Type" would have been handled
properly.
Signed-off-by: Peter Bigot <peter.bigot@nordicsemi.no>
Recommend that Kconfig symbols related to deprecated features use
'DEPRECATED' in the symbol name instead of 'LEGACY'.
Signed-off-by: Kumar Gala <kumar.gala@linaro.org>
Describe how an API can be deprecated, which is via the __deprecated
keyword or by introducing a legacy Kconfig option.
Signed-off-by: Carles Cufi <carles.cufi@nordicsemi.no>
Update the feature tracking page with a couple of new categories that
have been identified as missing during the Release Readiness meetings:
- Hardware support
- Meta
Signed-off-by: Carles Cufi <carles.cufi@nordicsemi.no>
This page has a lot more information about APIs than just stability,
and I believe it's currently our only exhaustive list of APIs.
Rename it to API Overview.
Signed-off-by: Martí Bolívar <marti.bolivar@nordicsemi.no>
Move the section describing the requirements for a new API out of the
peripheral API header, clarify the requirements for upgrading an API to
experimental and unstable clearly in the corresponding sections. Add a
link to the API stability page.
Signed-off-by: Carles Cufi <carles.cufi@nordicsemi.no>
Clean up and update release tagging procedures. Use new
document tabs to separate instructions for release
candidate and final releases.
Signed-off-by: David Leach <david.leach@nxp.com>
In order to make technical progress possible, some stable APIs
may sometimes need to be modified in a non backwards-compatible way.
Describe the process for integrating such changes in the documentation.
Signed-off-by: Carles Cufi <carles.cufi@nordicsemi.no>
Remove leading/trailing blank lines in .c, .h, .py, .rst, .yml, and
.yaml files.
Will avoid failures with the new CI test in
https://github.com/zephyrproject-rtos/ci-tools/pull/112, though it only
checks changed files.
Move the 'target-notes' target in boards/xtensa/odroid_go/doc/index.rst
to get rid of the trailing blank line there. It was probably misplaced.
Signed-off-by: Ulf Magnusson <Ulf.Magnusson@nordicsemi.no>
Some incorrect indenting in the doc was causing numbered lists to reset
back to 1 instead of continuing the series.
Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
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>
There are a few non-PNG (JPEG and WebP) files that are being
name as PNG files. This causes pdflatex/latexmk to fail due
to them not actually being PNG files. So rename those files
with correct extensions and update the RST files.
Also converted the WebP file in JPEG as PDFLatex cannot parse
WebP image.
Signed-off-by: Daniel Leung <daniel.leung@intel.com>
Fix misspellings and doc issues missed during regular reviews (including
some files without a trailing newline)
Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
All docs should have a label at the top that would
permit cross-document linking via :ref:`labelname`.
Update "testing" label that would have conflicted and fix the only
reference to the old "testing" label in development process
documentation.
Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
Renamed the page "review_process.rst" to "dev_env_and_tools.rst"
as the old name did not cover all its content.
Moved the labels page content into this
"Developemnt Environment and Tools" page.
Signed-off-by: Alberto Escolar Piedras <alpi@oticon.com>
There has been some confusion about how GitHub labels
should be used.
This commit adds a new doc page, which tries to clarify this.
Signed-off-by: Alberto Escolar Piedras <alpi@oticon.com>
As discussed in the TSC meeting of 2019/03/27:
To ensure that we do not forget to remove an API 2 releases later
and to provide a bit better visibility about when the removal
is planned, require that a GH issue be created, and that this
issue be added to the roadmap for the apropriate release.
As a free bonus:
Removed a redundant line in the list and added one missing article.
Signed-off-by: Alberto Escolar Piedras <alpi@oticon.com>
Add a note in the tagging section of the release process that explains
why using GitHub release process for tags should NOT be done.
Fixes#14985
Signed-off-by: Kumar Gala <kumar.gala@linaro.org>
Linking to API material requires knowing the pecularities of how
doxygen, sphinx, and breathe work. In an attempt to hide some of this
we're preparing the current docs to allow use of configuration defaults
that will let us more simply use a default role that will hunt for a
reference target in the various domains that are available by using a
default "role" of "all". This will let us use the simple notation
`functionname` or `typename` without fully specifying the reference as
:c:func:`functionname`.
This patch cleans up exising docs that were (incorrectly) using single
backtics where double backtics should have been used, and also found
some typos (such as a space between the role name and the reference,
such as :file: `filename`, and a missing colon such as
c:func:`functionname`)
This is a start to address issue #14313
Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
A new role :zephyr_file: is available that renders to a link to the file
or folder in GitHub. Find appropriate references using :file: and
convert to :zephyr_file: to take advantage of its linking capability.
Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
Nazar Kazakov