diff --git a/doc/development_process/index.rst b/doc/development_process/index.rst new file mode 100644 index 00000000000..662fbf203c1 --- /dev/null +++ b/doc/development_process/index.rst @@ -0,0 +1,300 @@ +.. _development_model: + +Development Model +################# + +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 + +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 requorements +- 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/lts.png b/doc/development_process/lts.png new file mode 100644 index 00000000000..feb2569f32f Binary files /dev/null and b/doc/development_process/lts.png differ diff --git a/doc/development_process/merge_window.png b/doc/development_process/merge_window.png new file mode 100644 index 00000000000..4d96c76d8d9 Binary files /dev/null and b/doc/development_process/merge_window.png differ diff --git a/doc/development_process/release_cycle.png b/doc/development_process/release_cycle.png new file mode 100644 index 00000000000..b7daaf20892 Binary files /dev/null and b/doc/development_process/release_cycle.png differ diff --git a/doc/index.rst b/doc/index.rst index 9cf01cde6d9..ad4b72410e6 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -51,6 +51,7 @@ Source code for the Zephyr Project is maintained in the Zephyr Project's introduction/introducing_zephyr.rst getting_started/getting_started.rst contribute/index.rst + development_process/index.rst application/application.rst kernel/kernel.rst security/security.rst