Zephyr microPlatform Branches¶
This document describes the rules governing the branches in the Zephyr microPlatform Git repositories, and what you can expect from them.
The important things to know are:
masterbranch in the ZmP west manifest repository always tracks the latest development.
- Commits in the Foundries.io Zephyr and mcuboot trees which aren’t present upstream have special tags, called sauce tags, in their Git shortlogs, so they can be easily identified and their purpose made clear.
- When upstream projects release new versions, the Zephyr microPlatform branches receive non-fast-forward updates onto the new upstream development versions.
- Currently, Zephyr microPlatform repositories provided by Foundries.io (i.e., projects without external upstreams) always get fast-forward updates.
Why Have Branching Rules?¶
The short answer is that it keeps things working while patches flow up- and downstream, and as we periodically rebase microPlatform patches on our upstream projects’ latest versions.
The details are given below in Appendix: Branch Management Rationale.
For repositories with upstreams, like Zephyr and MCUBoot, Foundries.io maintains some out of tree patches. To make this work smoothly, we typically bring in upstream changes by merging into our tree. You’ll see merge commits with
[FIO mergeup] in the shortlog when this happens. See below for a complete list of sauce tags.
However, whenever the upstream releases a new version, the Foundries.io branch history is cleaned up and re-written onto the new development tree for the next version. This is a destructive change, but you can always get the old version using the manifests from previous updates.
The notes in the microPlatform update will always make it clear when history rewrites have happened. They will also provide pointers to commits in the new update which match the last update exactly (even though history is different, the code will be the same). You can use these commits as a starting point when merging the new history into your own tree if you are also managing changes to these repositories – since the code is the same, the merge will succeed.
For source code repositories without upstreams, where Foundries.io is maintaining the code, Zephyr microPlatform updates will always contain fast-forward changes from the previous update.
Appendix: Branch Management Rationale¶
This is a detailed rationale for why these rules exist.
There are two “types” of repository in a Zephyr microPlatform installation:
- Projects which have an external upstream, like Zephyr and mcuboot.
- Projects which are developed for the Zephyr microPlatform, and which have no external upstream, like
Rather than cloning the upstream versions of the Zephyr and mcuboot repositories in a Zephyr microPlatform installation, Foundries.io maintains its own trees. This is for two reasons.
- It lets us track known-good revisions, especially when they include Foundries.io patches.
- As active contributors to these projects, it gives us a place to carry out our own development.
We’re constantly upstreaming features, bug fixes, etc. We’re also constantly tracking upstream and merging updates after they pass continuous testing. We also sometimes need to keep some temporary solutions or patches in our trees which aren’t useful for upstream, but are important to our users (i.e. you!).
While this happens, Zephyr microPlatform-only repositories are also changing, both to track changes from upstream, and in their own right.
This all gets complicated, and the branching rules help keep things working smoothly:
- Users can see differences between upstream and Zephyr microPlatform repositories clearly.
- Developers can stage local and integrate upstream changes into Zephyr microPlatform branches.
- Continuous Integration can track and test incoming changes.
- The west manifest file in each microPlatform update serves as a permanent record despite histories which rebase.