1.. _code-flow-and-branches:
2
3Code Flow and Branches
4######################
5
6Introduction
7************
8
9The zephyr Git repository has three types of branches:
10
11main
12  Which contains the latest state of development
13
14collab-\*
15  Collaboration branches that are used for shared development
16  of new features to be introduced into the main branch when ready. Creating a new
17  collaboration branch requires a justification and TSC approval. Collaboration branches
18  shall be based off the main branch and any changes developed in the collab
19  branch shall target the main development branch. For released versions of
20  Zephyr, the introduction of fixes and new features, if approved by the TSC,
21  shall be done using backport pull requests.
22
23vx.y-branch
24  Branches which track maintenance releases based on a major
25  release
26
27Development in collaboration branches before features go to mainline allows teams to
28work independently on a subsystem or a feature, improves efficiency and
29turnaround time, and encourages collaboration and streamlines communication
30between developers.
31
32Changes submitted to a collaboration branch can evolve and improve
33incrementally in a branch, before they are submitted to the mainline tree for
34final integration.
35
36By dedicating an isolated branch to complex features, it's
37possible to initiate in-depth discussions around new additions before
38integrating them into the official project.
39
40Collaboration branches are ephemeral and shall be removed once the collaboration work
41has been completed. When a branch is requested, the proposal should include the
42following:
43
44* Define exit criteria for merging the collaboration branch changes back into the main branch.
45* Define a timeline for the expected life cycle of the branch. It is
46  recommended to select a Zephyr release to set the timeline. Extensions to
47  this timeline requires TSC approval.
48
49Roles and Responsibilities
50**************************
51
52Collaboration branch owners have the following responsibilities:
53
54- Use the infrastructure and tools provided by the project (GitHub, Git)
55- All changes to collaboration branches shall come in form of github pull requests.
56- Force pushing a collaboration branch is only allowed when rebasing against the main branch.
57- Review changes coming from team members and request review from branch owners
58  when submitting changes.
59- Keep the branch in sync with upstream and update on a regular basis.
60- Push changes frequently to upstream using the following methods:
61
62  - GitHub pull requests: for example, when reviews have not been done in the local
63    branch (one-man branch).
64  - Merge requests: When a set of changes has been done in a local branch and
65    has been reviewed and tested in a collaboration branch.
66