doc: Rework Development Process section
- Added various contents from stale wiki pages - Added API life cycle document - Add pictures showing process in general - Split the document into multiple sections. Signed-off-by: Anas Nashif <anas.nashif@intel.com>
This commit is contained in:
Anas Nashif
parent
e66cbb68e3
commit
63d330e78b
14 changed files with 869 additions and 282 deletions
BIN
doc/development_process/api_lifecycle.png
Normal file
BIN
doc/development_process/api_lifecycle.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 56 KiB |
134
doc/development_process/api_lifecycle.rst
Normal file
134
doc/development_process/api_lifecycle.rst
Normal file
|
|
@ -0,0 +1,134 @@
|
||||||
|
.. _api_lifecycle:
|
||||||
|
|
||||||
|
API Lifecycle
|
||||||
|
#############
|
||||||
|
|
||||||
|
Developers using Zephyr's APIs need to know how long they can trust that a
|
||||||
|
given API will not change in future releases. At the same time, developers
|
||||||
|
maintaining and extending Zephyr's APIs need to be able to introduce
|
||||||
|
new APIs that aren't yet fully proven, and to potentially retire old APIs when they're
|
||||||
|
no longer optimal or supported by the underlying platforms.
|
||||||
|
|
||||||
|
|
||||||
|
.. figure:: api_lifecycle.png
|
||||||
|
:align: center
|
||||||
|
:alt: API Life Cycle
|
||||||
|
:figclass: align-center
|
||||||
|
|
||||||
|
API Life Cycle
|
||||||
|
|
||||||
|
|
||||||
|
Experimental
|
||||||
|
*************
|
||||||
|
|
||||||
|
Experimental APIs denote that a feature was introduced recently, and may change
|
||||||
|
or be removed in future versions. Try it out and provide feedback
|
||||||
|
to the community via the `Developer mailing list <https://lists.zephyrproject.org/g/devel>`_.
|
||||||
|
|
||||||
|
Peripheral APIs (Hardware Related)
|
||||||
|
==================================
|
||||||
|
|
||||||
|
When introducing an API (public header file with documentation) for a new
|
||||||
|
peripheral or driver subsystem, review of the API is enforced and is driven by
|
||||||
|
the API working group consisting of representatives from different vendors.
|
||||||
|
|
||||||
|
The following requirements apply to new APIs:
|
||||||
|
|
||||||
|
- Documentation of the API (usage)
|
||||||
|
explaining its design and assumptions, how it is to be used, current
|
||||||
|
implementation limitations, and future potential, if appropriate.
|
||||||
|
- The API introduction should be accompanied by at least one driver
|
||||||
|
implementing this API
|
||||||
|
- At least one sample using the new API
|
||||||
|
|
||||||
|
The API shall be promoted to ``unstable`` when it has at least two
|
||||||
|
implementations on different hardware platforms.
|
||||||
|
|
||||||
|
Hardware Agnostic APIs
|
||||||
|
=======================
|
||||||
|
|
||||||
|
For hardware agnostic APIs, multiple applications are required to promote an
|
||||||
|
API from ``experimental`` to ``unstable``.
|
||||||
|
|
||||||
|
|
||||||
|
Unstable
|
||||||
|
********
|
||||||
|
|
||||||
|
The API is in the process of settling, but has not yet had sufficient real-world
|
||||||
|
testing to be considered stable. The API is considered generic in nature and can
|
||||||
|
be used on different hardware platforms.
|
||||||
|
|
||||||
|
.. note::
|
||||||
|
|
||||||
|
Changes will not be announced.
|
||||||
|
|
||||||
|
Stable
|
||||||
|
*******
|
||||||
|
|
||||||
|
The API has proven satisfactory, but cleanup in the underlying code may cause
|
||||||
|
minor changes. Backwards-compatibility will be maintained if reasonable.
|
||||||
|
|
||||||
|
An API can be declared ``stable`` after fullfilling the following requirements:
|
||||||
|
|
||||||
|
- Test cases for the new API with 100% coverage
|
||||||
|
- Complete documentation in code. All public interfaces shall be documented
|
||||||
|
and available in online documentation.
|
||||||
|
- The API has been in-use and was available in at least 2 development releases
|
||||||
|
- Stable APIs can get backward compatible updates, bug fixes and security fixes
|
||||||
|
at any time.
|
||||||
|
|
||||||
|
.. note::
|
||||||
|
|
||||||
|
Incompatible changes will be announced in the release notes.
|
||||||
|
|
||||||
|
Deprecated
|
||||||
|
***********
|
||||||
|
|
||||||
|
.. note::
|
||||||
|
|
||||||
|
Unstable APIs can be removed without deprecation at any time.
|
||||||
|
|
||||||
|
The following are the requirements for deprecating an existing API:
|
||||||
|
|
||||||
|
- Deprecation Time (stable APIs): 2 Releases
|
||||||
|
The API needs to be marked as deprecated in at least two full releases.
|
||||||
|
For example, if an API was first deprecated in release 1.14,
|
||||||
|
it will be ready to be removed in 1.16 at the earliest.
|
||||||
|
There may be special circumstances, determined by the API working group,
|
||||||
|
where an API is deprecated sooner.
|
||||||
|
- What is required when deprecating:
|
||||||
|
|
||||||
|
- Mark as deprecated
|
||||||
|
- Document the deprecation
|
||||||
|
- All usage in Zephyr for deprecated API needs to be modified
|
||||||
|
- Change needs to be atomic and bisectable
|
||||||
|
- Code using the deprecated API needs to be modified to remove usage of said
|
||||||
|
API
|
||||||
|
|
||||||
|
During the deprecation waiting period, the API will be in the ``deprecated``
|
||||||
|
state. The Zephyr maintainers will track usage of deprecated APIs on
|
||||||
|
``docs.zephyrproject.org`` and support developers migrating their code. Zephyr
|
||||||
|
will continue to provide warnings:
|
||||||
|
|
||||||
|
- API documentation will inform users that the API is deprecated.
|
||||||
|
- Attempts to use a deprecated API at build time will log a warning to the
|
||||||
|
console.
|
||||||
|
|
||||||
|
|
||||||
|
Retired
|
||||||
|
*******
|
||||||
|
|
||||||
|
In this phase, the API is removed.
|
||||||
|
|
||||||
|
The target removal date is 2 releases after deprecation is announced.
|
||||||
|
The Zephyr maintainers will decide when to actually remove the API: this
|
||||||
|
will depend on how many developers have successfully migrated from the
|
||||||
|
deprecated API, and on how urgently the API needs to be removed.
|
||||||
|
|
||||||
|
If it's OK to remove the API, it will be removed. The maintainers will remove
|
||||||
|
the corresponding documentation, and communicate the removal in the usual ways:
|
||||||
|
the release notes, mailing lists, Github issues and pull-requests.
|
||||||
|
|
||||||
|
If it's not OK to remove the API, the maintainers will continue to support
|
||||||
|
migration and aim to remove the API in the next release.
|
||||||
|
|
||||||
48
doc/development_process/code_flow.rst
Normal file
48
doc/development_process/code_flow.rst
Normal file
|
|
@ -0,0 +1,48 @@
|
||||||
|
|
||||||
|
Code Flow and Branches
|
||||||
|
######################
|
||||||
|
|
||||||
|
Introduction
|
||||||
|
************
|
||||||
|
|
||||||
|
The zephyr Git repository has three types of branches:
|
||||||
|
|
||||||
|
master
|
||||||
|
Which contains the latest state of development
|
||||||
|
|
||||||
|
topic-\*
|
||||||
|
Topic branches that are used for shared development of a new feature
|
||||||
|
|
||||||
|
vx.y-branch
|
||||||
|
Branches which track maintenance releases based on a major
|
||||||
|
release
|
||||||
|
|
||||||
|
Development in topic branches before features go to mainline allows teams to
|
||||||
|
work independently on a subsystem or a feature, improves efficiency and
|
||||||
|
turnaround time, and encourages collaboration and streamlines communication
|
||||||
|
between developers.
|
||||||
|
|
||||||
|
Changes submitted to a development topic branch can evolve and improve
|
||||||
|
incrementally in a branch, before they are submitted to the mainline tree for
|
||||||
|
final integration.
|
||||||
|
|
||||||
|
By dedicating an isolated branch to complex features, it’s
|
||||||
|
possible to initiate in-depth discussions around new additions before
|
||||||
|
integrating them into the official project.
|
||||||
|
|
||||||
|
|
||||||
|
Roles and Responsibilities
|
||||||
|
**************************
|
||||||
|
|
||||||
|
Development topic branch owners have the following responsibilities:
|
||||||
|
|
||||||
|
- Use the infrastructure and tools provided by the project (GitHub, Git)
|
||||||
|
- Review changes coming from team members and request review from branch owners
|
||||||
|
when submitting changes.
|
||||||
|
- Keep the branch in sync with upstream and update on a regular basis.
|
||||||
|
- Push changes frequently to upstream using the following methods:
|
||||||
|
|
||||||
|
- GitHub pull requests: for example, when reviews have not been done in the local
|
||||||
|
branch (one-man branch).
|
||||||
|
- Merge requests: When a set of changes has been done in a local branch and
|
||||||
|
has been reviewed and tested in a topic branch.
|
||||||
14
doc/development_process/communication.rst
Normal file
14
doc/development_process/communication.rst
Normal file
|
|
@ -0,0 +1,14 @@
|
||||||
|
|
||||||
|
|
||||||
|
Communication and Collaboration
|
||||||
|
################################
|
||||||
|
|
||||||
|
The `Zephyr project mailing lists <https://lists.zephyrproject.org/g/main/subgroups>`_ are used as the primary
|
||||||
|
communication tool by project members, contributors, and the community. The
|
||||||
|
mailing list is open for topics related to the project and should be used for
|
||||||
|
collaboration among team members working on the same feature or subsystem or for
|
||||||
|
discussing project direction and daily development of the code base. In general,
|
||||||
|
bug reports and issues should be entered and tracked in the bug tracking system
|
||||||
|
(`GitHub Issues <https://github.com/zephyrproject-rtos/zephyr/issues>`_) and not broadcasted to the mailing list, the same applies to
|
||||||
|
code reviews. Code should be submitted to GitHub using the appropriate tools.
|
||||||
|
|
||||||
87
doc/development_process/documentation.rst
Normal file
87
doc/development_process/documentation.rst
Normal file
|
|
@ -0,0 +1,87 @@
|
||||||
|
|
||||||
|
Code Documentation
|
||||||
|
###################
|
||||||
|
|
||||||
|
API Documentation
|
||||||
|
******************
|
||||||
|
|
||||||
|
Well documented APIs enhance the experience for developers and are an essential
|
||||||
|
requirement for defining an API's success. Doxygen is a general purpose
|
||||||
|
documentation tool that the zephyr project uses for documenting APIs. It
|
||||||
|
generates either an on-line documentation browser (in HTML) and/or providess
|
||||||
|
input for other tools that is used to generate a reference manual from
|
||||||
|
documented source files. In particular, doxygen's XML output is used as an input
|
||||||
|
when producing the Zephyr project's online documentation.
|
||||||
|
|
||||||
|
Reference to Requirements
|
||||||
|
**************************
|
||||||
|
|
||||||
|
APIs for the most part document the implementation of requirements or advertised
|
||||||
|
features and can be traced back to features. We use the API documentation as the
|
||||||
|
main interface to trace implementation back to documented features. This is done
|
||||||
|
using custom _doxygen_ tags that reference requirements maintained somewhere
|
||||||
|
else in a requirement catalogue.
|
||||||
|
|
||||||
|
Test Documentation
|
||||||
|
*******************
|
||||||
|
|
||||||
|
To help understand what each test does and which functionality it tests we also
|
||||||
|
document all test code using the same tools and in the same context and generate
|
||||||
|
documentation for all unit and integration tests maintained in the same
|
||||||
|
environment. Tests are documented using references to the APIs or functionality
|
||||||
|
they validate by creating a link back to the APIs and by adding a reference to
|
||||||
|
the original resquirements.
|
||||||
|
|
||||||
|
|
||||||
|
Documentation Guidelines
|
||||||
|
*************************
|
||||||
|
|
||||||
|
Test Code
|
||||||
|
**********
|
||||||
|
|
||||||
|
The Zephyr project uses several test methodologies, the most common being the
|
||||||
|
:ref:`Ztest framework <testing>`. The documentation of tests should only be done
|
||||||
|
on the entry test functions (usually prefixed with test\_) and those that are
|
||||||
|
called directly by the Ztest framework. Those tests are going to appear in test
|
||||||
|
reports and using their name and identifier is the best way to identify them and
|
||||||
|
trace back to them to requirements.
|
||||||
|
|
||||||
|
Test documentation should not interfere with the actual API documentation and
|
||||||
|
needs to follow a new structure to avoid confusion. Using a consistent naming
|
||||||
|
scheme and following a well-defined structure we will be able to group this
|
||||||
|
documentation in its own module and identify it uniquely when parsing test data
|
||||||
|
for traceability reports. Here are a few guidelines to be followed:
|
||||||
|
|
||||||
|
- All test code documentation should be grouped under the ``all_tests`` doxygen
|
||||||
|
group
|
||||||
|
- All test documentation should be under doxygen groups that are prefixed
|
||||||
|
with tests\_
|
||||||
|
|
||||||
|
The doxygen ``@see`` directive is used to link features and APIs under test,
|
||||||
|
like so::
|
||||||
|
|
||||||
|
|
||||||
|
/**
|
||||||
|
* @brief Tests for the Semaphore kernel object
|
||||||
|
* @defgroup kernel_semaphore_tests Semaphore
|
||||||
|
* @ingroup all_tests
|
||||||
|
* @{
|
||||||
|
*/
|
||||||
|
|
||||||
|
...
|
||||||
|
/**
|
||||||
|
* @brief A brief description of the tests
|
||||||
|
* Some details about the test
|
||||||
|
* more details
|
||||||
|
*
|
||||||
|
* @see k_sem_init(), #K_SEM_DEFINE(x)
|
||||||
|
*/
|
||||||
|
void test_sema_thread2thread(void)
|
||||||
|
{
|
||||||
|
...
|
||||||
|
}
|
||||||
|
...
|
||||||
|
|
||||||
|
/**
|
||||||
|
* @}
|
||||||
|
*/
|
||||||
|
|
@ -3,6 +3,19 @@
|
||||||
Development Model
|
Development Model
|
||||||
#################
|
#################
|
||||||
|
|
||||||
|
|
||||||
|
.. toctree::
|
||||||
|
:maxdepth: 1
|
||||||
|
|
||||||
|
release_process
|
||||||
|
proposals
|
||||||
|
code_flow
|
||||||
|
review_process
|
||||||
|
issues
|
||||||
|
api_lifecycle
|
||||||
|
communication
|
||||||
|
documentation
|
||||||
|
|
||||||
Terminology
|
Terminology
|
||||||
***********
|
***********
|
||||||
|
|
||||||
|
|
@ -15,286 +28,4 @@ Terminology
|
||||||
pull from and push to, basically your upstream.
|
pull from and push to, basically your upstream.
|
||||||
- LTS: Long Term Support
|
- LTS: Long Term Support
|
||||||
|
|
||||||
Release Cycle
|
|
||||||
*************
|
|
||||||
|
|
||||||
The Zephyr project releases on a time-based cycle, rather than a feature-driven
|
|
||||||
one. Zephyr releases represent an aggregation of the work of many contributors,
|
|
||||||
companies, and individuals from the community.
|
|
||||||
|
|
||||||
A time-based release process enables the Zephyr project to provide users with a
|
|
||||||
balance of the latest technologies and features and excellent overall quality. A
|
|
||||||
roughly 3-month release cycle allows the project to coordinate development of
|
|
||||||
the features that have actually been implemented, allowing the project to
|
|
||||||
maintain the quality of the overall release without delays because of one or two
|
|
||||||
features that are not ready yet.
|
|
||||||
|
|
||||||
The Zephyr release model is loosely based on the Linux kernel model:
|
|
||||||
|
|
||||||
- Release tagging procedure:
|
|
||||||
|
|
||||||
- linear mode on master,
|
|
||||||
- release branches for maintenance after release tagging.
|
|
||||||
- Each release period will consist of a merge window period followed by one or
|
|
||||||
more release candidates on which only stabilization changes, bug fixes, and
|
|
||||||
documentation can be merged in.
|
|
||||||
|
|
||||||
- Merge window mode: all changes are accepted (subject to approval from the
|
|
||||||
respective maintainers.)
|
|
||||||
- When the merge window is closed, the gatekeeper lays a vN-rc1 tag and the tree
|
|
||||||
enters the release candidate phase
|
|
||||||
- CI sees the tag, builds and runs tests; QA analyses the report from the
|
|
||||||
build and test run and gives an ACK/NAK to the build
|
|
||||||
- The gatekeeper, with QA and any other needed input, determines if the release
|
|
||||||
candidate is a go for release
|
|
||||||
- If it is a go for a release, the gatekeeper lays a tag release vN at the same
|
|
||||||
point
|
|
||||||
- Development on new features continues in feature branches. Once features are
|
|
||||||
ready, they are submitted to mainline during the merge window period and after
|
|
||||||
the release is tagged.
|
|
||||||
|
|
||||||
.. figure:: release_cycle.png
|
|
||||||
:align: center
|
|
||||||
:alt: Release Cycle
|
|
||||||
:figclass: align-center
|
|
||||||
|
|
||||||
Release Cycle
|
|
||||||
|
|
||||||
Merge Window
|
|
||||||
*************
|
|
||||||
|
|
||||||
A relatively straightforward discipline is followed with regard to the merging
|
|
||||||
of patches for each release. At the beginning of each development cycle, the
|
|
||||||
"merge window" is said to be open. At that time, code which is deemed to be
|
|
||||||
sufficiently stable (and which is accepted by the development community) is
|
|
||||||
merged into the mainline tree. The bulk of changes for a new development cycle
|
|
||||||
(and all of the major changes) will be merged during this time.
|
|
||||||
|
|
||||||
The merge window lasts for approximately two months. At the end of this time,
|
|
||||||
the gatekeeper will declare that the window is closed and release the first of
|
|
||||||
the release candidates. For the codebase release which is destined to be 0.4.0,
|
|
||||||
for example, the release which happens at the end of the merge window will be
|
|
||||||
called 0.4.0-rc1. The -rc1 release is the signal that the time to merge new
|
|
||||||
features has passed, and that the time to stabilize the next release of the code
|
|
||||||
base has begun.
|
|
||||||
|
|
||||||
Over the next weeks, only patches which fix problems should be submitted to the
|
|
||||||
mainline. On occasion, a more significant change will be allowed, but such
|
|
||||||
occasions are rare and require a TSC approval (Change Control Board). As a
|
|
||||||
general rule, if you miss the merge window for a given feature, the best thing
|
|
||||||
to do is to wait for the next development cycle. (An occasional exception is
|
|
||||||
made for drivers for previously unsupported hardware; if they do not touch any
|
|
||||||
other in-tree code, they cannot cause regressions and should be safe to add at
|
|
||||||
any time).
|
|
||||||
|
|
||||||
As fixes make their way into the mainline, the patch rate will slow over time.
|
|
||||||
The mainline gatekeeper releases new -rc drops once or twice a week; a normal
|
|
||||||
series will get up to somewhere between -rc4 and -rc6 before the code base is
|
|
||||||
considered to be sufficiently stable and the final 0.4.x release is made.
|
|
||||||
|
|
||||||
At that point, the whole process starts over again.
|
|
||||||
|
|
||||||
.. figure:: merge_window.png
|
|
||||||
:align: center
|
|
||||||
:alt: Merge Window
|
|
||||||
:figclass: align-center
|
|
||||||
|
|
||||||
Merge Window
|
|
||||||
|
|
||||||
Here is the description of the various moderation levels:
|
|
||||||
|
|
||||||
- Low:
|
|
||||||
|
|
||||||
- Major New Features
|
|
||||||
- Bug Fixes
|
|
||||||
- Refactoring
|
|
||||||
- Structure/Directory Changes
|
|
||||||
- Medium:
|
|
||||||
|
|
||||||
- Bug Fixes, all priorities
|
|
||||||
- Enhancements
|
|
||||||
- Minor “self-contained” New Features
|
|
||||||
- High:
|
|
||||||
|
|
||||||
- Bug Fixes: P1 and P2
|
|
||||||
- Documentation + Test Coverage
|
|
||||||
|
|
||||||
Release Versions
|
|
||||||
****************
|
|
||||||
|
|
||||||
The following syntax should be used for releases and tags in Git:
|
|
||||||
|
|
||||||
- Release [Major].[Minor].[Patch Level]
|
|
||||||
- Release Candidate [Major].[Minor].[Patch Level]-rc[RC Number]
|
|
||||||
- Tagging:
|
|
||||||
|
|
||||||
- v[Major].[Minor].[Patch Level]-rc[RC Number]
|
|
||||||
- v[Major].[Minor].[Patch Level]
|
|
||||||
- v[Major].[Minor].99 - A tag applied to master branch to signify that work on
|
|
||||||
v[Major].[Minor+1] has started. For example, v1.7.99 will be tagged at the
|
|
||||||
start of v1.8 process. The tag corresponds to
|
|
||||||
VERSION_MAJOR/VERSION_MINOR/PATCHLEVEL macros as defined for a
|
|
||||||
work-in-progress master version. Presence of this tag allows generation of
|
|
||||||
sensible output for "git describe" on master, as typically used for
|
|
||||||
automated builds and CI tools.
|
|
||||||
|
|
||||||
Long Term Support (LTS)
|
|
||||||
***********************
|
|
||||||
|
|
||||||
Long-term support releases are designed to be supported for a longer than normal
|
|
||||||
period and will be the basis for products and certification for various usages.
|
|
||||||
|
|
||||||
The LTS is released every 2 years.
|
|
||||||
|
|
||||||
An LTS release will be branched and maintained independently of the mainline
|
|
||||||
tree.
|
|
||||||
|
|
||||||
|
|
||||||
.. figure:: lts.png
|
|
||||||
:align: center
|
|
||||||
:alt: Long Term Support Release
|
|
||||||
:figclass: align-center
|
|
||||||
|
|
||||||
Long Term Support Release
|
|
||||||
|
|
||||||
Changes and fixes flow in both directions, however, changes from master to
|
|
||||||
LTS branch will be limited to fixes that apply to both branches and for existing
|
|
||||||
features only.
|
|
||||||
|
|
||||||
All fixes for LTS that apply to the mainline tree are pushed to
|
|
||||||
mainline as well.
|
|
||||||
|
|
||||||
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 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.
|
|
||||||
|
|
||||||
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 automatically assigns a responsible reviewer on a component
|
|
||||||
basis, as defined in the CODEOWNERS file stored with the code tree in the Zephyr
|
|
||||||
project repository. A limited set of release managers are allowed to merge a PR
|
|
||||||
into the master branch once reviews are complete.
|
|
||||||
|
|
||||||
Continuous Integration
|
|
||||||
=======================
|
|
||||||
|
|
||||||
All changes submitted to GitHub are subject to sanity tests that are run on
|
|
||||||
emulated platforms and architectures to identify breakage and regressions that
|
|
||||||
can be immediately identified. Sanity testing additionally performs build tests
|
|
||||||
of a representative number of boards and platforms (subject to hardware
|
|
||||||
availability in the CI infrastructure). 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.
|
|
||||||
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)
|
|
||||||
- Gitlint: Git commit style based on project requirements
|
|
||||||
- License Check: Check for conflicting licenses
|
|
||||||
- Run '''sanitycheck''' script:
|
|
||||||
|
|
||||||
- Run kernel tests in QEMU (can vote -1 on errors)
|
|
||||||
- Build various samples for different boards (can vote -1 on errors)
|
|
||||||
|
|
||||||
|
|
||||||
Dealing with Proposals and RFCs
|
|
||||||
*******************************
|
|
||||||
|
|
||||||
Feature or enhancement proposals for Zephyr are used to propose a new design or
|
|
||||||
modify an existing feature and get it approved. To better integrate with the
|
|
||||||
current tools used in the project and to enable traceability and archiving of
|
|
||||||
such proposals a unified format for enhancement proposals is used.
|
|
||||||
|
|
||||||
Procedures
|
|
||||||
==========
|
|
||||||
|
|
||||||
Maintain such proposals in a document format (similar to the documentation
|
|
||||||
format used in the kernel source tree, using restructured Text) in a GitHub
|
|
||||||
repository. The review and approval process of GitHub could be used for
|
|
||||||
approving such proposals as well, so there will be no need for a dedicated tool.
|
|
||||||
|
|
||||||
Process
|
|
||||||
========
|
|
||||||
|
|
||||||
- Open an Improvement GitHub Issue with an abstract and the proposal itself
|
|
||||||
- Send an RFC with the abstract to the mailing list with an abstract and the
|
|
||||||
link to the detailed proposal
|
|
||||||
- Approve/Reject/Defer based on feedback and comments
|
|
||||||
|
|
||||||
Bug Reporting and Feature Tracking
|
|
||||||
***********************************
|
|
||||||
|
|
||||||
To maintain traceability and relation between proposals, changes, features, and
|
|
||||||
issues, cross-referencing a commit with a GitHub Issue and vice versa should be
|
|
||||||
done. Any changes that originate from a tracked feature or issue should contain
|
|
||||||
a reference to the feature by mentioning the corresponding Issue or pull-request id.
|
|
||||||
|
|
||||||
At any time it should be possible to establish the origin of a change and the
|
|
||||||
reason behind it by following the references in the code.
|
|
||||||
|
|
||||||
Communication and Collaboration
|
|
||||||
********************************
|
|
||||||
|
|
||||||
The Zephyr project mailing lists are important tools used as the primary
|
|
||||||
communication tool by project member, contributors, and the community. The
|
|
||||||
mailing list is open for topics related to the project and should be used for
|
|
||||||
collaboration among team members working on the same feature or subsystem or for
|
|
||||||
discussion project direction and daily development of the code base. In general,
|
|
||||||
bug reports and issues should be entered and tracked in the bug tracking system
|
|
||||||
(GitHub Issues) and not broadcasted to the mailing list, the same applies to
|
|
||||||
code reviews. Code should be submitted to GitHub using the appropriate tools.
|
|
||||||
|
|
||||||
Code Flow and Branches
|
|
||||||
**********************
|
|
||||||
|
|
||||||
Introduction
|
|
||||||
============
|
|
||||||
|
|
||||||
Development in topic branches before features go to mainline allows teams to work
|
|
||||||
independently on a subsystem or a feature, improves efficiency and turnaround
|
|
||||||
time and encourages collaboration and streamlines communication between
|
|
||||||
developers.
|
|
||||||
|
|
||||||
Changes submitted to a development branch can evolve and improve incrementally
|
|
||||||
in a branch before they are finally submitted to the mainline tree for final
|
|
||||||
integration.
|
|
||||||
|
|
||||||
By dedicating an isolated branch to each feature or subsystem, it’s
|
|
||||||
possible to initiate in-depth discussions around new additions before
|
|
||||||
integrating them into the official project.
|
|
||||||
|
|
||||||
Individual code changes and fixes can still be submitted to the main tree
|
|
||||||
without going through a development branch, however, such changes can be
|
|
||||||
redirected to a branch owner if the change is deemed to be part of a subsystem
|
|
||||||
that is maintained in a branch and needs review from subject matter experts
|
|
||||||
working in a branch. This might be needed to avoid conflicts when changes to the
|
|
||||||
same files and subsystems happen at the same time.
|
|
||||||
|
|
||||||
|
|
||||||
Roles and Responsibilities
|
|
||||||
==========================
|
|
||||||
|
|
||||||
Development topic branch owners have the following responsibilities:
|
|
||||||
|
|
||||||
- Use the infrastructure and tools provided by the project (GitHub, Git)
|
|
||||||
- Review changes coming from team members and request review from branch owners
|
|
||||||
when submitting changes.
|
|
||||||
- Keep the branch in sync with upstream and update on regular basis.
|
|
||||||
- Push changes frequently to upstream using the following methods:
|
|
||||||
|
|
||||||
- GitHub changes: for example, when reviews have not been done in local branch
|
|
||||||
(one-man branch).
|
|
||||||
- Merge requests: When a set of changes has been done in a local branch and
|
|
||||||
has been reviewed and tested in a feature branch.
|
|
||||||
|
|
|
||||||
11
doc/development_process/issues.rst
Normal file
11
doc/development_process/issues.rst
Normal file
|
|
@ -0,0 +1,11 @@
|
||||||
|
|
||||||
|
Bug Reporting and Feature Tracking
|
||||||
|
###################################
|
||||||
|
|
||||||
|
To maintain traceability and relation between proposals, changes, features, and
|
||||||
|
issues, cross-referencing a commit with a GitHub Issue and vice versa should be
|
||||||
|
done. Any changes that originate from a tracked feature or issue should contain
|
||||||
|
a reference to the feature by mentioning the corresponding Issue or pull-request id.
|
||||||
|
|
||||||
|
At any time it should be possible to establish the origin of a change and the
|
||||||
|
reason behind it by following the references in the code.
|
||||||
BIN
doc/development_process/milestones.png
Normal file
BIN
doc/development_process/milestones.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 59 KiB |
BIN
doc/development_process/milestones2.png
Normal file
BIN
doc/development_process/milestones2.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 105 KiB |
26
doc/development_process/proposals.rst
Normal file
26
doc/development_process/proposals.rst
Normal file
|
|
@ -0,0 +1,26 @@
|
||||||
|
|
||||||
|
Proposals and RFCs
|
||||||
|
##################
|
||||||
|
|
||||||
|
Feature or enhancement proposals for Zephyr are used to propose a new design or
|
||||||
|
modify an existing feature and get it approved. To better integrate with the
|
||||||
|
current tools used in the project and to enable traceability and archiving of
|
||||||
|
such proposals a unified format for enhancement proposals is used.
|
||||||
|
|
||||||
|
Procedures
|
||||||
|
***********
|
||||||
|
|
||||||
|
Maintain such proposals in a document format (similar to the documentation
|
||||||
|
format used in the kernel source tree, using restructured Text) in a GitHub
|
||||||
|
repository. The review and approval process of GitHub could be used for
|
||||||
|
approving such proposals as well, so there will be no need for a dedicated tool.
|
||||||
|
|
||||||
|
Process
|
||||||
|
*******
|
||||||
|
|
||||||
|
- Open an Improvement GitHub Issue with an abstract and the proposal itself or
|
||||||
|
open a pull request with detailed information about the nature of the change
|
||||||
|
and the rationale behind it.
|
||||||
|
- Send an RFC with the abstract to the mailing list with an abstract and the
|
||||||
|
link to the detailed proposal
|
||||||
|
- Approve/Reject/Defer based on feedback and comments
|
||||||
BIN
doc/development_process/pull_request_classes.png
Normal file
BIN
doc/development_process/pull_request_classes.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 38 KiB |
BIN
doc/development_process/release_flow.png
Normal file
BIN
doc/development_process/release_flow.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 67 KiB |
321
doc/development_process/release_process.rst
Normal file
321
doc/development_process/release_process.rst
Normal file
|
|
@ -0,0 +1,321 @@
|
||||||
|
.. _release_process:
|
||||||
|
|
||||||
|
Release Process
|
||||||
|
###############
|
||||||
|
|
||||||
|
The Zephyr project releases on a time-based cycle, rather than a feature-driven
|
||||||
|
one. Zephyr releases represent an aggregation of the work of many contributors,
|
||||||
|
companies, and individuals from the community.
|
||||||
|
|
||||||
|
A time-based release process enables the Zephyr project to provide users with a
|
||||||
|
balance of the latest technologies and features and excellent overall quality. A
|
||||||
|
roughly 3-month release cycle allows the project to coordinate development of
|
||||||
|
the features that have actually been implemented, allowing the project to
|
||||||
|
maintain the quality of the overall release without delays because of one or two
|
||||||
|
features that are not ready yet.
|
||||||
|
|
||||||
|
The Zephyr release model is loosely based on the Linux kernel model:
|
||||||
|
|
||||||
|
- Release tagging procedure:
|
||||||
|
|
||||||
|
- linear mode on master,
|
||||||
|
- release branches for maintenance after release tagging.
|
||||||
|
- Each release period will consist of a merge window period followed by one or
|
||||||
|
more release candidates on which only stabilization changes, bug fixes, and
|
||||||
|
documentation can be merged in.
|
||||||
|
|
||||||
|
- Merge window mode: all changes are accepted (subject to approval from the
|
||||||
|
respective maintainers.)
|
||||||
|
- When the merge window is closed, the release owner lays a vN-rc1 tag and the
|
||||||
|
tree enters the release candidate phase
|
||||||
|
- CI sees the tag, builds and runs tests; QA analyses the report from the
|
||||||
|
build and test run and gives an ACK/NAK to the build
|
||||||
|
- The release owner, with QA and any other needed input, determines if the
|
||||||
|
release candidate is a go for release
|
||||||
|
- If it is a go for a release, the release owner lays a tag release vN at the
|
||||||
|
same point
|
||||||
|
- Development on new features continues in topic branches. Once features are
|
||||||
|
ready, they are submitted to mainline during the merge window period and after
|
||||||
|
the release is tagged.
|
||||||
|
|
||||||
|
.. figure:: release_cycle.png
|
||||||
|
:align: center
|
||||||
|
:alt: Release Cycle
|
||||||
|
:figclass: align-center
|
||||||
|
:width: 80%
|
||||||
|
|
||||||
|
Release Cycle
|
||||||
|
|
||||||
|
Merge Window
|
||||||
|
*************
|
||||||
|
|
||||||
|
A relatively straightforward discipline is followed with regard to the merging
|
||||||
|
of patches for each release. At the beginning of each development cycle, the
|
||||||
|
"merge window" is said to be open. At that time, code which is deemed to be
|
||||||
|
sufficiently stable (and which is accepted by the development community) is
|
||||||
|
merged into the mainline tree. The bulk of changes for a new development cycle
|
||||||
|
(and all of the major changes) will be merged during this time.
|
||||||
|
|
||||||
|
The merge window lasts for approximately two months. At the end of this time,
|
||||||
|
the release owner will declare that the window is closed and release the first
|
||||||
|
of the release candidates. For the codebase release which is destined to be
|
||||||
|
0.4.0, for example, the release which happens at the end of the merge window
|
||||||
|
will be called 0.4.0-rc1. The -rc1 release is the signal that the time to merge
|
||||||
|
new features has passed, and that the time to stabilize the next release of the
|
||||||
|
code base has begun.
|
||||||
|
|
||||||
|
Over the next weeks, only patches which fix problems should be submitted to the
|
||||||
|
mainline. On occasion, a more significant change will be allowed, but such
|
||||||
|
occasions are rare and require a TSC approval (Change Control Board). As a
|
||||||
|
general rule, if you miss the merge window for a given feature, the best thing
|
||||||
|
to do is to wait for the next development cycle. (An occasional exception is
|
||||||
|
made for drivers for previously unsupported hardware; if they do not touch any
|
||||||
|
other in-tree code, they cannot cause regressions and should be safe to add at
|
||||||
|
any time).
|
||||||
|
|
||||||
|
As fixes make their way into the mainline, the patch rate will slow over time.
|
||||||
|
The mainline release owner releases new -rc drops once or twice a week; a normal
|
||||||
|
series will get up to somewhere between -rc4 and -rc6 before the code base is
|
||||||
|
considered to be sufficiently stable and the final 0.4.x release is made.
|
||||||
|
|
||||||
|
At that point, the whole process starts over again.
|
||||||
|
|
||||||
|
.. figure:: merge_window.png
|
||||||
|
:align: center
|
||||||
|
:alt: Merge Window
|
||||||
|
:figclass: align-center
|
||||||
|
:width: 80%
|
||||||
|
|
||||||
|
Merge Window
|
||||||
|
|
||||||
|
Here is the description of the various moderation levels:
|
||||||
|
|
||||||
|
- Low:
|
||||||
|
|
||||||
|
- Major New Features
|
||||||
|
- Bug Fixes
|
||||||
|
- Refactoring
|
||||||
|
- Structure/Directory Changes
|
||||||
|
- Medium:
|
||||||
|
|
||||||
|
- Bug Fixes, all priorities
|
||||||
|
- Enhancements
|
||||||
|
- Minor “self-contained” New Features
|
||||||
|
- High:
|
||||||
|
|
||||||
|
- Bug Fixes: P1 and P2
|
||||||
|
- Documentation + Test Coverage
|
||||||
|
|
||||||
|
Releases
|
||||||
|
*********
|
||||||
|
|
||||||
|
The following syntax should be used for releases and tags in Git:
|
||||||
|
|
||||||
|
- Release [Major].[Minor].[Patch Level]
|
||||||
|
- Release Candidate [Major].[Minor].[Patch Level]-rc[RC Number]
|
||||||
|
- Tagging:
|
||||||
|
|
||||||
|
- v[Major].[Minor].[Patch Level]-rc[RC Number]
|
||||||
|
- v[Major].[Minor].[Patch Level]
|
||||||
|
- v[Major].[Minor].99 - A tag applied to master branch to signify that work on
|
||||||
|
v[Major].[Minor+1] has started. For example, v1.7.99 will be tagged at the
|
||||||
|
start of v1.8 process. The tag corresponds to
|
||||||
|
VERSION_MAJOR/VERSION_MINOR/PATCHLEVEL macros as defined for a
|
||||||
|
work-in-progress master version. Presence of this tag allows generation of
|
||||||
|
sensible output for "git describe" on master, as typically used for
|
||||||
|
automated builds and CI tools.
|
||||||
|
|
||||||
|
|
||||||
|
.. figure:: release_flow.png
|
||||||
|
:align: center
|
||||||
|
:alt: Releases
|
||||||
|
:figclass: align-center
|
||||||
|
:width: 80%
|
||||||
|
|
||||||
|
Zephyr Code and Releases
|
||||||
|
|
||||||
|
|
||||||
|
Long Term Support (LTS)
|
||||||
|
=======================
|
||||||
|
|
||||||
|
Long-term support releases are designed to be supported for a longer than normal
|
||||||
|
period and will be the basis for products and certification for various usages.
|
||||||
|
|
||||||
|
An LTS release is made every 2 years and is branched and maintained
|
||||||
|
independently from the mainline tree.
|
||||||
|
|
||||||
|
An LTS release will be branched and maintained independently of the mainline
|
||||||
|
tree.
|
||||||
|
|
||||||
|
|
||||||
|
.. figure:: lts.png
|
||||||
|
:align: center
|
||||||
|
:alt: Long Term Support Release
|
||||||
|
:figclass: align-center
|
||||||
|
:width: 80%
|
||||||
|
|
||||||
|
Long Term Support Release
|
||||||
|
|
||||||
|
Changes and fixes flow in both directions. However, changes from master to an
|
||||||
|
LTS branch will be limited to fixes that apply to both branches and for existing
|
||||||
|
features only.
|
||||||
|
|
||||||
|
All fixes for an LTS branch that apply to the mainline tree are pushed to
|
||||||
|
mainline as well.
|
||||||
|
|
||||||
|
|
||||||
|
Auditable Code Base
|
||||||
|
===================
|
||||||
|
|
||||||
|
An auditable code base is to be established from a defined subset of Zephyr OS
|
||||||
|
features and will be limited in scope. The LTS, development tree, and the
|
||||||
|
auditable code bases shall be kept in sync after the audit branch is created,
|
||||||
|
but with a more rigorous process in place for adding new features into the audit
|
||||||
|
branch used for certification.
|
||||||
|
|
||||||
|
This process will be applied before new features move into the
|
||||||
|
auditable code base.
|
||||||
|
|
||||||
|
The initial and subsequent certification targets will be decided by the Zephyr project
|
||||||
|
governing board.
|
||||||
|
|
||||||
|
Processes to achieve selected certification will be determined by the Security and
|
||||||
|
Safety Working Groups and coordinated with the TSC.
|
||||||
|
|
||||||
|
|
||||||
|
Release Procedure
|
||||||
|
******************
|
||||||
|
|
||||||
|
This section documents the Release manager responsibilities so that it serves as
|
||||||
|
a knowledge repository for Release managers.
|
||||||
|
|
||||||
|
Milestones
|
||||||
|
==========
|
||||||
|
|
||||||
|
The following graphic shows the timeline of phases and milestones associated
|
||||||
|
with each release:
|
||||||
|
|
||||||
|
.. figure:: milestones.png
|
||||||
|
:align: center
|
||||||
|
:alt: Release Milestones
|
||||||
|
:figclass: align-center
|
||||||
|
:width: 80%
|
||||||
|
|
||||||
|
Release milestones
|
||||||
|
|
||||||
|
This shows how the phases and milestones of one release overlap with those of
|
||||||
|
the next release:
|
||||||
|
|
||||||
|
|
||||||
|
.. figure:: milestones2.png
|
||||||
|
:align: center
|
||||||
|
:alt: Release Milestones
|
||||||
|
:figclass: align-center
|
||||||
|
:width: 80%
|
||||||
|
|
||||||
|
Release milestones with planning
|
||||||
|
|
||||||
|
|
||||||
|
.. csv-table:: Milestone Description
|
||||||
|
:header: "Milestone", "Description", "Definition"
|
||||||
|
:widths: auto
|
||||||
|
|
||||||
|
|
||||||
|
"P0","Planning Kickoff","Start Entering Requirements"
|
||||||
|
"P1","","TSC Agrees on Major Features and Schedule"
|
||||||
|
"M0","Merge Window Open","All features, Sized, and AssignedMerge Window Is Opened"
|
||||||
|
"M1","M1 Checkpoint","Major Features Ready for Code Reviews |br| Test Plans Reviewed and Approved"
|
||||||
|
"M2","Feature Merge Window Close","Feature Freeze |br| Feature Development Complete (including Code Reviews and Unit Tests Passing) |br| P1 Stories Implemented |br| Feature Merge Window Is Closed |br| Test Development Complete |br| Technical Documentation Created/Updated and Ready for Review |br| CCB Control Starts"
|
||||||
|
"M3","Code Freeze","Code Freeze |br| RC3 Tagged and Built"
|
||||||
|
"M4","Release","TSC Reviews the Release Criteria Report and Approves Release
|
||||||
|
|br| Final RC Tagged |br| Make the Release"
|
||||||
|
|
||||||
|
Release Checklist
|
||||||
|
=================
|
||||||
|
|
||||||
|
Each release has a GitHub issue associated with it that contains the full
|
||||||
|
checklist. After a release is complete, a checklist for the next release is
|
||||||
|
created.
|
||||||
|
|
||||||
|
Tagging
|
||||||
|
=======
|
||||||
|
|
||||||
|
.. note::
|
||||||
|
|
||||||
|
This section uses tagging 1.11.0-rc1 as an example, replace with the
|
||||||
|
appropriate version.
|
||||||
|
|
||||||
|
Every time a release candidate (or the final release) needs to be tagged, the
|
||||||
|
following steps need to be followed:
|
||||||
|
|
||||||
|
#. Update the :file:`VERSION` file in the root of the Git repository. If it's a
|
||||||
|
release candidate, use `EXTRAVERSION` variable::
|
||||||
|
|
||||||
|
EXTRAVERSION = rc1
|
||||||
|
|
||||||
|
#. Commit the update to the :file:`VERSION` file, use `release:` as a commit
|
||||||
|
tag.
|
||||||
|
#. Check that CI has completed successfully before tagging.
|
||||||
|
#. Tag and push the version, using annotated tags:
|
||||||
|
|
||||||
|
* If it's a release candidate::
|
||||||
|
|
||||||
|
$ git tag -a v1.11.0-rc1
|
||||||
|
<Use "Zephyr 1.11.0-rc1" as the tag annotation>
|
||||||
|
$ git push git@github.com:zephyrproject-rtos/zephyr.git v1.11.0-rc1
|
||||||
|
|
||||||
|
* If it's a release::
|
||||||
|
|
||||||
|
$ git tag -a v1.11.0
|
||||||
|
<Use "Zephyr 1.11.0" as the tag annotation>
|
||||||
|
$ git push git@github.com:zephyrproject-rtos/zephyr.git v1.11.0
|
||||||
|
|
||||||
|
$ git tag -a zephyr-v1.11.0
|
||||||
|
<Use "Zephyr 1.11.0" as the tag annotation>
|
||||||
|
$ git push git@github.com:zephyrproject-rtos/zephyr.git zephyr-v1.11.0
|
||||||
|
|
||||||
|
#. If it's a release candidate, create a shortlog of changes between the
|
||||||
|
previous release::
|
||||||
|
|
||||||
|
$ git shortlog v1.10.0..v.1.11.0-rc1
|
||||||
|
|
||||||
|
#. Find the new tag at the top of the releases page, edit the release with the
|
||||||
|
`Edit` button and then do the following:
|
||||||
|
|
||||||
|
* If it's a release candidate:
|
||||||
|
|
||||||
|
* Name it `Zephyr 1.11.0-rc1`
|
||||||
|
* Copy the shortlog into the release notes textbox (don't forget to quote it
|
||||||
|
properly so it shows as unformatted text in Markdown)
|
||||||
|
* Check the "This is a pre-release" checkbox
|
||||||
|
* If it's a release:
|
||||||
|
|
||||||
|
* Name it `Zephyr 1.11.0`
|
||||||
|
* Copy the full content of `docs/release-notes-1.11.rst` into the the
|
||||||
|
release notes textbox
|
||||||
|
* Copy the full list of GitHub issues closed with this release into the
|
||||||
|
release notes textbox (see below on how to generate this list)
|
||||||
|
|
||||||
|
#. Send an email to the mailing lists (``announce`` and ``devel``) with a link
|
||||||
|
to the release
|
||||||
|
|
||||||
|
Listing all closed GitHub issues
|
||||||
|
=================================
|
||||||
|
|
||||||
|
The release notes for a final release contain the list of GitHub issues that
|
||||||
|
have been closed during the development process of that release.
|
||||||
|
|
||||||
|
In order to obtain the list of issues closed during the release development
|
||||||
|
cycle you can do the following:
|
||||||
|
|
||||||
|
#. Look for the last release before the current one and find the day it was
|
||||||
|
tagged::
|
||||||
|
|
||||||
|
$ git show zephyr-v1.10.0
|
||||||
|
tag zephyr-v1.10.0
|
||||||
|
Tagger: Kumar Gala <kumar.gala@linaro.org>
|
||||||
|
Date: Fri Dec 8 14:26:35 2017 -0600
|
||||||
|
|
||||||
|
|
||||||
|
#. Use available release tools to list all the issues that have been closed
|
||||||
|
between that date and the day of the release.
|
||||||
215
doc/development_process/review_process.rst
Normal file
215
doc/development_process/review_process.rst
Normal file
|
|
@ -0,0 +1,215 @@
|
||||||
|
|
||||||
|
|
||||||
|
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.
|
||||||
|
|
||||||
|
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 automatically assigns a responsible reviewer on a
|
||||||
|
component basis, as defined in the :file:`CODEOWNERS` 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 master branch once reviews are complete.
|
||||||
|
|
||||||
|
|
||||||
|
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
|
||||||
|
++++
|
||||||
|
|
||||||
|
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 API changes, the API working group needs to be consulted
|
||||||
|
and made aware of such changes.
|
||||||
|
|
||||||
|
|
||||||
|
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 1 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
|
||||||
|
- Split the commits
|
||||||
|
- 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.
|
||||||
|
Failing to do so, an issue or a pull request will be closed automatically
|
||||||
|
after 6 months.
|
||||||
|
|
||||||
|
Continuous Integration
|
||||||
|
***********************
|
||||||
|
|
||||||
|
All changes submitted to GitHub are subject to sanity tests that are run on
|
||||||
|
emulated platforms and architectures to identify breakage and regressions that
|
||||||
|
can be immediately identified. Sanity testing 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)
|
||||||
|
- Gitlint: Git commit style based on project requirements
|
||||||
|
- License Check: Check for conflicting licenses
|
||||||
|
- Run ''sanitycheck'' 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.
|
||||||
|
|
||||||
Loading…
Add table
Add a link
Reference in a new issue