1# Choosing an ANGLE branch for your project 2 3ANGLE is under continuous development, and does not create release tarballs or 4tag specific revisions as releases, which may make the process of choosing a 5point in ANGLE's history as the dependency for your project less than obvious. 6This document illustrates how to choose a branch of ANGLE which can be expected 7to be updated with critical fixes, should they be needed. 8 9## ANGLE automatic branching 10 11Branches are created automatically in ANGLE to correspond to branches created in 12Chromium. These branches are named `chromium/####`, where the number is the 13matching Chromium branch. These branches will be created from the revision which 14that Chromium branch points to as its dependency. So, for example, the 15`chromium/2013` branch point is at r28bcf4ff, because [Chromium's dependency 16file for the 2013 branch] 17(http://src.chromium.org/viewvc/chrome/branches/2013/src/DEPS?revision=272741) 18uses this ANGLE revision. 19 20It isn't necessary to be familiar with how Chromium's dependency management 21works to choose an appropriate ANGLE branch for your project. You will, however, 22likely want to make sure that you choose a branch that is used for a relatively 23stable Chromium release channel build, as those branches will be deployed with 24Chromium, and receive updates if bugs are found and fixed during release 25lifetime, while the more volatile channels will turn over quickly, and their 26branches will be short-lived. 27 28**We recommend choosing a branch corresponding to a Beta or Stable Chromium 29release** if you are pursuing periodic, not continuous, integration of ANGLE. 30 31## Matching a Chromium release to an ANGLE branch 32 33In order to determine which branches are used by Chromium releases, please use 34[the OmahaProxy tool](http://omahaproxy.appspot.com/), which lists build 35information about current Chromium releases. Find the entry for a suitable 36release channel (for now, we recommend one of the Windows desktop releases), and 37note the branch listed in the `true_branch` column. This identifies the ANGLE 38branch used by that Chromium release. 39 40## Updates to release branches 41 42If bugs (stability, security, performance, or otherwise) are discovered after a 43branch has been created, and that branch is used by a Chromium release, the 44fixes for those bugs will be applied to the ANGLE branches for uptake by 45Chromium and any other projects using that branch. You should need only to 46perform a `git pull` to check for and apply any such changes. 47 48## Cherry-picking a change to a release branch 49 50Occasionally a bug fix must be merged back to an earlier Chromium 51release branch. To do this, first look up the branch number in 52[OmahaProxy](https://omahaproxy.appspot.com/). For example, M55 53corresponds to branch number 2883. 54 55In the simple case where there are no conflicts, the merge can be done 56entirely in the Gerrit UI. Click the "Cherry pick" button and enter 57`chromium/[branch_number]` as the branch to merge to. 58 59If there are conflicts, however, follow these steps: 60 611. `git checkout chromium/[branch_number]` 622. `git cherry-pick [commit_hash]` 633. Fix any merge conflicts. 644. `git cl upload` 65 66Have the cherry-pick reviewed, and then land it. It's also OK to skip 67the review and land it yourself with TBR= in the issue description, if 68you have that ability. 69 70There is one final step to pick up the ANGLE change into a Chromium Beta or 71Stable branch. A Skia auto-roller updates the DEPS file in the corresponding 72Chromium branch automatically once the ANGLE change is merged into an ANGLE 73branch. To make sure that your change has made it into Chromium you can check 74these auto-rollers: 75 761. https://autoroll.skia.org/r/angle-chromium-beta-autoroll 771. https://autoroll.skia.org/r/angle-chromium-stable-autoroll 78