diff --git a/doc/project/code_flow.rst b/doc/project/code_flow.rst index 19276ab24c..5ad6e86ab0 100644 --- a/doc/project/code_flow.rst +++ b/doc/project/code_flow.rst @@ -11,19 +11,25 @@ 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 +collab-\* + Collaboration branches that are used for shared development + of new features to be introduced into the main branch when ready. Creating a new + collaboration branch requires a justification and TSC approval. Collaboration branches + shall be based off the main branch and any changes developed in the collab + branch shall target the main development branch. For released versions of + Zephyr, the introduction of fixes and new features, if approved by the TSC, + shall be done using backport pull requests. 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 +Development in collaboration 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 +Changes submitted to a collaboration branch can evolve and improve incrementally in a branch, before they are submitted to the mainline tree for final integration. @@ -31,13 +37,23 @@ 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. +Collaboration branches are ephemeral and shall be removed once the collaboration work +has been completed. When a branch is requested, the proposal should include the +following: + +* Define exit criteria for merging the collaboration branch changes back into the main branch. +* Define a timeline for the expected life cycle of the branch. It is + recommended to select a Zephyr release to set the timeline. Extensions to + this timeline requires TSC approval. Roles and Responsibilities ************************** -Development topic branch owners have the following responsibilities: +Collaboration branch owners have the following responsibilities: - Use the infrastructure and tools provided by the project (GitHub, Git) +- All changes to collaboration branches shall come in form of github pull requests. +- Force pushing a collaboration branch is only allowed when rebasing against the main branch. - 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. @@ -46,4 +62,4 @@ Development topic branch owners have the following responsibilities: - 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. + has been reviewed and tested in a collaboration branch.