Skip to content

Chromium rebases

Jump to bottom
Emerick Rogul edited this page Oct 30, 2024 · 94 revisions

Configure and init the new Chromium version

  1. Create a new cloned directory and install the necessary node modules.

 npm install

  1. Since this is a new clone, you won't have a src directory so run init to create that.

 npm run init

  1. Branch off the latest Chromium rebase branch or master, whichever is applicable.

  2. Open package.json in src/brave/ and change the string at the path config.projects.chrome.tag to the new Chromium version, then commit the changes to that file with the comment Update from Chromium XXX to Chromium YYY.

  3. Run npm run sync to make sure that the Chromium repository at src/ is at the right version, the right internal dependencies are set to the expected versions, and the patches from Brave applied as expected.

  4. If all patches apply correctly, simply run

 npm run update_patches

 then, commit the changes with the comment Updated patches from Chromium XXX to Chromium YYY.

 Typically, however, some patches will fail to apply.

Fix patches

  1. Resolve errors for each patch that didn't apply.

 The most common situations are:

  • The file being patched got moved/renamed -> rename the patch accordingly.
  • The content of the file changed so that the lines surrounding the patched in lines don't match -> adjust the patch to fit the new content. Once the patch is fixed, apply it, then, update:
 cd src
 git apply -3 brave/patches/patch_name.patch
 git diff <CHROMIUM_VERSION> --src-prefix=a/ --dst-prefix=b/ --full-index path/to/file/being/patched > brave/patches/patch_name.patch

 When all such failing patches have been fixed, commit the changed patches with the comment Conflict-resolved patches from Chromium XXX to Chromium YYY.

  • The content that was being patched or the entire file was removed -> determine if the patch can just be removed or other changes need to made to compensate for the removed code. Remove the patch and commit. The commit message should include the links to the relevant upstream changes on https://chromium.googlesource.com/ or https://source.chromium.org/, as well as the upstream commit messages for those changes.
  1. Once all patching errors have been resolved, run update:

 npm run update_patches

 This will update patches that applied correctly in the first place. Commit the changes with the comment Updated patches from Chromium XXX to Chromium YYY.

  1. Since the init was interrupted by patching errors run sync:

 npm run sync

Note: Be careful when applying tools/gritsettings/resource_ids, sometimes the IDs can change and you should update the Brave one to be the same as the Chromium one.

Update strings

Update grd and grdp files from the Chromium ones:

cd ..
npm run chromium_rebase_l10n

Note: Filled some custom strings to brave_strings.grd by https://github.com/brave/brave-core/pull/214/commits/256f5aa8e781d266ad23f863ac7b613615ad2a5a

Inspect changed strings visually to catch overly aggressive replacements (e.g. Google Lens -> Brave Lens). If overly aggressive replacements are found, add them to script/lib/l10n/grd_string_replacements.py and script/lib/l10n/transifex/push.py and rerun the chromium_rebase_l10n script.

Do a commit for the updated source strings, grd files with the comment Updated strings for Chromium XXX.

Check for changes in the build tool chain

  • For Mac, check mac_sdk_min in src/build/config/mac/mac_sdk_overrides.gni for the SDK version, the comment above MAC_BINARIES_TAG and MAC_MINIMUM_OS_VERSION in src/build/mac_toolchain.py for the XCode version and the OS version.
  • For Windows check MSVS_VERSIONS in src/build/vs_toolchain.py (CURRENT_DEFAULT_TOOLCHAIN_VERSION in src/build/win_toolchain.py prior to C75) for Visual Studio versions.

Update your toolchain (this is only needed if not using the hermetic toolchain, which should be rare). Alert dev-ops and CI teams on toolchain changes, so they can update and deploy the new hermetic toolchains. Note that we automated the process for updating the Mac hermetic toolchain, which can be run here: https://ci.brave.com/job/xcode-hermetic-toolchain-build/.

After they do, you will need to update brave-core to use the new toolchain:

  • For updates to the Mac hermetic toolchain, update //brave/build/mac/download_hermetic_xcode.py.
  • For updates to the Windows hermetic toolchain, update //brave/build/commands/lib/config.js with the new toolchain hash as found in the relevant https://ci.brave.com/job/windows-hermetic-toolchain-build log file.

Fix the build

Do a build like normal, fix errors as they come up.

npm run build

If there's anything that should be called out as a non-trivial change, you should do it as a separate commit.

For each error fixed, the commit message should include the links to the relevant upstream changes on https://chromium.googlesource.com/ or https://source.chromium.org/, as well as the upstream commit messages for those changes.

If you have more fixes caused by the same upstream change, use git commit --fixup and rebase -i to squash them.

git log
1234567 Fix for upstream change A.
8910112 Fix for upstream change B.

git commit -a --fixup 1234567 
git rebase -i --autosquash @~3

Fix chromium_src overrides

Run brave/tools/chromium_src/check_chromium_src.py to find faulty overrides in the chromium_src directory, including:

  • targets under src that no longer exist
  • definitions for symbols that are no longer present in the target file

Make an appropriate fix for each situation.

Fix unit and browser tests build

Build unit and browser tests as usual:

npm run test -- brave_unit_tests

npm run test -- brave_browser_tests

Use the same commit practices as for fixing the main build.

MIDL issue on Windows

When this message is visible during the build, check src/third_party/win_build_output/ is changed. If not, it means our pre-generated files in ./src/brave/win_build_output/midl/google_update/ are not copied there. In this case, check updateOmahaMidlFiles() in lib/util.js. Make sure that google_update directory has two directory(x64, x86).

To rebaseline:
  copy /y c:\users\XXX\appdata\local\temp\tmpdjhho_\* C:\Projects\brave\brave-browser\src\third_party\win_build_output\midl\google_update\x64

Audit for new network services

When submitting your PR add the CI/run-network-audit label to ensure that CI runs the audit-network pipeline.

For now just follow the instructions in https://github.com/brave/brave-browser/wiki/Tests#privacy-network-audit.

We should build some automation to find new things added here:

https://cs.chromium.org/search/?q=%22destination:+GOOGLE_OWNED_SERVICE%22&sq=package:chromium&type=cs

Check for changes in supported OS versions

  • For MacOS check mac_deployment_target and mac_min_system_version in build/config/mac/mac_sdk.gni
  • For iOS check ios_deployment_target in build/config/ios/ios_sdk_overrides.gni

Notify Security team of feature changes

  • Check with the Security team regarding any potentially relevant changes in feature behaviors or defaults. Specifically, post a link to changes in https://chromium.googlesource.com/chromium/src/+diff/[PreviousVersion]..[NewVersion]/content/public/common/content_features.cc in #security-discussion Slack channel.

  • In addition to new/changed features, check brave://components to see if there are any new components. For example, this GitHub issue lists components that slipped in during the rebasing process or that we failed to triage in the past. There's an issue created to automate this process which you can find here.

  • Entitlements to enable new features specific to Chromium are added to https://source.chromium.org/chromium/chromium/src/+/master:chrome/app/app-entitlements-chrome.plist. Review the new entitlements for each CR bump when new features are added to Chromium. If a new entitlement is added, it most likely will result in the MacOS application failing to launch due to a signature error.

  • On Android, new permissions can be added in */AndroidManifest.xml or */AndroidManifest.xml.expected. Users often ask questions about new permissions on update. Any new permissions should be reviewed by the @android-team or @security-team before merge.

Check for dependency changes in upstream Rust crates

If there are dependency changes in upstream Rust crates (see third_party/rust/chromium_crates_io/Cargo.lock) that we also use in Brave code, then we must update our dependencies to reflect the new versions. This process currently involves copying all of Brave's Rust dependencies and associated third_party/cargo configuration changes to src and running gnrt from src to update everything.

This process is explained here, but it's best to have someone from the Rust team and/or @rust-deps perform this step for now.

Creating the PR

When creating the PR, mark it as WIP and put it into draft mode. The title should be Upgrade from Chromium {n} to Chromium {n+1} where n is the current version number.

The PR must contain all of the following labels:

  • CI/run-audit-deps
  • CI/run-draft
  • CI/run-network-audit
  • CI/run-upstream-tests

Smoke test

Before handing off a build to QA, please test the following functionality:

  • Ensure that About page shows the expected version number
  • Ensure that brave://settings is functional and not throwing any console errors (check each section)
  • Ensure that clearing browser data on exit works as expected
  • Ensure that tabs have the expected shape (it's slightly different from Chrome)
  • Ensure that videos play properly on YouTube and that the media device toolbar button works correctly
  • Ensure that tab-muting works properly
  • Ensure that vertical tabs work as expected (enable by right-clicking any tab and selecting "Use vertical tabs")
  • Ensure that enabling Rewards works properly and verify that the NTP Rewards widget shows as connected
  • Ensure that all elements of the sidebar panel work as expected
  • Ensure that creating and using multiple profiles works as expected
  • Ensure that creating and using a Guest profile works as expected (reached via Hamburger -> More tools -> Open Guest profile)
  • Ensure that private and Tor windows work as expected
  • Ensure that a few different web sites load as expected
  • Ensure that DevTools loads correctly and works as expected

QA Builds

Before merging, we must produce standard (non-delta) and delta builds for QA to test.

Standard (non-delta) builds

Creation

Make non-delta builds for QA smoke tests using the following links:

Settings:

  • CHANNEL - Set to nightly (this is the default)
  • BRANCH - Set to the appropriate branch name, e.g., cr100
  • PREVIOUS_BUILD_NUMBER_DELTA - Leave blank
  • KEYCHAIN_NAME (Mac only) - Must be set to release (this is now the default, but always double-check it as using the wrong setting will result in an app that crashes on startup)

Download

The build jobs produce installers that you can retrieve from the following places (you'll need to modify these links slightly, as they include build and version number information; they're provided here only as an example):

MacOS installers
Linux installers
Windows (x64) installers
Windows (x86) installers
Android installers
iOS installers

Delta builds

Creation

After creating the standard builds, next create the delta builds for Windows and Mac.

Note: You MUST first wait for the version number to increment on master and then rebase your branch against master to get that new version, as the delta updater must update to a new version number.

Make delta builds for QA smoke tests using the following links:

Settings (all settings are the same as used above for the non-delta QA builds, except):

  • PREVIOUS_BUILD_NUMBER_DELTA - Specify the build number from the previous non-delta build that you created above

Download

The build jobs produce installers that you can retrieve from the following places (you'll need to modify these links slightly, as they include build and version number information; they're provided here only as an example):

MacOS deltas
Windows deltas

Uploading

After producing the delta builds, you can upload them to the update server here: https://ci.brave.com/job/test-brave-browser-updates-upload

Settings:

  • JOB - A job ending with -windows-[arch] or -macos-[arch], eg. test-brave-browser-build-windows-x64
  • BUILD_NUMBER - The build number of the delta build
  • OMAHA_CHANNEL - The channel on the update server to upload the version to

For Windows x86 and x64, set OMAHA_CHANNEL to nightly (this is the default).

For MacOS x64, set OMAHA_CHANNEL to nightly (this is the default). For MacOS arm64, set OMAHA_CHANNEL to nightly-arm64.

Testing

Windows

In order to test a delta update on Windows, do the following:

  1. Connect to the Brave VPN
  2. Download and install the appropriate standalone installer (e.g., BraveBrowserStandaloneNightlySetup_119_1_61_36.exe)
  3. Once the browser launches:
    • Open brave://version
    • Verify that correct version is installed
    • Close the browser
  4. In the Windows registry, set HKEY_LOCAL_MACHINE\SOFTWARE\WOW6432Node\BraveSoftware\UpdateDev\url to https://updates-panel.brave.com/service/update2
  5. In the Windows registry, set Computer\HKEY_LOCAL_MACHINE\SOFTWARE\WOW6432Node\BraveSoftware\Update\ClientState\{C6CB981E-DB30-4876-8639-109F8933582C}\ap to the appropriate channel name (e.g., nightly)
  6. Launch the browser and visit brave://settings/help
  7. Verify that the browser downloads and installs the delta update

Merge

After code review and QA signoff on the test builds, merge to master (do not use a squash merge) and announce it on the appropriate Slack channels. At this time, you can also note for developers any process/style/toolkit/etc. changes required by the new Chromium version.

After merging to master create uplift PRs as appropriate.

Follow-up work

Sometimes during the review process, reviewers will request follow-up issues to resolve problems that are important but shouldn't block review. We track those issues here, using the GitHub tag Chromium/Followup. When entering a new follow-up issue, please use that tag and prefix the issue title with the major Chromium version where the follow-up work was requested.

Minor bumps

For post-merge minor Chromium bumps, follow the instructions here.

Clone this wiki locally