michaelh/zephyr
1
0
Fork 0
Code Releases Activity

doc: Rework Development Process section

Browse source 
- 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 2019-02-13 14:22:40 -05:00
commit 63d330e78b
14 changed files with 869 additions and 282 deletions
Download patch file Download diff file Expand all files Collapse all files

BIN
doc/development_process/api_lifecycle.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 56 KiB

134
doc/development_process/api_lifecycle.rst Normal file
View 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
View 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
View 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
View 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)
{
...
}
...
/**
* @}
*/

295
doc/development_process/index.rst
View file

@ -3,6 +3,19 @@
Development Model
#################
.. toctree::
:maxdepth: 1
release_process
proposals
code_flow
review_process
issues
api_lifecycle
communication
documentation
Terminology
***********
@ -15,286 +28,4 @@ Terminology
pull from and push to, basically your upstream.
- 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
View 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
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 59 KiB

BIN
doc/development_process/milestones2.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 105 KiB

26
doc/development_process/proposals.rst Normal file
View 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
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 38 KiB

BIN
doc/development_process/release_flow.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 67 KiB

321
doc/development_process/release_process.rst Normal file
View 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
View 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.