1# How to Branch and Roll Chromium's ANGLE Dependency 2 3ANGLE provides an implementation of OpenGL ES on top of other APIs (e.g. DirectX11, Vulkan). ANGLE 4uses (i.e. depends upon) other third-party software that comes from different repositories. ANGLE specifies 5its dependencies on a specific version of each of these other repositories in the [ANGLE DEPS file](https://chromium.googlesource.com/angle/angle/+/main/DEPS). 6 7Chromium relies upon ANGLE for hardware accelerated rendering and WebGL support. Chromium similarly 8specifies its dependency on a specific version of ANGLE in the [Chromium repository's src/DEPS file](http://src.chromium.org/viewvc/chrome/trunk/src/DEPS). 9 10This document describes how to update those dependencies, and, if necessary, create an ANGLE branch 11to correspond to a branched release of Chrome. 12 13ANGLE's commit queue also runs browser-level tests which are hosted in 14the Chromium repository. To reduce the chance of a Chromium-side 15change breaking ANGLE's CQ, the version of Chromium against which 16ANGLE changes is also snapshotted, and rolled forward into ANGLE with 17appropriate testing. 18 19## Autorollers 20 21At present, autorollers manage both the ANGLE roll into Chromium, and 22the Chromium roll into ANGLE. There is also an autoroller for ANGLE into [Android AOSP](https://android.googlesource.com/platform/external/angle/). 23All of the ANGLE-related autorollers are documented in the [ANGLE Wrangling documentation](../infra/ANGLEWrangling.md#the-auto-rollers). 24 25## Manually rolling DEPS 26 27As mentioned above, dependencies are encoded in `DEPS` files. The process to update a given 28dependency is as follows: 29 30 * Find the appropriate line in the relevant `DEPS` file that defines the dependency 31 * Change the [git SHA-1 revision number](http://git-scm.com/book/ch6-1.html) to be that of the commit 32on which to depend upon (Note: use the full SHA-1, not a 33shortened version) 34 * You can find the SHA-1 for a particular commit with `git log` on the appropriate branch of the 35repository, or via a public repository viewer 36 * If using the [ANGLE public repository viewer](https://chromium.googlesource.com/angle/angle), you will need to select the branch whose log you 37wish to view from the list on the left-hand side, and then click on the "tree" link at the top of 38the resulting page. Alternatively, you can navigate to 39`https://chromium.googlesource.com/angle/angle/+/<branch name>/` -- 40including the terminating forward slash. (e.g. 41`https://chromium.googlesource.com/angle/angle/+/main/`) 42 43### Rolling Vulkan Memory Allocator (VMA) 44 45ANGLE and other Google projects (e.g. Skia, Chrome) use the open-source [Vulkan Memory Allocator][vma-upstream] (VMA) 46library. As with with other external repositories, these projects do not directly use the [upstream Vulkan Memory Allocator][vma-upstream] repository. 47Instead, a [Google-local repository][vma-chrome] is used, which contains Google-local changes and fixes (e.g. changes 48to `BUILD.gn`). This Google-local repository repository contains the following key branches: 49 50- `upstream/master` is automatically mirrored with the contents of the [upstream VMA][vma-upstream] repository 51- `main` is manually curated by Google, with a combination of upstream and Google-local changes 52 53ANGLE's `DEPS` file points to a git SHA-1 revision of the `main` branch. 54 55Manual rolls of the `main` branch currently involve rebasing all of the Google-local changes on top of newer upstream changes. The current process (done in 2022) is to: 56 57 * Revert all of the Google-local changes (i.e. with a single commit) 58 * Merge or cherry-pick all of the upstream changes 59 * Cherry-pick the Google-local changes on top 60 * Note: it may be possible to simply merge future upstream changes directly, without reverting the Google-local changes 61 62Manual rolls of which SHA-1 revision the ANGLE's `DEPS` file points to is done via the process 63outlined above. Within an ANGLE build, you can navigate to the `third_party/vulkan_memory_allocator` 64directory, check out the `main` branch, and use `git log` to select the desired Git revision. 65**Please note** that cross-project coordination may be required when rolling VMA, as some projects (e.g. Chrome) builds itself with a single VMA version across Chrome, ANGLE, and Skia. 66 67[vma-upstream]: https://github.com/GPUOpen-LibrariesAndSDKs/VulkanMemoryAllocator 68[vma-chrome]: https://chromium.googlesource.com/external/github.com/GPUOpen-LibrariesAndSDKs/VulkanMemoryAllocator 69 70Note: When ANGLE is AutoRolled to the Android AOSP source tree, Google-local 71changes to the VMA `BUILD.gn` file will be converted to the ANGLE `Android.bp` file. 72 73## Branching ANGLE 74 75Sometimes, individual changes to ANGLE are needed for a release of Chrome which 76has already been branched. If this is the case, a branch of ANGLE should be 77created to correspond to the Chrome release version, so that Chrome may 78incorporate only these changes, and not everything that has been committed since 79the version on which Chrome depended at branch time. **Please note: Only ANGLE 80admins can create a new branch.** To create a branch of ANGLE for a branched 81Chrome release: 82 83 * Determine what the ANGLE dependency is for the Chrome release 84by checking the DEPS file for that branch. 85 * Check out this commit as a new branch in your local repository. 86 * e.g., for [the Chrome 34 release at 87chrome/branches/1847](http://src.chromium.org/viewvc/chrome/branches/1847/src/DEPS), 88the ANGLE version is 4df02c1ed5e97dd54576b06964b1da67ea30238e. To 89check this commit out locally and create a new branch named 'mybranch' 90from this commit, use: ```git checkout -b mybranch 914df02c1ed5e97dd54576b06964b1da67ea30238e``` 92 * To create this new branch in the public repository, you'll need to push the 93branch to the special Gerrit reference location, 'refs/heads/<branch name>'. You 94must be an ANGLE administrator to be able to push this new branch. 95 * e.g., to use your local 'mybranch' to create a branch in the public repository called 96'chrome\_m34', use: ```git push origin mybranch:refs/heads/chrome_m34``` 97 * The naming convention that ANGLE uses for its release-dedicated branches is 'chrome\_m##'. 98