diff --git a/doc/development_process/api_lifecycle.png b/doc/development_process/api_lifecycle.png new file mode 100644 index 00000000000..fbdb2651a9a Binary files /dev/null and b/doc/development_process/api_lifecycle.png differ diff --git a/doc/development_process/api_lifecycle.rst b/doc/development_process/api_lifecycle.rst new file mode 100644 index 00000000000..2a30858da7b --- /dev/null +++ b/doc/development_process/api_lifecycle.rst @@ -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 `_. + +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. + diff --git a/doc/development_process/code_flow.rst b/doc/development_process/code_flow.rst new file mode 100644 index 00000000000..495848b4f1a --- /dev/null +++ b/doc/development_process/code_flow.rst @@ -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. diff --git a/doc/development_process/communication.rst b/doc/development_process/communication.rst new file mode 100644 index 00000000000..29702a1adc7 --- /dev/null +++ b/doc/development_process/communication.rst @@ -0,0 +1,14 @@ + + +Communication and Collaboration +################################ + +The `Zephyr project mailing lists `_ 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 `_) and not broadcasted to the mailing list, the same applies to +code reviews. Code should be submitted to GitHub using the appropriate tools. + diff --git a/doc/development_process/documentation.rst b/doc/development_process/documentation.rst new file mode 100644 index 00000000000..d84d4f714b7 --- /dev/null +++ b/doc/development_process/documentation.rst @@ -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 `. 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) + { + ... + } + ... + + /** + * @} + */ diff --git a/doc/development_process/index.rst b/doc/development_process/index.rst index 274e8ffd090..b93d99eb6a0 100644 --- a/doc/development_process/index.rst +++ b/doc/development_process/index.rst @@ -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. diff --git a/doc/development_process/issues.rst b/doc/development_process/issues.rst new file mode 100644 index 00000000000..0add7382176 --- /dev/null +++ b/doc/development_process/issues.rst @@ -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. diff --git a/doc/development_process/milestones.png b/doc/development_process/milestones.png new file mode 100644 index 00000000000..122a9cf62bd Binary files /dev/null and b/doc/development_process/milestones.png differ diff --git a/doc/development_process/milestones2.png b/doc/development_process/milestones2.png new file mode 100644 index 00000000000..584f96c3d11 Binary files /dev/null and b/doc/development_process/milestones2.png differ diff --git a/doc/development_process/proposals.rst b/doc/development_process/proposals.rst new file mode 100644 index 00000000000..081f197508f --- /dev/null +++ b/doc/development_process/proposals.rst @@ -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 diff --git a/doc/development_process/pull_request_classes.png b/doc/development_process/pull_request_classes.png new file mode 100644 index 00000000000..544cd3e1a67 Binary files /dev/null and b/doc/development_process/pull_request_classes.png differ diff --git a/doc/development_process/release_flow.png b/doc/development_process/release_flow.png new file mode 100644 index 00000000000..aac0d065d55 Binary files /dev/null and b/doc/development_process/release_flow.png differ diff --git a/doc/development_process/release_process.rst b/doc/development_process/release_process.rst new file mode 100644 index 00000000000..7fd46e633cb --- /dev/null +++ b/doc/development_process/release_process.rst @@ -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 + + $ git push git@github.com:zephyrproject-rtos/zephyr.git v1.11.0-rc1 + + * If it's a release:: + + $ git tag -a v1.11.0 + + $ git push git@github.com:zephyrproject-rtos/zephyr.git v1.11.0 + + $ git tag -a zephyr-v1.11.0 + + $ 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 + 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. diff --git a/doc/development_process/review_process.rst b/doc/development_process/review_process.rst new file mode 100644 index 00000000000..7b17875d756 --- /dev/null +++ b/doc/development_process/review_process.rst @@ -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. +