421 lines
16 KiB
ReStructuredText
421 lines
16 KiB
ReStructuredText
.. _dev-environment-and-tools:
|
|
|
|
Development Environment and Tools
|
|
#################################
|
|
|
|
Code Review
|
|
************
|
|
|
|
GitHub is intended to provide a framework for reviewing every commit before it
|
|
is accepted into the code base. Changes, in the form of Pull Requests (PR) are
|
|
uploaded to GitHub but don't actually become a part of the project until they've
|
|
been reviewed, passed a series of checks (CI), and are approved by maintainers.
|
|
GitHub is used to support the standard open source practice of submitting
|
|
patches, which are then reviewed by the project members before being applied to
|
|
the code base.
|
|
|
|
Pull requests should be appropriately :ref:`labeled<gh_labels>`,
|
|
and linked to any relevant :ref:`bug or feature tracking issues<bug_reporting>`
|
|
.
|
|
|
|
The Zephyr project uses GitHub for code reviews and Git tree management. When
|
|
submitting a change or an enhancement to any Zephyr component, a developer
|
|
should use GitHub. GitHub Actions automatically assigns a responsible reviewer
|
|
on a component basis, as defined in the :zephyr_file:`MAINTAINERS.yml` file
|
|
stored with the code tree in the Zephyr project repository. A limited set of
|
|
release managers are allowed to merge a pull request into the main branch once
|
|
reviews are complete.
|
|
|
|
.. _review_time:
|
|
|
|
Give reviewers time to review before code merge
|
|
================================================
|
|
|
|
The Zephyr project is a global project that is not tied to a certain geography
|
|
or timezone. We have developers and contributors from across the globe. When
|
|
changes are proposed using pull request, we need to allow for a minimal review
|
|
time to give developers and contributors the opportunity to review and comment
|
|
on changes. There are different categories of changes and we know that some
|
|
changes do require reviews by subject matter experts and owners of the subsystem
|
|
being changed. Many changes fall under the "trivial" category that can be
|
|
addressed with general reviews and do not need to be queued for a maintainer or
|
|
code-owner review. Additionally, some changes might require further discussions
|
|
and a decision by the TSC or the Security working group. To summarize the above,
|
|
the diagram below proposes minimal review times for each category:
|
|
|
|
|
|
.. figure:: pull_request_classes.png
|
|
:align: center
|
|
:alt: Pull request classes
|
|
:figclass: align-center
|
|
|
|
Pull request classes
|
|
|
|
Workflow
|
|
---------
|
|
|
|
- An author of a change can suggest in his pull-request which category a change
|
|
should belong to. A project maintainers or TSC member monitoring the inflow of
|
|
changes can change the label of a pull request by adding a comment justifying
|
|
why a change should belong to another category.
|
|
- The project will use the label system to categorize the pull requests.
|
|
- Changes should not be merged before the minimal time has expired.
|
|
|
|
Categories/Labels
|
|
-----------------
|
|
|
|
Hotfix
|
|
++++++
|
|
|
|
Any change that is a fix to an issue that blocks developers from doing their
|
|
daily work, for example CI breakage, Test breakage, Minor documentation fixes
|
|
that impact the user experience.
|
|
|
|
Such fixes can be merged at any time after they have passed CI checks. Depending
|
|
on the fix, severity, and availability of someone to review them (other than the
|
|
author) they can be merged with justification without review by one of the
|
|
project owners.
|
|
|
|
Trivial
|
|
+++++++
|
|
|
|
Trivial changes are those that appear obvious enough and do not require maintainer or code-owner
|
|
involvement. Such changes should not change the logic or the design of a
|
|
subsystem or component. For example a trivial change can be:
|
|
|
|
- Documentation changes
|
|
- Configuration changes
|
|
- Minor Build System tweaks
|
|
- Minor optimization to code logic without changing the logic
|
|
- Test changes and fixes
|
|
- Sample modifications to support additional configuration or boards etc.
|
|
|
|
Maintainer
|
|
+++++++++++
|
|
|
|
Any changes that touch the logic or the original design of a subsystem or
|
|
component will need to be reviewed by the code owner or the designated subsystem
|
|
maintainer. If the code changes is initiated by a contributor or developer other
|
|
than the owner the pull request needs to be assigned to the code owner who will
|
|
have to drive the pull request to a mergeable state by giving feedback to the
|
|
author and asking for more reviews from other developers.
|
|
|
|
Security
|
|
+++++++++++
|
|
|
|
Changes that appear to have an impact to the overall security of the system need
|
|
to be reviewed by a security expert from the security working group.
|
|
|
|
TSC and Working Groups
|
|
++++++++++++++++++++++
|
|
|
|
Changes that introduce new features or functionality or change the way the
|
|
overall system works need to be reviewed by the TSC or the responsible Working
|
|
Group. For example for :ref:`breaking API changes <breaking_api_changes>`, the
|
|
proposal needs to be presented in the Architecture meeting so that the relevant
|
|
stakeholders are made aware of the change.
|
|
|
|
A Pull-Request should have an Assignee
|
|
=======================================
|
|
|
|
- An assignee to a pull request should not be the same as the
|
|
author of the pull-request
|
|
- An assignee to a pull request is responsible for driving the
|
|
pull request to a mergeable state
|
|
- An assignee is responsible for dismissing stale reviews and seeking reviews
|
|
from additional developers and contributors
|
|
- Pull requests should not be merged without an approval by the assignee.
|
|
|
|
Pull Request should not be merged by author without review
|
|
===========================================================
|
|
|
|
All pull requests need to be reviewed and should not be merged by the author
|
|
without a review. The following exceptions apply:
|
|
|
|
- Hot fixes: Fixing CI issues, reverts, and system breakage
|
|
- Release related changes: Changing version file, applying tags and release
|
|
related activities without any code changes.
|
|
|
|
Developers and contributors should always seek review, however there are cases
|
|
when reviewers are not available and there is a need to get a code change into
|
|
the tree as soon as possible.
|
|
|
|
Reviewers shall not 'Request Changes' without comments or justification
|
|
=======================================================================
|
|
|
|
Any change requests (-1) on a pull request have to be justified. A reviewer
|
|
should avoid blocking a pull-request with no justification. If a reviewer feels
|
|
that a change should not be merged without their review, then: Request change
|
|
of the category: for example:
|
|
|
|
- Trivial -> Maintainer
|
|
- Assign Pull Request to yourself, this will mean that a pull request should
|
|
not be merged without your approval.
|
|
|
|
|
|
Pull Requests should have at least 2 approvals before they are merged
|
|
======================================================================
|
|
|
|
A pull-request shall be merged only with two positive reviews (approval). Beside
|
|
the person merging the pull-request (merging != approval), two additional
|
|
approvals are required to be able to merge a pull request. The person merging
|
|
the request can merge without approving or approve and merge to get to the 2
|
|
approvals required.
|
|
|
|
Reviewers should keep track of pull requests they have provided feedback to
|
|
===========================================================================
|
|
|
|
If a reviewer has requested changes in a pull request, he or she should monitor
|
|
the state of the pull request and/or respond to mention requests to see if his
|
|
feedback has been addressed. Failing to do so, negative reviews shall be
|
|
dismissed by the assignee or an owner of the repository. Reviews will be
|
|
dismissed following the criteria below:
|
|
|
|
- The feedback or concerns were visibly addressed by the author
|
|
- The reviewer did not revisit the pull request after 2 week and multiple pings
|
|
by the author
|
|
- The review is unrelated to the code change or asking for unjustified
|
|
structural changes such as:
|
|
|
|
- Split the PR
|
|
- Can you fix this unrelated code that happens to appear in the diff
|
|
- Can you fix unrelated issues
|
|
- Etc.
|
|
|
|
Closing Stale Issues and Pull Requests
|
|
=======================================
|
|
|
|
- The Pull requests and issues sections on Github are NOT discussion forums.
|
|
They are items that we need to execute and drive to closure.
|
|
Use the mailing lists for discussions.
|
|
- In case of both issues and pull-requests the original poster needs to respond
|
|
to questions and provide clarifications regarding the issue or the change.
|
|
After one week without a response to a request, a second attempt to elicit
|
|
a response from the contributor will be made. After one more week without a
|
|
response the item may be closed (draft and DNM tagged pull requests are
|
|
excluded).
|
|
|
|
Continuous Integration
|
|
***********************
|
|
|
|
All changes submitted to GitHub are subject to tests that are run on
|
|
emulated platforms and architectures to identify breakage and regressions that
|
|
can be immediately identified. Testing using Twister additionally performs build tests
|
|
of all boards and platforms. Documentation changes are also verified
|
|
through review and build testing to verify doc generation will be successful.
|
|
|
|
Any failures found during the CI test run will result in a negative review
|
|
assigned automatically by the CI system.
|
|
Developers are expected to fix issues and rework their patches and submit again.
|
|
|
|
The CI infrastructure currently runs the following tests:
|
|
|
|
- Run ``checkpatch`` for code style issues (can vote -1 on errors; see note)
|
|
- Gitlint: Git commit style based on project requirements
|
|
- License Check: Check for conflicting licenses
|
|
- Run ``twister`` script
|
|
|
|
- Run kernel tests in QEMU (can vote -1 on errors)
|
|
- Build various samples for different boards (can vote -1 on errors)
|
|
|
|
- Verify documentation builds correctly.
|
|
|
|
.. note::
|
|
|
|
``checkpatch`` is a Perl script that uses regular expressions to
|
|
extract information that requires a C language parser to process
|
|
accurately. As such it sometimes issues false positives. Known
|
|
cases include constructs like:
|
|
|
|
.. code-block:: c
|
|
|
|
static uint8_t __aligned(PAGE_SIZE) page_pool[PAGE_SIZE * POOL_PAGES];
|
|
IOPCTL_Type *base = config->base;
|
|
|
|
Both lines produce a diagnostic regarding spaces around the ``*``
|
|
operator: the first is misidentified as a pointer type declaration
|
|
that would be correct as ``PAGE_SIZE *POOL_PAGES`` while the second
|
|
is misidentified as a multiplication expression that would be correct
|
|
as ``IOPCTL_Type * base``.
|
|
|
|
Maintainers can override the -1 in cases where the CI infrastructure
|
|
gets the wrong answer.
|
|
|
|
|
|
.. _gh_labels:
|
|
|
|
Labeling issues and pull requests in GitHub
|
|
*******************************************
|
|
|
|
The project uses GitHub issues and pull requests (PRs) to track and manage
|
|
daily and long-term work and contributions to the Zephyr project. We use
|
|
GitHub **labels** to classify and organize these issues and PRs by area, type,
|
|
priority, and more, making it easier to find and report on relevant items.
|
|
|
|
All GitHub issues or pull requests must be appropriately labeled.
|
|
Issues and PRs often have multiple labels assigned,
|
|
to help classify them in the different available categories.
|
|
When reviewing a PR, if it has missing or incorrect labels, maintainers shall
|
|
fix it.
|
|
|
|
This saves us all time when searching, reduces the chances of the PR or issue
|
|
being forgotten, speeds up reviewing, avoids duplicate issue reports, etc.
|
|
|
|
These are the labels we currently have, grouped by applicability:
|
|
|
|
Labels applicable to issues only
|
|
================================
|
|
|
|
.. list-table::
|
|
:header-rows: 1
|
|
|
|
* - Label
|
|
- Description
|
|
|
|
* - :guilabel:`priority: {high|medium|low}`
|
|
- To classify the impact and importance of a bug or
|
|
:ref:`feature <feature-tracking>`.
|
|
|
|
Note: Issue priorities are generally set or changed during the bug-triage or TSC
|
|
meetings.
|
|
|
|
* - :guilabel:`Regression`
|
|
- Something, which was working, but does not anymore (bug subtype).
|
|
|
|
* - :guilabel:`Enhancement`
|
|
- Changes/Updates/Additions to existing :ref:`features <feature-tracking>`.
|
|
|
|
* - :guilabel:`Feature request`
|
|
- A request for a new :ref:`feature <feature-tracking>`.
|
|
|
|
* - :guilabel:`Feature`
|
|
- A :ref:`planned feature<feature-tracking>` with a milestone.
|
|
|
|
* - :guilabel:`Hardware Support`
|
|
- Covers porting an existing feature (including Zephyr itself) to new hardware.
|
|
|
|
* - :guilabel:`Duplicate`
|
|
- This issue is a duplicate of another issue (please specify).
|
|
|
|
* - :guilabel:`Good first issue`
|
|
- Good for a first time contributor to take.
|
|
|
|
* - :guilabel:`Release Notes`
|
|
- Issues that need to be mentioned in release notes as known issues with
|
|
additional information.
|
|
|
|
Any issue must be classified and labeled as either *Bug*, *Enhancement*, *RFC*,
|
|
*Feature*, *Feature Request* or *Hardware Support*. More information on how
|
|
feature requests are handled and become features can be found in :ref:`Feature
|
|
Tracking<feature-tracking>`.
|
|
|
|
Labels applicable to pull requests only
|
|
=======================================
|
|
|
|
The issue or PR describes a change to a stable API.
|
|
|
|
.. list-table::
|
|
:header-rows: 1
|
|
|
|
* - Label
|
|
- Description
|
|
|
|
* - :guilabel:`Hotfix`
|
|
- Fix for an issue blocking development.
|
|
|
|
* - :guilabel:`Trivial`
|
|
- Simple changes that can have shorter review time and be reviewed by anyone, i.e. typos,
|
|
straightforward one-liner bug fixes, etc.
|
|
|
|
* - :guilabel:`Maintainer`
|
|
- Maintainer review required.
|
|
|
|
* - :guilabel:`Security Review`
|
|
- To be reviewed by a security expert.
|
|
|
|
* - :guilabel:`DNM`
|
|
- This PR should not be merged (Do Not Merge). For work in progress, GitHub
|
|
"draft" PRs are preferred.
|
|
|
|
* - :guilabel:`Needs review`
|
|
- The PR needs attention from the maintainers.
|
|
|
|
* - :guilabel:`Backport`
|
|
- The PR is a backport or should be backported.
|
|
|
|
* - :guilabel:`Licensing`
|
|
- The PR has licensing issues which require a licensing expert to review it.
|
|
|
|
.. note::
|
|
For all labels applicable to PRs: Please note that the label, together with
|
|
PR complexity, affects how long a merge should be held to ensure proper
|
|
review. See :ref:`review process <review_time>` for details.
|
|
|
|
|
|
Labels applicable to both pull requests and issues
|
|
==================================================
|
|
|
|
.. list-table::
|
|
:header-rows: 1
|
|
|
|
* - Label
|
|
- Description
|
|
|
|
* - :guilabel:`area: {area-name}`
|
|
- Indicates Zephyr subsystems (e.g, :guilabel:`area: Kernel`, :guilabel:`area: I2C`,
|
|
:guilabel:`area: Memory Management`), project functions (e.g., :guilabel:`area: Debugging`,
|
|
:guilabel:`area: Documentation`, :guilabel:`area: Process`), or other categories (e.g.,
|
|
:guilabel:`area: Coding Style`, :guilabel:`area: MISRA-C`) affected by the bug or the pull request.
|
|
|
|
An area maintainer should be able to filter by an area label and find all issues
|
|
and PRs which relate to that area.
|
|
|
|
* - :guilabel:`platform: {platform-name}`
|
|
- An issue or PR which affects only a particular platform.
|
|
|
|
* - :guilabel:`dev-review`
|
|
- The issue is to be discussed in the following `dev-review`_ if time
|
|
permits.
|
|
|
|
.. _`dev-review`: https://github.com/zephyrproject-rtos/zephyr/wiki/Zephyr-Committee-and-Working-Group-Meetings#zephyr-dev-meeting
|
|
|
|
* - :guilabel:`TSC`
|
|
- TSC stands for Technical Steering Committee. The issue is to be discussed in the
|
|
following `TSC meeting`_ if time permits.
|
|
|
|
.. _`TSC meeting`: https://github.com/zephyrproject-rtos/zephyr/wiki/Zephyr-Committee-and-Working-Group-Meetings#technical-steering-committee-tsc
|
|
|
|
* - :guilabel:`Breaking API Change`
|
|
- The issue or PR describes a breaking change to a stable API. See additional information
|
|
in :ref:`breaking_api_changes`.
|
|
|
|
* - :guilabel:`bug`
|
|
- The issue is a bug, or the PR is fixing a bug.
|
|
|
|
* - :guilabel:`Coverity`
|
|
- A Coverity detected issue or its fix.
|
|
|
|
* - :guilabel:`Waiting for response`
|
|
- The Zephyr developers are waiting for the submitter to respond to a question, or
|
|
address an issue.
|
|
|
|
* - :guilabel:`Blocked`
|
|
- Blocked by another PR or issue.
|
|
|
|
* - :guilabel:`Stale`
|
|
- An issue or a PR which seems abandoned, and requires attention by the author.
|
|
|
|
* - :guilabel:`In progress`
|
|
- For PRs: is work in progress and should not be merged yet. For issues: Is being
|
|
worked on.
|
|
|
|
* - :guilabel:`RFC`
|
|
- The author would like input from the community. For a PR it should be considered
|
|
a draft.
|
|
|
|
* - :guilabel:`LTS`
|
|
- Long term release branch related.
|
|
|
|
* - :guilabel:`EXT`
|
|
- Related to an external component.
|