doc: create new section for project structure
Move all project and governance related docs into one new section. Signed-off-by: Anas Nashif <anas.nashif@intel.com>
This commit is contained in:
Anas Nashif
Carles Cufí
parent
f09948b68a
commit
5b3b9c7c41
19 changed files with 4 additions and 4 deletions
49
doc/project/code_flow.rst
Normal file
49
doc/project/code_flow.rst
Normal file
|
|
@ -0,0 +1,49 @@
|
|||
.. _code-flow-and-branches:
|
||||
|
||||
Code Flow and Branches
|
||||
######################
|
||||
|
||||
Introduction
|
||||
************
|
||||
|
||||
The zephyr Git repository has three types of branches:
|
||||
|
||||
main
|
||||
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.
|
||||
16
doc/project/communication.rst
Normal file
16
doc/project/communication.rst
Normal file
|
|
@ -0,0 +1,16 @@
|
|||
.. _communication-and-collaboration:
|
||||
|
||||
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.
|
||||
395
doc/project/dev_env_and_tools.rst
Normal file
395
doc/project/dev_env_and_tools.rst
Normal file
|
|
@ -0,0 +1,395 @@
|
|||
.. _dev-environment-and-tools:
|
||||
|
||||
Development Environment and Tools
|
||||
#################################
|
||||
|
||||
Code Review
|
||||
************
|
||||
|
||||
GitHub is intended to provide a framework for reviewing every commit before it
|
||||
is accepted into the code base. Changes, in the form of Pull Requests (PR) are
|
||||
uploaded to GitHub but don't actually become a part of the project until they've
|
||||
been reviewed, passed a series of checks (CI), and are approved by maintainers.
|
||||
GitHub is used to support the standard open source practice of submitting
|
||||
patches, which are then reviewed by the project members before being applied to
|
||||
the code base.
|
||||
|
||||
Pull requests should be appropriately :ref:`labeled<gh_labels>`,
|
||||
and linked to any relevant :ref:`bug or feature tracking issues<bug_reporting>`
|
||||
.
|
||||
|
||||
The Zephyr project uses GitHub for code reviews and Git tree management. When
|
||||
submitting a change or an enhancement to any Zephyr component, a developer
|
||||
should use GitHub. GitHub automatically assigns a responsible reviewer on a
|
||||
component basis, as defined in the :zephyr_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 main branch once reviews are complete.
|
||||
|
||||
.. _review_time:
|
||||
|
||||
Give reviewers time to review before code merge
|
||||
================================================
|
||||
|
||||
The Zephyr project is a global project that is not tied to a certain geography
|
||||
or timezone. We have developers and contributors from across the globe. When
|
||||
changes are proposed using pull request, we need to allow for a minimal review
|
||||
time to give developers and contributors the opportunity to review and comment
|
||||
on changes. There are different categories of changes and we know that some
|
||||
changes do require reviews by subject matter experts and owners of the subsystem
|
||||
being changed. Many changes fall under the "trivial" category that can be
|
||||
addressed with general reviews and do not need to be queued for a maintainer or
|
||||
code-owner review. Additionally, some changes might require further discussions
|
||||
and a decision by the TSC or the Security working group. To summarize the above,
|
||||
the diagram below proposes minimal review times for each category:
|
||||
|
||||
|
||||
.. figure:: pull_request_classes.png
|
||||
:align: center
|
||||
:alt: Pull request classes
|
||||
:figclass: align-center
|
||||
|
||||
Pull request classes
|
||||
|
||||
Workflow
|
||||
---------
|
||||
|
||||
- An author of a change can suggest in his pull-request which category a change
|
||||
should belong to. A project maintainers or TSC member monitoring the inflow of
|
||||
changes can change the label of a pull request by adding a comment justifying
|
||||
why a change should belong to another category.
|
||||
- The project will use the label system to categorize the pull requests.
|
||||
- Changes should not be merged before the minimal time has expired.
|
||||
|
||||
Categories/Labels
|
||||
-----------------
|
||||
|
||||
Hotfix
|
||||
++++++
|
||||
|
||||
Any change that is a fix to an issue that blocks developers from doing their
|
||||
daily work, for example CI breakage, Test breakage, Minor documentation fixes
|
||||
that impact the user experience.
|
||||
|
||||
Such fixes can be merged at any time after they have passed CI checks. Depending
|
||||
on the fix, severity, and availability of someone to review them (other than the
|
||||
author) they can be merged with justification without review by one of the
|
||||
project owners.
|
||||
|
||||
Trivial
|
||||
+++++++
|
||||
|
||||
Trivial changes are those that appear obvious enough and do not require maintainer or code-owner
|
||||
involvement. Such changes should not change the logic or the design of a
|
||||
subsystem or component. For example a trivial change can be:
|
||||
|
||||
- Documentation changes
|
||||
- Configuration changes
|
||||
- Minor Build System tweaks
|
||||
- Minor optimization to code logic without changing the logic
|
||||
- Test changes and fixes
|
||||
- Sample modifications to support additional configuration or boards etc.
|
||||
|
||||
Maintainer
|
||||
+++++++++++
|
||||
|
||||
Any changes that touch the logic or the original design of a subsystem or
|
||||
component will need to be reviewed by the code owner or the designated subsystem
|
||||
maintainer. If the code changes is initiated by a contributor or developer other
|
||||
than the owner the pull request needs to be assigned to the code owner who will
|
||||
have to drive the pull request to a mergeable state by giving feedback to the
|
||||
author and asking for more reviews from other developers.
|
||||
|
||||
Security
|
||||
+++++++++++
|
||||
|
||||
Changes that appear to have an impact to the overall security of the system need
|
||||
to be reviewed by a security expert from the security working group.
|
||||
|
||||
TSC and Working Groups
|
||||
++++++++++++++++++++++
|
||||
|
||||
Changes that introduce new features or functionality or change the way the
|
||||
overall system works need to be reviewed by the TSC or the responsible Working
|
||||
Group. For example for :ref:`stable API changes <stable_api_changes>`, the
|
||||
proposal needs to be presented in the API meeting so that the relevant
|
||||
stakeholders are made aware of the change.
|
||||
|
||||
A Pull-Request should have an Assignee
|
||||
=======================================
|
||||
|
||||
- An assignee to a pull request should not be the same as the
|
||||
author of the pull-request
|
||||
- An assignee to a pull request is responsible for driving the
|
||||
pull request to a mergeable state
|
||||
- An assignee is responsible for dismissing stale reviews and seeking reviews
|
||||
from additional developers and contributors
|
||||
- Pull requests should not be merged without an approval by the assignee.
|
||||
|
||||
Pull Request should not be merged by author without review
|
||||
===========================================================
|
||||
|
||||
All pull requests need to be reviewed and should not be merged by the author
|
||||
without a review. The following exceptions apply:
|
||||
|
||||
- Hot fixes: Fixing CI issues, reverts, and system breakage
|
||||
- Release related changes: Changing version file, applying tags and release
|
||||
related activities without any code changes.
|
||||
|
||||
Developers and contributors should always seek review, however there are cases
|
||||
when reviewers are not available and there is a need to get a code change into
|
||||
the tree as soon as possible.
|
||||
|
||||
Reviewers shall not 'Request Changes' without comments or justification
|
||||
=======================================================================
|
||||
|
||||
Any change requests (-1) on a pull request have to be justified. A reviewer
|
||||
should avoid blocking a pull-request with no justification. If a reviewer feels
|
||||
that a change should not be merged without their review, then: Request change
|
||||
of the category: for example:
|
||||
|
||||
- Trivial -> Maintainer
|
||||
- Assign Pull Request to yourself, this will mean that a pull request should
|
||||
not be merged without your approval.
|
||||
|
||||
|
||||
Pull Requests should have at least 2 approvals before they are merged
|
||||
======================================================================
|
||||
|
||||
A pull-request shall be merged only with two positive reviews (approval). Beside
|
||||
the person merging the pull-request (merging != approval), two additional
|
||||
approvals are required to be able to merge a pull request. The person merging
|
||||
the request can merge without approving or approve and merge to get to the 2
|
||||
approvals required.
|
||||
|
||||
Reviewers should keep track of pull requests they have provided feedback to
|
||||
===========================================================================
|
||||
|
||||
If a reviewer has requested changes in a pull request, he or she should monitor
|
||||
the state of the pull request and/or respond to mention requests to see if his
|
||||
feedback has been addressed. Failing to do so, negative reviews shall be
|
||||
dismissed by the assignee or an owner of the repository. Reviews will be
|
||||
dismissed following the criteria below:
|
||||
|
||||
- The feedback or concerns were visibly addressed by the author
|
||||
- The reviewer did not revisit the pull request after 2 week and multiple pings
|
||||
by the author
|
||||
- The review is unrelated to the code change or asking for unjustified
|
||||
structural changes such as:
|
||||
|
||||
- Split the PR
|
||||
- Can you fix this unrelated code that happens to appear in the diff
|
||||
- Can you fix unrelated issues
|
||||
- Etc.
|
||||
|
||||
Closing Stale Issues and Pull Requests
|
||||
=======================================
|
||||
|
||||
- The Pull requests and issues sections on Github are NOT discussion forums.
|
||||
They are items that we need to execute and drive to closure.
|
||||
Use the mailing lists for discussions.
|
||||
- In case of both issues and pull-requests the original poster needs to respond
|
||||
to questions and provide clarifications regarding the issue or the change.
|
||||
After one week without a response to a request, a second attempt to elicit
|
||||
a response from the contributor will be made. After one more week without a
|
||||
response the item may be closed (draft and DNM tagged pull requests are
|
||||
excluded).
|
||||
|
||||
Continuous Integration
|
||||
***********************
|
||||
|
||||
All changes submitted to GitHub are subject to tests that are run on
|
||||
emulated platforms and architectures to identify breakage and regressions that
|
||||
can be immediately identified. Testing using Twister additionally performs build tests
|
||||
of all boards and platforms. Documentation changes are also verified
|
||||
through review and build testing to verify doc generation will be successful.
|
||||
|
||||
Any failures found during the CI test run will result in a negative review
|
||||
assigned automatically by the CI system.
|
||||
Developers are expected to fix issues and rework their patches and submit again.
|
||||
|
||||
The CI infrastructure currently runs the following tests:
|
||||
|
||||
- Run ''checkpatch'' for code style issues (can vote -1 on errors; see note)
|
||||
- Gitlint: Git commit style based on project requirements
|
||||
- License Check: Check for conflicting licenses
|
||||
- Run ''twister'' script
|
||||
|
||||
- Run kernel tests in QEMU (can vote -1 on errors)
|
||||
- Build various samples for different boards (can vote -1 on errors)
|
||||
|
||||
- Verify documentation builds correctly.
|
||||
|
||||
.. note::
|
||||
|
||||
''checkpatch'' is a Perl script that uses regular expressions to
|
||||
extract information that requires a C language parser to process
|
||||
accurately. As such it sometimes issues false positives. Known
|
||||
cases include constructs like::
|
||||
|
||||
static uint8_t __aligned(PAGE_SIZE) page_pool[PAGE_SIZE * POOL_PAGES];
|
||||
IOPCTL_Type *base = config->base;
|
||||
|
||||
Both lines produce a diagnostic regarding spaces around the ``*``
|
||||
operator: the first is misidentified as a pointer type declaration
|
||||
that would be correct as ``PAGE_SIZE *POOL_PAGES`` while the second
|
||||
is misidentified as a multiplication expression that would be correct
|
||||
as ``IOPCTL_Type * base``.
|
||||
|
||||
Maintainers can override the -1 in cases where the CI infrastructure
|
||||
gets the wrong answer.
|
||||
|
||||
|
||||
.. _gh_labels:
|
||||
|
||||
Labeling issues and pull requests in GitHub
|
||||
*******************************************
|
||||
|
||||
The project uses GitHub issues and pull requests (PRs) to track and manage
|
||||
daily and long-term work and contributions to the Zephyr project. We use
|
||||
GitHub **labels** to classify and organize these issues and PRs by area, type,
|
||||
priority, and more, making it easier to find and report on relevant items.
|
||||
|
||||
All GitHub issues or pull requests must be appropriately labeled.
|
||||
Issues and PRs often have multiple labels assigned,
|
||||
to help classify them in the different available categories.
|
||||
When reviewing a PR, if it has missing or incorrect labels, maintainers shall
|
||||
fix it.
|
||||
|
||||
This saves us all time when searching, reduces the chances of the PR or issue
|
||||
being forgotten, speeds up reviewing, avoids duplicate issue reports, etc.
|
||||
|
||||
These are the labels we currently have, grouped by type:
|
||||
|
||||
Area
|
||||
====
|
||||
|
||||
============= ===============================================================
|
||||
Labels ``Area:*``
|
||||
Applicable to PRs and issues
|
||||
Description Indicates subsystems (e.g., Kernel, I2C, Memory Management),
|
||||
project functions (e.g., Debugging, Documentation, Process),
|
||||
or other categories (e.g., Coding Style, MISRA-C) affected by
|
||||
the bug or pull request.
|
||||
============= ===============================================================
|
||||
|
||||
An area maintainer should be able to filter by an area label and
|
||||
find all issues and PRs which relate to that area.
|
||||
|
||||
Platform
|
||||
========
|
||||
|
||||
============= ===============================================================
|
||||
Labels ``Platform:*``
|
||||
Applicable to PRs and issues
|
||||
Description An issue or PR which affects only a particular platform
|
||||
============= ===============================================================
|
||||
|
||||
To be discussed in a meeting
|
||||
============================
|
||||
|
||||
============= ===============================================================
|
||||
Labels ``dev-review``, ``TSC``
|
||||
Applicable to PRs and issues
|
||||
Description The issue is to be discussed in the following
|
||||
`dev-review/TSC meeting`_ if time permits
|
||||
============= ===============================================================
|
||||
|
||||
.. _`dev-review/TSC meeting`: https://github.com/zephyrproject-rtos/zephyr/wiki/Zephyr-Committee-and-Working-Group-Meetings
|
||||
|
||||
Stable API changes
|
||||
==================
|
||||
|
||||
============= ===============================================================
|
||||
Labels ``Stable API Change``
|
||||
Applicable to PRs and issues
|
||||
Description The issue or PR describes a change to a stable API. See
|
||||
additional information in :ref:`stable_api_changes`
|
||||
============= ===============================================================
|
||||
|
||||
Minimum PR review time
|
||||
======================
|
||||
|
||||
============= ===============================================================
|
||||
Labels ``Hot Fix``, ``Trivial``, ``Maintainer``,
|
||||
``Security Review``, ``TSC``
|
||||
Applicable to PRs only
|
||||
Description Depending on the PR complexity, an indication of how long a merge
|
||||
should be held to ensure proper review. See
|
||||
:ref:`review process <review_time>`
|
||||
============= ===============================================================
|
||||
|
||||
Issue priority labels
|
||||
=====================
|
||||
|
||||
============= ===============================================================
|
||||
Labels ``priority:{high|medium|low}``
|
||||
Applicable to Issues only
|
||||
Description To classify the impact and importance of a bug or
|
||||
:ref:`feature <feature-tracking>`
|
||||
============= ===============================================================
|
||||
|
||||
Note: Issue priorities are generally set or changed during the bug-triage or TSC
|
||||
meetings.
|
||||
|
||||
Miscellaneous labels
|
||||
====================
|
||||
|
||||
For both PRs and issues
|
||||
-----------------------
|
||||
|
||||
+------------------------+-----------------------------------------------------+
|
||||
|``Bug`` | The issue is a bug, or the PR is fixing a bug |
|
||||
+------------------------+-----------------------------------------------------+
|
||||
|``Coverity`` | A Coverity detected issue or its fix |
|
||||
+------------------------+-----------------------------------------------------+
|
||||
|``Waiting for response``| The Zephyr developers are waiting for the submitter |
|
||||
| | to respond to a question, or address an issue. |
|
||||
+------------------------+-----------------------------------------------------+
|
||||
|``Blocked`` | Blocked by another PR or issue |
|
||||
+------------------------+-----------------------------------------------------+
|
||||
|``In progress`` | For PRs: is work in progress and should not be |
|
||||
| | merged yet. For issues: Is being worked on |
|
||||
+------------------------+-----------------------------------------------------+
|
||||
|``RFC`` | The author would like input from the community. For |
|
||||
| | a PR it should be considered a draft |
|
||||
+------------------------+-----------------------------------------------------+
|
||||
|``LTS`` | Long term release branch related |
|
||||
+------------------------+-----------------------------------------------------+
|
||||
|``EXT`` | Related to an external component (in ``ext/``) |
|
||||
+------------------------+-----------------------------------------------------+
|
||||
|
||||
PR only labels
|
||||
--------------
|
||||
|
||||
================ ===============================================================
|
||||
``DNM`` This PR should not be merged (Do Not Merge).
|
||||
For work in progress, GitHub "draft" PRs are preferred
|
||||
``Stale PR`` PR which seems abandoned, and requires attention by the author
|
||||
``Needs review`` The PR needs attention from the maintainers
|
||||
``Backport`` The PR is a backport or should be backported
|
||||
``Licensing`` The PR has licensing issues which require a licensing expert to
|
||||
review it
|
||||
================ ===============================================================
|
||||
|
||||
Issue only labels
|
||||
-----------------
|
||||
|
||||
==================== ===========================================================
|
||||
``Regression`` Something, which was working, but does not anymore
|
||||
(bug subtype)
|
||||
``Question`` This issue is a question to the Zephyr developers
|
||||
``Enhancement`` Changes/Updates/Additions to existing
|
||||
:ref:`features <feature-tracking>`
|
||||
``Feature request`` A request for a new :ref:`feature <feature-tracking>`
|
||||
``Feature`` A :ref:`planned feature<feature-tracking>` with a milestone
|
||||
``Duplicate`` This issue is a duplicate of another issue
|
||||
(please specify)
|
||||
``Good first issue`` Good for a first time contributor to take
|
||||
``Release Notes`` Issues that need to be mentioned in release notes as known
|
||||
issues with additional information
|
||||
==================== ===========================================================
|
||||
|
||||
Any issue must be classified and labeled as either ``Bug``, ``Question``,
|
||||
``Enhancement``, ``Feature``, or ``Feature Request``. More information on how
|
||||
feature requests are handled and become features can be found in
|
||||
:ref:`Feature Tracking<feature-tracking>`.
|
||||
113
doc/project/documentation.rst
Normal file
113
doc/project/documentation.rst
Normal file
|
|
@ -0,0 +1,113 @@
|
|||
.. _code-documentation:
|
||||
|
||||
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 provides
|
||||
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 requirements.
|
||||
|
||||
|
||||
Documentation Guidelines
|
||||
*************************
|
||||
|
||||
Test Code
|
||||
=========
|
||||
|
||||
The Zephyr project uses several test methodologies, the most common being the
|
||||
:ref:`Ztest framework <test-framework>`. Test documentation 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 from 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 custom doxygen ``@verify`` directive signifies that a test verifies a
|
||||
requirement::
|
||||
|
||||
/**
|
||||
* @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
|
||||
*
|
||||
* @verify{@req{1111}}
|
||||
*/
|
||||
void test_sema_thread2thread(void)
|
||||
{
|
||||
...
|
||||
}
|
||||
...
|
||||
|
||||
/**
|
||||
* @}
|
||||
*/
|
||||
|
||||
To get coverage of how an implementation or a piece of code satisfies a
|
||||
requirements, we use the ``satisfy`` alias in doxygen::
|
||||
|
||||
/**
|
||||
* @brief Give a semaphore.
|
||||
*
|
||||
* This routine gives @a sem, unless the semaphore is already at its maximum
|
||||
* permitted count.
|
||||
*
|
||||
* @note Can be called by ISRs.
|
||||
*
|
||||
* @param sem Address of the semaphore.
|
||||
*
|
||||
* @satisfy{@req{015}}
|
||||
*/
|
||||
__syscall void k_sem_give(struct k_sem *sem);
|
||||
|
||||
|
||||
|
||||
To generate the matrix, you will first need to build the documentation,
|
||||
specifically you will need to build the doxygen XML output::
|
||||
|
||||
$ make doxygen
|
||||
|
||||
Parse the generated XML data from doxygen to generate the traceability matrix.
|
||||
BIN
doc/project/img/img_release_activity.png
Normal file
BIN
doc/project/img/img_release_activity.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 29 KiB |
51
doc/project/index.rst
Normal file
51
doc/project/index.rst
Normal file
|
|
@ -0,0 +1,51 @@
|
|||
.. _development_model:
|
||||
|
||||
Project and Governance
|
||||
#######################
|
||||
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
|
||||
project_roles.rst
|
||||
release_process
|
||||
proposals
|
||||
code_flow
|
||||
modifying_contributions.rst
|
||||
dev_env_and_tools
|
||||
issues
|
||||
communication
|
||||
documentation
|
||||
|
||||
|
||||
|
||||
The Zephyr project defines a development process workflow using GitHub
|
||||
**Issues** to track feature, enhancement, and bug reports together with GitHub
|
||||
**Pull Requests** (PRs) for submitting and reviewing changes. Zephyr
|
||||
community members work together to review these Issues and PRs, managing
|
||||
feature enhancements and quality improvements of Zephyr through its regular
|
||||
releases, as outlined in the
|
||||
`program management overview <https://wiki.zephyrproject.org/Program-Management>`_.
|
||||
|
||||
We can only manage the volume of Issues and PRs, by requiring timely reviews,
|
||||
feedback, and responses from the community and contributors, both for initial
|
||||
submissions and for followup questions and clarifications. Read about the
|
||||
project's :ref:`development processes and tools <dev-environment-and-tools>`
|
||||
and specifics about :ref:`review timelines <review_time>` to learn about the
|
||||
project's goals and guidelines for our active developer community.
|
||||
|
||||
:ref:`project_roles` describes in detail the Zephyr project roles and associated permissions
|
||||
with respect to the development process workflow.
|
||||
|
||||
|
||||
Terminology
|
||||
***********
|
||||
|
||||
- mainline: The main tree where the core functionality and core features are
|
||||
being developed.
|
||||
- subsystem/feature branch: is a branch within the same repository. In our case,
|
||||
we will use the term branch also when referencing branches not in the same
|
||||
repository, which are a copy of a repository sharing the same history.
|
||||
- upstream: A parent branch the source code is based on. This is the branch you
|
||||
pull from and push to, basically your upstream.
|
||||
- LTS: Long Term Support
|
||||
36
doc/project/issues.rst
Normal file
36
doc/project/issues.rst
Normal file
|
|
@ -0,0 +1,36 @@
|
|||
.. _bug_reporting:
|
||||
|
||||
Bug Reporting
|
||||
##############
|
||||
|
||||
To maintain traceability and relation between proposals, changes, features, and
|
||||
issues, it is recommended to cross-reference source code commits with the
|
||||
relevant GitHub issues and vice versa.
|
||||
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
|
||||
identifiers.
|
||||
|
||||
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.
|
||||
|
||||
Reporting a regression issue
|
||||
****************************
|
||||
|
||||
It could happen that the issue being reported is identified as a regression,
|
||||
as the use case is known to be working on earlier commit or release.
|
||||
In this case, providing directly the guilty commit when submitting the bug
|
||||
gains a lot of time in the eventual bug fixing.
|
||||
|
||||
To identify the commit causing the regression, several methods could be used,
|
||||
but tree bisecting method is an efficient one that doesn't require deep code
|
||||
expertise and can be used by every one.
|
||||
|
||||
For this, `git bisect`_ is the recommended tool.
|
||||
|
||||
Recommendations on the process:
|
||||
|
||||
* Run ``west update`` on each bisection step.
|
||||
* Once the bisection is over and a culprit identified, verify manually the result.
|
||||
|
||||
.. _git bisect:
|
||||
https://git-scm.com/docs/git-bisect
|
||||
BIN
doc/project/lts.png
Normal file
BIN
doc/project/lts.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 17 KiB |
BIN
doc/project/milestones.jpg
Normal file
BIN
doc/project/milestones.jpg
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 59 KiB |
BIN
doc/project/milestones2.jpg
Normal file
BIN
doc/project/milestones2.jpg
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 105 KiB |
70
doc/project/modifying_contributions.rst
Normal file
70
doc/project/modifying_contributions.rst
Normal file
|
|
@ -0,0 +1,70 @@
|
|||
.. _modifying_contributions:
|
||||
|
||||
Modifying Contributions made by other developers
|
||||
************************************************
|
||||
|
||||
Scenarios
|
||||
#########
|
||||
|
||||
Zephyr contributors and collaborators are encouraged to assist
|
||||
as reviewers in pull requests, so that patches may be approved and merged
|
||||
to Zephyr's main branch as part of the original pull requests. The authors
|
||||
of the pull requests are responsible for amending their original commits
|
||||
following the review process.
|
||||
|
||||
There are occasions, however, when a contributor might need to modify patches
|
||||
included in pull requests that are submitted by other Zephyr contributors.
|
||||
For instance, this is the case when:
|
||||
|
||||
* a developer cherry-picks commits submitted by other contributors into their
|
||||
own pull requests in order to:
|
||||
|
||||
* integrate useful content which is part of a stale pull request, or
|
||||
* get content merged to the project's main branch as part of a larger
|
||||
patch
|
||||
|
||||
* a developer pushes to a branch or pull request opened by another
|
||||
contributor in order to:
|
||||
|
||||
* assist in updating pull requests in order to get the patches merged
|
||||
to the project's main branch
|
||||
* drive stale pull requests to completion so they can be merged
|
||||
|
||||
|
||||
Accepted policies
|
||||
#################
|
||||
|
||||
A developer who intends to cherry-pick and potentially modify patches sent by
|
||||
another contributor shall:
|
||||
|
||||
* clarify in their pull request the reason for cherry-picking the patches,
|
||||
instead of assisting in getting the patches merged in their original
|
||||
pull request, and
|
||||
* invite the original author of the patches to their pull request review.
|
||||
|
||||
A developer who intends to force-push to a branch or pull request of
|
||||
another Zephyr contributor shall clarify in the pull request the reason
|
||||
for pushing and for modifying the existing patches (e.g. stating that it
|
||||
is done to drive the pull request review to completion, when the pull
|
||||
request author is not able to do so).
|
||||
|
||||
.. note::
|
||||
Developers should try to limit the above practice to pull requests identified
|
||||
as *stale*. Read about how to identify pull requests as stale in
|
||||
:ref:`development processes and tools <dev-environment-and-tools>`
|
||||
|
||||
If the original patches are substantially modified, the developer can either:
|
||||
|
||||
* (preferably) reach out to the original author and request them to
|
||||
acknowledge that the modified patches may be merged while having
|
||||
the original sign-off line and author identity, or
|
||||
* submit the modified patches as their *own* work (i.e. with their
|
||||
*own* sign-off line and author identity). In this case, the developer
|
||||
shall identify in the commit message(s) the original source the
|
||||
submitted work is based on (mentioning, for example, the original PR
|
||||
number).
|
||||
|
||||
.. note::
|
||||
Contributors should uncheck the box *“Allow Edits By Maintainers"*
|
||||
to indicate that they do not wish their patches to be amended,
|
||||
inside their original branch or pull request, by other Zephyr developers.
|
||||
364
doc/project/project_roles.rst
Normal file
364
doc/project/project_roles.rst
Normal file
|
|
@ -0,0 +1,364 @@
|
|||
.. _project_roles:
|
||||
|
||||
TSC Project Roles
|
||||
*****************
|
||||
|
||||
Main Roles
|
||||
##########
|
||||
|
||||
TSC projects generally will involve *Maintainers*, *Collaborators*, and
|
||||
*Contributors*:
|
||||
|
||||
**Maintainer**: lead Collaborators on an area identified by the TSC (e.g.
|
||||
Architecture, code subsystems, etc.). Maintainers shall also serve as the
|
||||
area’s representative on the TSC as needed. Maintainers may become voting
|
||||
members of the TSC under the guidelines stated in the project Charter.
|
||||
|
||||
**Collaborator**: A highly involved Contributor in one or more areas.
|
||||
May become a Maintainer with approval of existing TSC voting members.
|
||||
|
||||
**Contributor**: anyone in the community that contributes code or
|
||||
documentation to the project. Contributors may become Collaborators
|
||||
by approval of the existing Collaborators and Maintainers of the
|
||||
particular code base areas or subsystems.
|
||||
|
||||
|
||||
Contributor
|
||||
+++++++++++
|
||||
|
||||
A *Contributor* is a developer who wishes to contribute to the project,
|
||||
at any level.
|
||||
|
||||
Contributors are granted the following rights and responsibilities:
|
||||
|
||||
* Right to contribute code, documentation, translations, artwork, etc.
|
||||
* Right to report defects (bugs) and suggestions for enhancement.
|
||||
* Right to participate in the process of reviewing contributions by others.
|
||||
* Right to initiate and participate in discussions in any communication
|
||||
methods.
|
||||
* Right to approach any member of the community with matters they believe
|
||||
to be important.
|
||||
* Right to participate in the feature development process.
|
||||
* Responsibility to abide by decisions, once made. They are welcome to
|
||||
provide new, relevant information to reopen decisions.
|
||||
* Responsibility for issues and bugs introduced by one’s own contributions.
|
||||
* Responsibility to respect the rules of the community.
|
||||
* Responsibility to provide constructive advice whenever participating in
|
||||
discussions and in the review of contributions.
|
||||
* Responsibility to follow the project’s code of conduct
|
||||
(https://github.com/zephyrproject-rtos/zephyr/blob/main/CODE_OF_CONDUCT.md)
|
||||
|
||||
Contributors are initially only given `Read
|
||||
<https://docs.github.com/en/organizations/managing-access-to-your-organizations-repositories/repository-permission-levels-for-an-organization>`_
|
||||
access to the Zephyr GitHub repository. Specifically, at the Read access level,
|
||||
Contributors are not allowed to assign reviewers to their own pull requests. An
|
||||
automated process will assign reviewers. You may also share the pull request on
|
||||
the `Zephyr devel mailing list <https://lists.zephyrproject.org/g/devel>`_ or on
|
||||
the `Zephyr Discord Server <https://chat.zephyrproject.org>`_.
|
||||
|
||||
Contributors who show dedication and skill are granted the Triage permission
|
||||
level to the Zephyr GitHub repository.
|
||||
|
||||
You may nominate yourself, or another GitHub user, for promotion to the Triage
|
||||
permission level by creating a GitHub issue, using the :github:`nomination
|
||||
template <new?assignees=&labels=bug&template=nomination.md&title=>`.
|
||||
|
||||
Contributors granted the Triage permission level are permitted to add reviewers
|
||||
to a pull request and can be added as a reviewer by other GitHub users.
|
||||
Contributor votes on pull requests are not counted with respect to accepting and
|
||||
merging a pull request. However, Contributors comments and requested changes
|
||||
should still be considered by the pull request author.
|
||||
|
||||
Collaborator
|
||||
++++++++++++
|
||||
|
||||
A *Collaborator* is a Contributor who is also responsible for the maintenance
|
||||
of Zephyr source code. Their opinions weigh more when decisions are made, in a
|
||||
fully meritocratic fashion.
|
||||
|
||||
Collaborators have the following rights and responsibilities,
|
||||
in addition to those listed for Contributors:
|
||||
|
||||
* Right to set goals for the short and medium terms for the project being
|
||||
maintained, alongside the Maintainer.
|
||||
* Responsibility to participate in the feature development process.
|
||||
* Responsibility to review relevant code changes within reasonable time.
|
||||
* Responsibility to ensure the quality of the code to expected levels.
|
||||
* Responsibility to participate in community discussions.
|
||||
* Responsibility to mentor new contributors when appropriate
|
||||
* Responsibility to participate in the quality verification and release
|
||||
process, when those happen.
|
||||
|
||||
Contributors are promoted to the Collaborator role by adding the GitHub user
|
||||
name to one or more ``collaborators`` sections of the :ref:`maintainers_file` in
|
||||
the Zephyr repository.
|
||||
|
||||
Collaborator votes on pull requests can block or approve the pull request.
|
||||
|
||||
Maintainer
|
||||
++++++++++
|
||||
|
||||
A *Maintainer* is a Collaborator who is also responsible for knowing,
|
||||
directing and anticipating the needs of a given zephyr source code area.
|
||||
|
||||
Maintainers have the following rights and responsibilities,
|
||||
in addition to those listed for Contributors and Collaborators:
|
||||
|
||||
* Right to set the overall architecture of the relevant subsystems or areas
|
||||
of involvement.
|
||||
* Right to make decisions in the relevant subsystems or areas of involvement,
|
||||
in conjunction with the collaborators.
|
||||
* Responsibility to convey the direction of the relevant subsystem or areas to
|
||||
the TSC
|
||||
* Responsibility to ensure all contributions of the project have been reviewed
|
||||
within reasonable time.
|
||||
* Responsibility to enforce the code of conduct.
|
||||
|
||||
Contributors or Collaborators are promoted to the Maintainer role by adding the
|
||||
GitHub user name to one or more ``maintainers`` sections of the
|
||||
:ref:`maintainers_file` in the Zephyr repository.
|
||||
|
||||
Maintainer votes on pull requests can block or approve the pull request.
|
||||
|
||||
Role Retirement
|
||||
###############
|
||||
|
||||
* Individuals elected to the following Project roles, including, Maintainer,
|
||||
Release Engineering Team member, Release Manager, but are no longer engaged
|
||||
in the project as described by the rights and responsibilities of that role,
|
||||
may be requested by the TSC to retire from the role they are elected.
|
||||
* Such a request needs to be raised as a motion in the TSC and be
|
||||
approved by the TSC voting members.
|
||||
By approval of the TSC the individual is considered to be retired
|
||||
from the role they have been elected.
|
||||
* The above applies to elected TSC Project roles that may be defined
|
||||
in addition.
|
||||
|
||||
|
||||
Teams and Supporting Activities
|
||||
###############################
|
||||
|
||||
Assignee
|
||||
++++++++
|
||||
|
||||
An *Assignee* is one of the maintainers of a subsystem or code being changed.
|
||||
Assignees are set either automatically based on the code being changed or set
|
||||
by the other Maintainers, the Release Engineering team can set an assignee when
|
||||
the latter is not possible.
|
||||
|
||||
* Right to dismiss stale reviews and seek reviews from additional maintainers,
|
||||
developers and contributors
|
||||
* Right to block pull requests from being merged
|
||||
* Responsibility to re-assign a pull request if they are the original submitter
|
||||
of the code
|
||||
* Responsibility to drive the pull request to a mergeable state
|
||||
* Solicit approvals from maintainers of the subsystems affected
|
||||
* Responsibility to drive the escalation process
|
||||
|
||||
Release Engineering Team
|
||||
++++++++++++++++++++++++
|
||||
|
||||
A team of active Maintainers involved in multiple areas.
|
||||
|
||||
* The members of the Release Engineering team are expected to fill
|
||||
the Release Manager role based on a defined cadence and selection process.
|
||||
* The cadence and selection process are defined by the Release Engineering
|
||||
team and are approved by the TSC.
|
||||
* The team reports directly into the TSC.
|
||||
|
||||
Release Engineering team has the following rights and responsibilities:
|
||||
|
||||
* Right to merge code changes to the zephyr tree following the project rules.
|
||||
* Right to revert any changes that have broken the code base
|
||||
* Right to close any stale changes after <N> months of no activity
|
||||
* Responsibility to take directions from the TSC and follow them.
|
||||
* Responsibility to coordinate code merges with maintainers.
|
||||
* Responsibility to merge all contributions regardless of their
|
||||
origin and area if they have been approved by the respective
|
||||
maintainers and follow the merge criteria of a change.
|
||||
* Responsibility to keep the Zephyr code base in a working and passing state
|
||||
(as per CI)
|
||||
|
||||
Joining the Release Engineering team
|
||||
|
||||
* Maintainers highly involved in the project may be nominated
|
||||
by a TSC voting member to join the Release Engineering team.
|
||||
Nominees may become members of the team by approval of the
|
||||
existing TSC voting members.
|
||||
* To ensure a functional Release Engineering team the TSC shall
|
||||
periodically review the team’s followed processes,
|
||||
the appropriate size, and the membership
|
||||
composition (ensure, for example, that team members are
|
||||
geographically distributed across multiple locations and
|
||||
time-zones).
|
||||
|
||||
|
||||
Release Manager
|
||||
+++++++++++++++
|
||||
|
||||
A *Maintainer* responsible for driving a specific release to
|
||||
completion following the milestones and the roadmap of the
|
||||
project for this specific release.
|
||||
|
||||
* TSC has to approve a release manager.
|
||||
|
||||
A Release Manager is a member of the Release Engineering team and has
|
||||
the rights and responsibilities of that team in addition to
|
||||
the following:
|
||||
|
||||
* Right to manage and coordinate all code merges after the
|
||||
code freeze milestone (M3, see `program management overview <https://wiki.zephyrproject.org/Program-Management>`_.)
|
||||
* Responsibility to drive and coordinate the triaging process
|
||||
for the release
|
||||
* Responsibility to create the release notes of the release
|
||||
* Responsibility to notify all stakeholders of the project,
|
||||
including the community at large about the status of the
|
||||
release in a timely manner.
|
||||
* Responsibility to coordinate with QA and validation and
|
||||
verify changes either directly or through QA before major
|
||||
changes and major milestones.
|
||||
|
||||
Roles / Permissions
|
||||
+++++++++++++++++++
|
||||
|
||||
.. table:: Project Roles vs GitHub Permissions
|
||||
:widths: 20 20 10 10 10 10 10
|
||||
:align: center
|
||||
|
||||
================ =================== =========== ================ =========== =========== ============
|
||||
.. .. **Admin** **Merge Rights** Member Owner Collaborator
|
||||
---------------- ------------------- ----------- ---------------- ----------- ----------- ------------
|
||||
Main Roles Contributor x
|
||||
---------------- ------------------- ----------- ---------------- ----------- ----------- ------------
|
||||
.. Collaborator x
|
||||
---------------- ------------------- ----------- ---------------- ----------- ----------- ------------
|
||||
.. Maintainer x
|
||||
Supportive Roles QA/Validation x x
|
||||
.. DevOps **x**
|
||||
.. System Admin **x** x
|
||||
.. Release Engineering **x** **x** x
|
||||
|
||||
================ =================== =========== ================ =========== =========== ============
|
||||
|
||||
|
||||
.. _maintainers_file:
|
||||
|
||||
MAINTAINERS File
|
||||
################
|
||||
|
||||
Generic guidelines for deciding and filling in the Maintainers' list
|
||||
|
||||
* The :zephyr_file:`MAINTAINERS.yml` file shall replace the
|
||||
:zephyr_file:`CODEOWNERS` file and will be used for both setting assignees and
|
||||
reviewers.
|
||||
* We should keep the granularity of code maintainership at a manageable level
|
||||
* We should be looking for maintainers for areas of code that
|
||||
are orphaned (i.e. without an explicit maintainer)
|
||||
|
||||
* Un-maintained areas should be indicated clearly in the MAINTAINERS file
|
||||
|
||||
* All submitted pull requests should have an assignee
|
||||
* We Introduce an area/subsystem hierarchy to address the above point
|
||||
|
||||
* Parent-area maintainer should be acting as default substitute/fallback
|
||||
assignee for un-maintained sub-areas
|
||||
* Area maintainer gets precedence over parent-area maintainer
|
||||
|
||||
* Pull requests may be re-assigned if this is needed or more appropriate
|
||||
|
||||
* Re-assigned by original assignee (see “Assignee” slide)
|
||||
|
||||
* In general, updates to the MAINTAINERS file should be
|
||||
in a standalone commit alongside other changes introducing new files and
|
||||
directories to the tree.
|
||||
* Major changes to the file, including the addition of new areas with new maintainers
|
||||
should come in as standalone pull requests and require TSC review.
|
||||
* If additional review by the TSC is required, the maintainers of the file
|
||||
should send the requested changes to the TSC and give members of the TSC two
|
||||
(2) days to object to any of the changes to maintainership of areas or the
|
||||
addition of new maintainers or areas.
|
||||
* Path, collaborator and name changes do not require a review by the TSC.
|
||||
* Addition of new areas without a maintainer do not require review by the TSC.
|
||||
* The MAINTAINERS file itself shall have a maintainer
|
||||
* Architectures, core components, sub-systems, samples, tests
|
||||
|
||||
* Each area shall have an explicit maintainer
|
||||
|
||||
* Boards (incl relevant samples, tests), SoCs (incl DTS)
|
||||
* May have a maintainer, shall have a higher-level platform maintainer
|
||||
* Drivers
|
||||
|
||||
* Shall have a driver-area (and API) maintainer
|
||||
* Could have individual driver implementation
|
||||
maintainers but preferably collaborator/contributors
|
||||
* In the above case, platform-specific PRs may be
|
||||
re-assigned to respective collaborator/contributor of driver
|
||||
implementation
|
||||
|
||||
|
||||
Release Activity
|
||||
################
|
||||
|
||||
.. figure:: img/img_release_activity.png
|
||||
:width: 663px
|
||||
:align: center
|
||||
:alt: Release Activity
|
||||
|
||||
Merge Criteria
|
||||
++++++++++++++
|
||||
|
||||
* All continuous integration checks have passed
|
||||
|
||||
* Codeowners
|
||||
* Device Tree
|
||||
* Documentation
|
||||
* Gitlint
|
||||
* Identity/Emails
|
||||
* Kconfig
|
||||
* License
|
||||
* Checkpatch (Coding Style)
|
||||
* Pylint
|
||||
* Integration Tests (Via twister) on emulation/simulation platforms
|
||||
* Simulated Bluetooth Tests
|
||||
|
||||
* Planned
|
||||
|
||||
* Footprint
|
||||
* Code coverage
|
||||
* Coding Guidelines
|
||||
* Static Analysis (Coverity)
|
||||
* Documentation coverage (APIs)
|
||||
|
||||
* PR template with checklist
|
||||
|
||||
* Minimal of 2 approvals
|
||||
|
||||
* A collaborator from the same subsystem.
|
||||
* Alternately another maintainer of another subsystem
|
||||
* Approval by the assignee
|
||||
|
||||
* A minimum review period of 2 days, 4 hours for trivial changes (see
|
||||
:ref:`review_time`). Hotfixes can be merged at any time after CI passes.
|
||||
* All required checks are passing
|
||||
|
||||
Escalation Process
|
||||
++++++++++++++++++
|
||||
|
||||
* Contributors may object to change requests or decisions made by
|
||||
Maintainers.
|
||||
* Process
|
||||
|
||||
* Resolve in the PR among assignee, maintainers and reviewer
|
||||
|
||||
* Assignee to act as moderator if applicable
|
||||
|
||||
* Optionally resolve in the dev review meeting with more Maintainers
|
||||
and project stakeholders
|
||||
|
||||
* The involved parties and the Assignee to be present when
|
||||
the (escalated) issue is discussed
|
||||
|
||||
* TSC: Assignees can escalate to the TSC voting members and get
|
||||
a binding resolution in the TSC.
|
||||
* Assignee to ensure the resolution of the escalation is
|
||||
reflected in the PR review.
|
||||
162
doc/project/proposals.rst
Normal file
162
doc/project/proposals.rst
Normal file
|
|
@ -0,0 +1,162 @@
|
|||
.. _feature-tracking:
|
||||
|
||||
Feature Tracking
|
||||
#################
|
||||
|
||||
For feature tracking we use Github labels to classify new features and
|
||||
enhancements. The following is the description of each category:
|
||||
|
||||
Enhancement
|
||||
Changes to existing features that are not considered a bug and would not
|
||||
block a release. This is an incremental enhancement to a feature that already
|
||||
exists in Zephyr.
|
||||
|
||||
Feature request
|
||||
A request for the implementation or inclusion of a new unit of functionality
|
||||
that is not part of any release plans yet, that has not been vetted, and needs
|
||||
further discussion and details.
|
||||
|
||||
Feature
|
||||
A committed and planned unit of functionality with a detailed design and
|
||||
implementation proposal and an owner. Features must go through an RFC process
|
||||
and must be vetted and discussed in the TSC before a target milestone is set.
|
||||
|
||||
Hardware Support
|
||||
A request or plan to port an existing feature or enhancement to a particular
|
||||
hardware platform. This ranges from porting Zephyr itself to a new
|
||||
architecture, SoC or board to adding an implementation of a peripheral driver
|
||||
API for an existing hardware platform.
|
||||
|
||||
Meta
|
||||
A label to group other GitHub issues that are part of a single feature or unit
|
||||
of work.
|
||||
|
||||
The following workflow should be used to process features:.
|
||||
|
||||
This is the formal way for asking for a new feature in Zephyr and indicating its
|
||||
importance to the project. Often, the requester may have a readiness and
|
||||
willingness to drive implementation of the feature in an upcoming release, and
|
||||
should assign the request to themselves.
|
||||
If not though, an owner will be assigned after evaluation by the TSC.
|
||||
A feature request can also have a companion RFC with more details on the feature
|
||||
and a proposed design or implementation.
|
||||
|
||||
- Label new features requests as ``feature-request``
|
||||
- The TSC discusses new ``feature-request`` items regularly and triages them.
|
||||
Items are examined for similarity with existing features, how they fit with
|
||||
the project goals and other timeline considerations. The priority is
|
||||
determined as follows:
|
||||
|
||||
- High = Next milestone
|
||||
- Medium = As soon as possible
|
||||
- Low = Best effort
|
||||
|
||||
- After the initial discussion and triaging, the label is moved from
|
||||
``feature-request`` to ``feature`` with the target milestone and an assignee.
|
||||
|
||||
All items marked as ``feature-request`` are non-binding and those without an
|
||||
assignee are open for grabs, meaning that they can be picked up and implemented
|
||||
by any project member or the community. You should contact an assigned owner if
|
||||
you'd like to discuss or contribute to that feature's implementation
|
||||
|
||||
|
||||
.. _rfcs:
|
||||
|
||||
Proposals and RFCs
|
||||
*******************
|
||||
|
||||
Many changes, including bug fixes and documentation improvements can be
|
||||
implemented and reviewed via the normal GitHub pull request workflow.
|
||||
|
||||
Many changes however are "substantial" and need to go through a
|
||||
design process and produce a consensus among the project stakeholders.
|
||||
|
||||
The "RFC" (request for comments) process is intended to provide a consistent and
|
||||
controlled path for new features to enter the project.
|
||||
|
||||
Contributors and project stakeholders should consider using this process if
|
||||
they intend to make "substantial" changes to Zephyr or its documentation. Some
|
||||
examples that would benefit from an RFC are:
|
||||
|
||||
- A new feature that creates new API surface area, and would require a feature
|
||||
flag if introduced.
|
||||
- The modification of an existing stable API
|
||||
- The removal of features that already shipped as part of Zephyr.
|
||||
- The introduction of new idiomatic usage or conventions, even if they do not
|
||||
include code changes to Zephyr itself.
|
||||
|
||||
The RFC process is a great opportunity to get more eyeballs on proposals coming
|
||||
from contributors before it becomes a part of Zephyr. Quite often, even
|
||||
proposals that seem "obvious" can be significantly improved once a wider group
|
||||
of interested people have a chance to weigh in.
|
||||
|
||||
The RFC process can also be helpful to encourage discussions about a proposed
|
||||
feature as it is being designed, and incorporate important constraints into the
|
||||
design while it's easier to change, before the design has been fully
|
||||
implemented.
|
||||
|
||||
Some changes do not require an RFC:
|
||||
|
||||
- Rephrasing, reorganizing or refactoring
|
||||
- Addition or removal of warnings
|
||||
- Addition of new boards, SoCs or drivers to existing subsystems
|
||||
- ...
|
||||
|
||||
The process in itself consists in creating a GitHub issue with the :ref:`RFC
|
||||
label <gh_labels>` that documents the proposal thoroughly. There is an `RFC
|
||||
template`_ included in the main Zephyr GitHub repository that serves as a
|
||||
guideline to write a new RFC.
|
||||
|
||||
As with Pull Requests, RFCs might require discussion in the context of one of
|
||||
the `Zephyr meetings`_ in order to move it forward in cases where there is
|
||||
either disagreement or not enough voiced opinions in order to proceed. Make sure
|
||||
to either label it appropriately or include it in the corresponding GitHub
|
||||
project in order for it to be examined during the next meeting.
|
||||
|
||||
Roadmap and Release Plans
|
||||
*************************
|
||||
|
||||
Project roadmaps and release plans are both important tools for the project, but
|
||||
they have very different purposes and should not be confused. A project roadmap
|
||||
communicates the high-level overview of a project's strategy, while a release
|
||||
plan is a tactical document designed to capture and track the features planned
|
||||
for upcoming releases.
|
||||
|
||||
- The project roadmap communicates the why; a release plan details the what
|
||||
- A release plan spans only a few months; a product roadmap might cover a year
|
||||
or more
|
||||
|
||||
|
||||
Project Roadmap
|
||||
================
|
||||
|
||||
The project roadmap should serve as a high-level, visual summary of the
|
||||
project's strategic objectives and expectations.
|
||||
|
||||
If built properly, the roadmap can be a valuable tool for several reasons. It
|
||||
can help the project present its plan in a compelling way to existing and new
|
||||
stakeholders, to help recruit new members and it can be a helpful resource the
|
||||
team and community can refer to throughout the project's development, to ensure
|
||||
they are still executing according to plan.
|
||||
|
||||
As such, the roadmap should contain only strategic-level details, major project
|
||||
themes, epics, and goals.
|
||||
|
||||
|
||||
Release Plans
|
||||
==============
|
||||
|
||||
The release plan comes into play when the project roadmap's high-level strategy
|
||||
is translated into an actionable plan built on specific features, enhancements,
|
||||
and fixes that need to go into a specific release or milestone.
|
||||
|
||||
The release plan communicates those features and enhancements slated for your
|
||||
project' next release (or the next few releases). So it acts as more of a
|
||||
project plan, breaking the big ideas down into smaller projects the community
|
||||
and main stakeholders of the project can make progress on.
|
||||
|
||||
Items labeled as ``features`` are short or long term release items that shall
|
||||
have an assignee and a milestone set.
|
||||
|
||||
.. _`RFC template`: https://github.com/zephyrproject-rtos/zephyr/blob/main/.github/ISSUE_TEMPLATE/rfc-proposal.md
|
||||
.. _`Zephyr meetings`: https://github.com/zephyrproject-rtos/zephyr/wiki/Zephyr-Committee-and-Working-Group-Meetings
|
||||
BIN
doc/project/pull_request_classes.png
Normal file
BIN
doc/project/pull_request_classes.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 38 KiB |
BIN
doc/project/release_cycle.png
Normal file
BIN
doc/project/release_cycle.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 36 KiB |
BIN
doc/project/release_flow.png
Normal file
BIN
doc/project/release_flow.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 67 KiB |
470
doc/project/release_process.rst
Normal file
470
doc/project/release_process.rst
Normal file
|
|
@ -0,0 +1,470 @@
|
|||
.. _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 4-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 main branch,
|
||||
- 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 quality metrics have been achieved
|
||||
at which point the final 0.4.x release is made.
|
||||
|
||||
At that point, the whole process starts over again.
|
||||
|
||||
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_quality_criteria:
|
||||
|
||||
Release Quality Criteria
|
||||
************************
|
||||
|
||||
The current backlog of prioritized bugs shall be used as a quality metric to
|
||||
gate the final release. The following counts shall be used:
|
||||
|
||||
.. csv-table:: Bug Count Release Thresholds
|
||||
:header: "High", "Medium", "Low"
|
||||
:widths: auto
|
||||
|
||||
|
||||
"0","<20","<50"
|
||||
|
||||
.. note::
|
||||
|
||||
The "low" bug count target of <50 will be a phased approach starting with 150
|
||||
for release 2.4.0, 100 for release 2.5.0, and 50 for release 2.6.0
|
||||
|
||||
|
||||
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 main 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 main branch version. Presence of this tag allows generation of
|
||||
sensible output for "git describe" on main branch, 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 and maintained
|
||||
for an extended period and is the recommended release for
|
||||
products and the auditable branch used for certification.
|
||||
|
||||
An LTS release is defined as:
|
||||
|
||||
- **Product focused**
|
||||
- **Extended Stabilisation period**: Allow for more testing and bug fixing
|
||||
- **Stable APIs**
|
||||
- **Quality Driven Process**
|
||||
- **Long Term**: Maintained for an extended period of time (at least 2.5 years)
|
||||
overlapping previous LTS release for at least half a year.
|
||||
|
||||
|
||||
Product Focused
|
||||
+++++++++++++++
|
||||
|
||||
Zephyr LTS is the recommended release for product makers with an extended
|
||||
support and maintenance which includes general stability and bug fixes,
|
||||
security fixes.
|
||||
|
||||
An LTS includes both mature and new features. API and feature maturity is
|
||||
documented and tracked. The footprint and scope of mature and stable APIs expands
|
||||
as we move from one LTS to the next giving users access to bleeding edge features
|
||||
and new hardware while keeping a stable foundation that evolves over time.
|
||||
|
||||
Extended Stabilisation Period
|
||||
+++++++++++++++++++++++++++++
|
||||
|
||||
Zephyr LTS development cycle differs from regular releases and has an extended
|
||||
stabilization period. Feature freeze of regular releases happens 3-4 weeks
|
||||
before the scheduled release date. The stabilisation period for LTS is extended
|
||||
by 3 weeks with the feature freeze occurring 6-7 weeks before the anticipated
|
||||
release date. The time between code freeze and release date is extended in this case.
|
||||
|
||||
Stable APIs
|
||||
+++++++++++
|
||||
|
||||
Zephyr LTS provides a stable and long-lived foundation for developing
|
||||
products. To guarantee stability of the APIs and the implementation of such
|
||||
APIs it is required that any release software that makes the core of the OS
|
||||
went through the Zephyr API lifecycle and stabilised over at least 2 releases.
|
||||
This guarantees that we release many of the highlighted and core features with
|
||||
mature and well-established implementations with stable APIs that are
|
||||
supported during the lifetime of the release LTS.
|
||||
|
||||
- API Freeze (LTS - 2)
|
||||
|
||||
- All stable APIs need to be frozen 2 releases before an LTS. APIs can be extended
|
||||
with additional features, but the core implementation is not modified. This
|
||||
is valid for the following subsystems for example:
|
||||
|
||||
- Device Drivers (i2c.h, spi.h)...
|
||||
- Kernel (k_*):
|
||||
- OS services (logging,debugging, ..)
|
||||
- DTS: API and bindings stability
|
||||
- Kconfig
|
||||
|
||||
- New APIs for experimental features can be added at any time as long as they
|
||||
are standalone and documented as experimental or unstable features/APIs.
|
||||
- Feature Freeze (LTS - 1)
|
||||
- No new features or overhaul/restructuring of code covering major LTS features.
|
||||
|
||||
- Kernel + Base OS
|
||||
- Additional advertised LTS features
|
||||
|
||||
- Auxiliary features on top of and/or extending the base OS and advertised LTS features
|
||||
can be added at any time and should be marked as experimental if applicable
|
||||
|
||||
Quality Driven Process
|
||||
++++++++++++++++++++++
|
||||
|
||||
The Zephyr project follows industry standards and processes with the goal of
|
||||
providing a quality oriented releases. This is achieved by providing the
|
||||
following products to track progress, integrity and quality of the software
|
||||
components provided by the project:
|
||||
|
||||
- Compliance with published coding guidelines, style guides and naming
|
||||
conventions and documentation of deviations.
|
||||
- Regular static analysis on the complete tree using available commercial and
|
||||
open-source tools and documentation of deviations and false positives.
|
||||
- Documented components and APIS
|
||||
- Requirements Catalog
|
||||
- Verification Plans
|
||||
- Verification Reports
|
||||
- Coverage Reports
|
||||
- Requirements Traceability Matrix (RTM)
|
||||
- SPDX License Reports
|
||||
|
||||
Each release is created with the above products to document the quality and the
|
||||
state of the software when it was released.
|
||||
|
||||
Long Term Support and Maintenance
|
||||
++++++++++++++++++++++++++++++++++
|
||||
|
||||
A Zephyr LTS release is published every 2 years and is branched and maintained
|
||||
independently from the main tree for at least 2.5 years after it was
|
||||
released. Support and maintenance for an LTS release stops at least half a year
|
||||
after the following LTS release is published.
|
||||
|
||||
.. 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 main branch 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 shall be submitted to
|
||||
mainline tree 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.jpg
|
||||
: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.jpg
|
||||
: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
|
||||
=======
|
||||
|
||||
The final release and each release candidate shall be tagged using the following
|
||||
steps:
|
||||
|
||||
.. note::
|
||||
|
||||
Tagging needs to be done via explicit git commands and not via GitHub's release
|
||||
interface. The GitHub release interface does not generate annotated tags (it
|
||||
generates 'lightweight' tags regardless of release or pre-release). You should
|
||||
also upload your gpg public key to your GitHub account, since the instructions
|
||||
below involve creating signed tags. However, if you do not have a gpg public
|
||||
key you can opt to remove the ``-s`` option from the commands below.
|
||||
|
||||
.. tabs::
|
||||
|
||||
.. tab:: Release Candidate
|
||||
|
||||
.. note::
|
||||
|
||||
This section uses tagging 1.11.0-rc1 as an example, replace with
|
||||
the appropriate release candidate version.
|
||||
|
||||
#. Update the version variables in the :zephyr_file:`VERSION` file
|
||||
located in the root of the Git repository to match the version for
|
||||
this release candidate. The ``EXTRAVERSION`` variable is used to
|
||||
identify the rc[RC Number] value for this candidate::
|
||||
|
||||
EXTRAVERSION = rc1
|
||||
|
||||
#. Post a PR with the updated :zephyr_file:`VERSION` file using
|
||||
``release: Zephyr 1.11.0-rc1`` as the commit subject. Merge
|
||||
the PR after successful CI.
|
||||
#. Tag and push the version, using an annotated tag::
|
||||
|
||||
$ git pull
|
||||
$ git tag -s -m "Zephyr 1.11.0-rc1" v1.11.0-rc1
|
||||
$ git push git@github.com:zephyrproject-rtos/zephyr.git v1.11.0-rc1
|
||||
|
||||
#. Once the tag is pushed, a github action will create a draft release
|
||||
in Github with a shortlog since the last tag. The action will also
|
||||
create a SPDX manifest of the Zephyr tree and will add the file as an
|
||||
asset in the release.
|
||||
|
||||
Go to the draft release that was created and edit as needed. If this
|
||||
step fails for a reason, it can be done manually following the steps
|
||||
below:
|
||||
|
||||
#. Create a shortlog of changes between the previous release (use
|
||||
rc1..rc2 between release candidates)::
|
||||
|
||||
$ git shortlog v1.10.0..v1.11.0-rc1
|
||||
|
||||
#. Find the new tag at the top of the releases page and edit the release
|
||||
with the ``Edit tag`` button with the following:
|
||||
|
||||
* 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
|
||||
|
||||
#. Send an email to the mailing lists (``announce`` and ``devel``)
|
||||
with a link to the release
|
||||
|
||||
.. tab:: Final Release
|
||||
|
||||
.. note::
|
||||
|
||||
This section uses tagging 1.11.0 as an example, replace with the
|
||||
appropriate final release version.
|
||||
|
||||
When all final release criteria has been met and the final release notes
|
||||
have been approved and merged into the repository, the final release version
|
||||
will be set and repository tagged using the following procedure:
|
||||
|
||||
#. Update the version variables in the :zephyr_file:`VERSION` file
|
||||
located in the root of the Git repository. Set ``EXTRAVERSION``
|
||||
variable to an empty string to indicate final release::
|
||||
|
||||
EXTRAVERSION =
|
||||
|
||||
#. Post a PR with the updated :zephyr_file:`VERSION` file using
|
||||
``release: Zephyr 1.11.0`` as the commit subject. Merge
|
||||
the PR after successful CI.
|
||||
#. Tag and push the version, using two annotated tags::
|
||||
|
||||
$ git pull
|
||||
$ git tag -s -m "Zephyr 1.11.0" v1.11.0
|
||||
$ git push git@github.com:zephyrproject-rtos/zephyr.git v1.11.0
|
||||
|
||||
# This is the tag that will represent the release on GitHub, so that
|
||||
# the file you can download is named ``zephyr-v1.11.0.zip`` and not
|
||||
# just ``v1.11.0.zip``
|
||||
$ git tag -s -m "Zephyr 1.11.0" zephyr-v1.11.0
|
||||
$ git push git@github.com:zephyrproject-rtos/zephyr.git zephyr-v1.11.0
|
||||
|
||||
#. Find the new ``zephyr-v1.11.0`` tag at the top of the releases page
|
||||
and edit the release with the ``Edit tag`` button with the following:
|
||||
|
||||
* Name it ``Zephyr 1.11.0``
|
||||
* Copy the full content of ``docs/releases/release-notes-1.11.rst``
|
||||
into the release notes textbox
|
||||
|
||||
#. 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 -s --format=%ci zephyr-v1.10.0
|
||||
tag zephyr-v1.10.0
|
||||
Tagger: Kumar Gala <kumar.gala@linaro.org>
|
||||
|
||||
Zephyr 1.10.0
|
||||
2017-12-08 13:32:22 -0600
|
||||
|
||||
|
||||
#. Use available release tools to list all the issues that have been closed
|
||||
between that date and the day of the release.
|
||||
Loading…
Add table
Add a link
Reference in a new issue