xref: /aosp_15_r20/external/angle/doc/ChoosingANGLEBranch.md (revision 8975f5c5ed3d1c378011245431ada316dfb6f244)

# Choosing an ANGLE branch for your project

ANGLE is under continuous development, and does not create release tarballs or
tag specific revisions as releases, which may make the process of choosing a
point in ANGLE's history as the dependency for your project less than obvious.
This document illustrates how to choose a branch of ANGLE which can be expected
to be updated with critical fixes, should they be needed.

## ANGLE automatic branching

Branches are created automatically in ANGLE to correspond to branches created in
Chromium. These branches are named `chromium/####`, where the number is the
matching Chromium branch. These branches will be created from the revision which
that Chromium branch points to as its dependency. So, for example, the
`chromium/2013` branch point is at r28bcf4ff, because [Chromium's dependency
file for the 2013 branch]
(http://src.chromium.org/viewvc/chrome/branches/2013/src/DEPS?revision=272741)
uses this ANGLE revision.

It isn't necessary to be familiar with how Chromium's dependency management
works to choose an appropriate ANGLE branch for your project. You will, however,
likely want to make sure that you choose a branch that is used for a relatively
stable Chromium release channel build, as those branches will be deployed with
Chromium, and receive updates if bugs are found and fixed during release
lifetime, while the more volatile channels will turn over quickly, and their
branches will be short-lived.

**We recommend choosing a branch corresponding to a Beta or Stable Chromium
release** if you are pursuing periodic, not continuous, integration of ANGLE.

## Matching a Chromium release to an ANGLE branch

In order to determine which branches are used by Chromium releases, please use
[the OmahaProxy tool](http://omahaproxy.appspot.com/), which lists build
information about current Chromium releases. Find the entry for a suitable
release channel (for now, we recommend one of the Windows desktop releases), and
note the branch listed in the `true_branch` column. This identifies the ANGLE
branch used by that Chromium release.

## Updates to release branches

If bugs (stability, security, performance, or otherwise) are discovered after a
branch has been created, and that branch is used by a Chromium release, the
fixes for those bugs will be applied to the ANGLE branches for uptake by
Chromium and any other projects using that branch. You should need only to
perform a `git pull` to check for and apply any such changes.

## Cherry-picking a change to a release branch

Occasionally a bug fix must be merged back to an earlier Chromium
release branch. To do this, first look up the branch number in
[OmahaProxy](https://omahaproxy.appspot.com/). For example, M55
corresponds to branch number 2883.

In the simple case where there are no conflicts, the merge can be done
entirely in the Gerrit UI. Click the "Cherry pick" button and enter
`chromium/[branch_number]` as the branch to merge to.

If there are conflicts, however, follow these steps:

1. `git checkout chromium/[branch_number]`
2. `git cherry-pick [commit_hash]`
3. Fix any merge conflicts.
4. `git cl upload`

Have the cherry-pick reviewed, and then land it. It's also OK to skip
the review and land it yourself with TBR= in the issue description, if
you have that ability.

There is one final step to pick up the ANGLE change into a Chromium Beta or
Stable branch. A Skia auto-roller updates the DEPS file in the corresponding
Chromium branch automatically once the ANGLE change is merged into an ANGLE
branch. To make sure that your change has made it into Chromium you can check
these auto-rollers:

1. https://autoroll.skia.org/r/angle-chromium-beta-autoroll
1. https://autoroll.skia.org/r/angle-chromium-stable-autoroll