Bridle code base

The source code, libraries, and tools that compose Bridle are entirely hosted in a set of Git repositories. Basic familiarity with Git is required to understand the architecture of the repository set and to work with Bridle.

All Bridle repositories are publicly hosted on GitHub, and accessible to both individual users and companies.

Git basics

Git is a distributed version control system that allows repositories to be easily duplicated. Every time you take an existing Git repository and create a copy of it, you are creating a fork of that repository. This means that you create an identical copy that might diverge from the original over time, since commits to the original will not be automatically reflected in the copy, and commits to your copy will not be automatically reflected in the original.

Note

When we talk about forks or copying Git repositories, we refer to the creation of a new repository hosted on a server and accessible to other users. If you clone a repository to your local machine using git clone, that is referred to as a clone and not a fork.

When you create a fork by copying an existing repository, the original repository is called the upstream repository and the newly created copy the downstream repository.

A fork can be hosted on any server, including a public Git hosting site like GitHub. It is, however, important to differentiate between the generic concept of a fork and GitHub’s concept of a GitHub fork. When you create a GitHub fork, GitHub copies the original repository and tags the downstream repository (the fork) with a flag that allows users to send pull requests from the fork to its upstream repository. GitHub also supports creating forks without linking them to the upstream respository. See the GitHub documentation for information about how to do this.

Fork and branch strategy

A graphical depiction of the |BRIDLE| branch strategy

The Bridle branch strategy.

Repository types

There are two main type of Git repositories in the Bridle repository set:

TIAC repositories:

  • Created, developed, and maintained by TiaC Systems.

  • Usually permissively licensed for use by anyone interested, in both public or proprietary products.

OSS repositories:

  • Created and maintained by TiaC Systems.

  • Soft forks of open-source projects.

  • Typically contain a small set of changes that are specific to Bridle.

  • Updated (“upmerged”) regularly with the latest changes from the open source project.

TIAC repositories are stand-alone and have no upstreams, since they are unique to the Bridle. Some examples of repositories of this type are:

  • tiac-bridle: The Bridle main repository for TiaC Systems developed software.

OSS repositories are typically soft forks of an upstream open source project, which TiaC Systems maintains in order to keep a small set of changes that do not belong, or have not been merged, to the upstream official open source software repository. For example:

Repository structure

In order to manage the combination of repositories and versions, Bridle uses west, the same tool that Zephyr uses to manage its repository set. You can learn more about the reasons behind the introduction of west in this section of the Zephyr documentation.

A manifest repository, tiac-bridle, contains a file in its root folder, west.yml, which lists all other repositories (west projects) included in Bridle. The Bridle repository structure has a star topology, with the tiac-bridle repository being the center of the star and all other repositories being west projects that are managed by west.yml. This is equivalent to topology T2 in the west documentation and more detailed describe in Multiple Repository Model.

A graphical depiction of the |BRIDLE| repository structure

The Bridle repository structure.

The figure above depicts the Bridle repository structure. A central concept with this repository structure is that each revision (in Git terms) of the tiac-bridle repository completely determines the revisions of all other repositories (i.e. the west projects). This means that the linear Git history of this manifest repository also determines the history of the repository set in its entirety, thanks to the west.yml west manifest file being part of the manifest repository. West reads the contents of the manifest file to find out which revisions of the project repositories are to be checked out every time west update is run. In this way, you can decide to work with a specific Bridle release either by initializing a new west installation at a particular tag or by checking out the corresponding tag for a release in an existing installation and then updating your project repositories to the corresponding state with west update. Alternatively, you can work with the latest state of development by using the main branch of the tiac-bridle repository, updating it with Git regularly and using west update to update the project repositories every time the manifest repository changes. More information about manifests can be found in the west manifest section of the Zephyr documentation.

Revisions

Attention

A proper release planning has not been established so far. The information given here is in planning and not yet implemented!

There are two fundamental revisions that are relevant to most Bridle users:

As discussed above, the revision of the manifest repository, tiac-bridle, uniquely determines the revisions of all other repositories, so a discussion about Bridle revisions can be essentially limited to the manifest repository revision.

The main branch of the tiac-bridle repository always contains the latest development state of the Bridle. Since all development is done openly, you can use it if you are not particularly concerned about stability and want to track the latest changes that are being merged continuously into the different repositories.

The Git tags correspond to official releases tested and signed by the TiaC Systems engineers. The format is as follows:

vX.Y.Z(-rcN)

Where X, Y, and Z are the major, minor, and patch version respectively and, optionally, a release candidate postfix -rcN is attached if the tag identifies a candidate instead of the actual release.

The Git tags are composed as follows:

vX.Y.Z(-rcN|-devN)

X, Y, and Z are the major, minor, and patch version, respectively. Tags without a suffix correspond to official releases tested and signed by TiaC Systems engineers. A release candidate suffix -rcN is attached if the tag identifies a candidate instead of the actual release. In between releases, there might be development tags. These are identified by a -devN suffix.

OSS repositories downstream project history

As described in Repository types, Bridle contains OSS repositories, which are based on third-party, open-source Git repositories and may contain additional patches not present upstream. Examples include tiac-zephyr, which have upstream open-source projects used as a basis for downstream repositories distributed with Bridle. This section describes how the history of these OSS repositories is maintained, and how they are synchronized with their upstreams.

The short logs for these downstream patches contain [bridle xyz] at the beginning, for different xyz strings. This makes their different purposes downstream clearer, and makes them easier to search for and see in git log. The current values of [bridle xyz] are:

  • [bridle mergeup]: periodic merges of the upstream tree (if really needed)

  • [bridle fromlist]: patches which have upstream pull requests, including any later revisions

  • [bridle toup]: patches which TiaC Systems developers intend to submit upstream later

  • [bridle noup]: patches which are specific to Bridle

  • [bridle temphack]: temporary patches with some known issues

  • [bridle fromtree]: patches which have been cherry-picked from an upstream tree

Note

The downstream project history is periodically rewritten. This is important to prevent the number of downstream patches included in a specific Bridle release from increasing forever. A repository’s history is typically only rewritten once for every Bridle release.

To make incorporating new history into your own forks easier, a new point in the downstream Bridle history is always created which has an empty git diff with the previous version. The empty diff means you can always use:

  • git merge to get the rewritten history merged into your own fork without errors

  • git rebase --onto or git cherry-pick to reapply any of your own patches cleanly before and after the history rewrite

  • git cherry to list any additional patches you may have applied to these projects to rewrite history as needed

Additionally, both the old and new histories are committed sequentially into the revision fields for these projects in the bridle/west.yml west manifest file. This means you can always combine git bisect in the bridle repository with west update at each bisection point to diagnose regressions, etc.