Rebasing our forks - PeterWangIntel/crosswalk-website GitHub Wiki

As described in our Release Methodology page, Crosswalk follows a release process similar to Chromium's. Part of the release of Crosswalk it involves rebasing our forks of our Blink, Chromium and V8 on top of a certain upstream release.

This article shows how perform these rebases and what pitfalls to look out for, as well as how to update Crosswalk itself once the forks have been rebased.

Before you begin

Some skills are essential in order to rebase the code without losing half of your hair or running away in despair.

First of all, you must be familiar with Chromium's release process (which is what we have based our own relase methodology on). Particularly important things to know include:

Chromium's git repository organization:
- The master branch is where all development happens.
- Development is stabilized in branches: no new features are introduced, and this is where final releases are created from. In git, the branches are in refs/branch-heads/<NUMBER>.
- Releases (canaries, betas, stables etc) are tags in refs/tags/<RELEASE NUMBER>.
- Branches and tags are not fetched by default, contrary to the defaults used by most git projects in the world.
- DEPS and .DEPS.git are not updated in a branch after it is created from master. They are updated for releases, though (a tagged release simply points to a commit on top of a branch that updates those two files).
Blink's development still happens in SVN. trunk (/trunk) corresponds to git's master, and a branch is created with the same number as the Chromium one when the latter is branched (/branches/chromium/<NUMBER>), except that Chromium branches such as 1234_55 do not have a corresponding branch in Blink; all commits to 1234, 1234_56, 1234_678 etc in Chromium go to the same branch 1234 in Blink.
- Blink is also mirrored in git. git's master branch corresponds to trunk, branches are in refs/branch-heads/chromium/<NUMBER>.
Finally, V8's development happens in git, with release branches accompanying each Chromium release. For example, Chromium 34 uses V8 from the 3.24 branch. In git, these branches are stored in refs/branch-heads/<NUMBER>.

You also need to be familiar with OmahaProxy. Understand which row you are supposed to choose and what the columns mean. If you are rebasing Crosswalk's dependencies for a new cycle (ie. you are working on what Crosswalk's master branch is going to be based on), you should check the linux-beta row in OmahaProxy. Likewise, if you are simply maintaining Crosswalk's stable branch and are thus updating from one Chromium release to another in the same milestone, use the linux-stable row. From there you will see which is newest chromium version in specific type of release.

Finally, spend some time getting to know git better. Do not follow the instructions below blindly. Specifically, make sure you know how references and refspecs work.

Branch names in blink-crosswalk, chromium-crosswalk and v8-crosswalk

When creating new branches or updating existing ones, it is important to pay attention to Crosswalk's branch naming conventions for the forks. They apply to all our forks (blink-crosswalk, chromium-crosswalk and v8-crosswalk).

The most basic distinction is between the master and the crosswalk-* branches:

master, as usual in a git-based workflow, is the current development branch and the one everyone works on at the moment. It corresponds to the fork versions Crosswalk's master branch is using.
When rebasing to track a different release, the previous branch should be backed up and preserved as crosswalk-<version>/<release_number>. For example, crosswalk-1/28.0.1500.36 corresponds to all the commits we made to chromium-crosswalk (or blink-crosswalk) while we were tracking Chromium's 28.0.1500.36 release.

In other words, crosswalk-<version>/<release_number> simply contains a certain number of commits made by Crosswalk contributors on top of an upstream branch.

Rebasing blink-crosswalk

Let's start with the dependency deepest down the stack we have: Blink. Most of the time, rebasing Blink should be trivial: not only are fork-specific commits discouraged in general, but Blink normally serves Crosswalk's purposes just fine without requiring any changes from our part.

Fork blink-crosswalk.

In case this was not obvious, make sure you have your own fork of the blink-crosswalk both for experimenting and also for submitting pull requests and exercising the bots. Do NOT push your changes directly to crosswalk-project/blink-crosswalk.git directly without testing and talking to people first!

Also, do not forget to add your remote to your checkout if you have not done so yet:
```
cd third_party/WebKit
git remote add my-fork [email protected]:myusername/blink-crosswalk.git
```
Back up the existing master branch.

As mentioned above, since the master branch is going to have its history changed, it must be backed up into a history branch first. For example, if we are currently tracking Chromium release 28.0.1500.36, a branch called crosswalk-1/28.0.1500.36 must be created. You can find that in src/chrome/VERSION (in chromium-crosswalk). You can check the Crosswalk version from src/xwalk/VERSION. If you track master:
```
git fetch origin
git reset --hard origin/master # if someone is rebased after you last one.
git branch crosswalk-1/28.0.1500.36 origin/master
git push my-fork crosswalk-1/28.0.1500.36
```
If you track a beta/stable branch, backup branch is already there, but you have to create a branch for the new version:
```
git fetch origin
# Checkout newest commit
git branch crosswalk-12/41.0.2272.101 origin/crosswalk-12/41.0.2272.74
# No need to push yet, if you do so you have to force push later.
```
Fetch the new Blink branch and create a new upstream branch.

This use of git fetch is a bit unusual:
```
git fetch https://chromium.googlesource.com/chromium/blink.git +branch-heads/chromium/<BUILD_NUM:1599>:upstream-copy-mine
```
A new local branch called upstream-copy-mine should now exist and be visible if you call git branch.
Determine the new Blink branch and revision that are going to be used.

Let us assume we are working on Crosswalk's development branch (master). We look at the proper row (linux-beta) in OmahaProxy, and determine its version number is 30.0.1599.66. From this we can figure out the branch version used 1599.

You need to check out the correct revision for Blink and Chromium in the release DEPS file (ie. /releases/31.0.1650.12/DEPS). In this file, we can see the following snippet:
```
# ...
'src/third_party/WebKit':
 (Var("git.chromium.org")) + '/chromium/blink.git@59c766688e9de7eecb38047114f22801088d7d24',
# ...
```
This means Blink needs to be at revision 59c766688e9de7eecb38047114f22801088d7d24.

As the same branch can be used for more than one release, the commit at the tip of the branch might not be the one corresponding to the release we want. If it's different then reset to it:
```
git checkout upstream-copy-mine
git reset --hard <SHA1>
```
Rebase existing fork-specific changes in master on top of the new upstream branch.
1. In the trivial case, we have no fork-specific commits on top of the upstream ones (yay). This means both master (and crosswalk-1/28.0.1500.36) point to the same commit as upstream-copy-mine). Updating master should be very simple: just make it point to the same change as the new upstream branch. You can check that if there is crosswalk related commits at the top of git log. If you track master
```
git checkout master  # or your new branch
git reset --hard upstream-copy-mine
```
1. If we do have commits on top of the upstream ones, we need to check which of them are still relevant and re-apply those which are.
  
  This process involves some manual work. Use git log and any other tools at your disposal to study the Crosswalk-specific commits we have. In some cases, their commit messages say "this commit will not be needed once we rebase", or "this commit is only necessary until release XX.YY". Take note of them, because they will probably not be needed anymore. After that, use git rebase -i to rebase our commits on top of the new branch. It will try to add a lot of previous Chromium commits as well, so you need to remove a handful of lines (anything before the first Crosswalk-specific commit belongs to the previous Chromium branch and must be removed) and check which commits should actually be added.
  
  Note that there some manual effort is required here: there are likely going to be a lot of conflicts, so you need to check the commits, remove some and adjust some others. Also note that the automatic merge commits from GitHub will be lost.
```
git checkout master #or your new branch
git rebase -i upstream-copy-mine # Choose the right commits, resolve conflicts.
```
Push your new branches to your fork.

Your new commits will have to be tested with Crosswalk (and Chromium) later, so you need to push them to your fork first.
```
git push -f my-fork master
```

Rebasing v8-crosswalk

The rebasing process for v8-crosswalk is very similar to the one for blink-crosswalk. The differences are in some branch names upstream, and we always carry the SIMD.js patches on top of upstream.

The parts of the process that are similar to blink-crosswalk have shorter descriptions here. Please refer to the blink-crosswalk section for more detailed explanations of each step. It's not possible to emphasize enough how important it is not to follow the steps blindly, so read up and understand what is going on first.

Fork v8-crosswalk.

Once again, fork the repository if you haven't done it yet, and DO NOT push your changes directly to crosswalk-project/v8-crosswalk.git directly without testing and talking to people first!

And, if you haven't done so, add your remote to your checkout:
```
cd v8
git remote add my-fork [email protected]:myusername/v8-crosswalk.git
```

Back up the existing master branch.

Assuming we are currently tracking Chromium release 40.0.2214.28:

git fetch origin
git reset --hard origin/master
git branch crosswalk-11/40.0.2214.28 origin/master
git push my-fork crossalk-11/40.0.2214.28

or with stable etc:

git fetch origin
#get latest
git branch crosswalk-11/40.0.2214.28 crosswalk-11/40.0.2200.2

Determine the new Chromium branch and revision that are going to be used.

Assuming we are tracking linux-beta and it is now at release 40.0.2214.69: the v8 version column in OmahaProxy says the version number is 3.30.33.13, so the V8 tag we are interested in is called 3.30.33.13.
Fetch the new V8 branch and create a new upstream branch.
```
git fetch https://chromium.googlesource.com/v8/v8.git +refs/tags/3.30.33.13:upstream-copy-mine
```
Verify the new branch upstream-copy-mine has been created by running git branch.

You need to check the correct SHA1 hash for V8 in the release DEPS file (ie. chromium/src/+/40.0.2214.69/DEPS). In this file, we can see the following snippet:
```
# ...
'src/v8':
  (Var("git.chromium.org")) + '/v8/v8.git@aee41f5d4de09a9ffc245eaea459a75331b6f94d',
# ...
```
As the same branch can be used for more than one release, the commit at the tip of the branch might not be the one corresponding to the release we want. Use git log to determine the SHA1 hash determined above, and then reset to it:
```
git checkout upstream-copy-mine
git reset --hard <SHA1>
```
Rebase existing fork-specific changes in master on top of the new upstream branch.
1. In the trivial case (ie. we have no commits on top of upstream):
```
git checkout master #or your specifig
git reset --hard upstream-copy-mine
```
1. If we do have commits of our own, use git log to check if some of the commit messages say certain commits can be safely removed when moving to a newer V8 release, then rebase:
```
git checkout master # or your specifig
git rebase -i upstream-copy-mine # Choose the right commits, resolve conflicts.
```
Push your new branches to your fork.
```
git push -f my-fork master
```

Rebasing chromium-crosswalk

Again, the rebasing process for chromium-crosswalk is very similar to the one for blink-crosswalk. The differences are in some branch names upstream, the fact that it is much more likely that we have commits on top of the upstream ones than for blink-crosswalk and, most importantly, we rebase on top of a tag instead of a branch.

Fork chromium-crosswalk.

Once again, fork the repository if you haven't done it yet, and DO NOT push your changes directly to crosswalk-project/chromium-crosswalk.git directly without testing and talking to people first!

And, if you haven't done so, add your remote to your checkout:
```
git remote add my-fork [email protected]:myusername/chromium-crosswalk.git
```

Back up the existing master branch.

Assuming we are currently tracking Chromium release 28.0.1500.36:

git fetch origin
git reset --hard origin/master
git branch crosswalk-1/28.0.1500.36 origin/master
git push my-fork crosswalk-1/28.0.1500.36

or with stable etc:

git fetch origin
#get latest
git branch crosswalk-11/40.0.2214.28 crosswalk-11/40.0.2200.2

Determine the new Chromium release that is going to be used.

Assuming we are tracking linux-beta and it is now at release 30.0.1599.66. This is the tag/release we will rebase onto. Chromium's git repository uses tags a bit differently than most git projects: while most project use a tag to refer to a commit part of a certain branch and can be accessed by traversing this branch, Chromium's release tags point to a single commit descending from a branch but not referenced by it. The sole purpose of this commit is to update DEPS and .DEPS.git so that Chromium's dependencies are at the correct revisions.

In other words: looking at the "1599" part of 30.0.1599.66, it is possible to see that it comes from the branch 1599. In git, it means one can fetch and follow refs/branch-heads/1599 containing all commits from master that have been merged into the 1599 branch, but with outdated versions of DEPS and .DEPS.git. The tag refs/tags/30.0.1599.66, on the other hand, points to a commit fixing DEPS and .DEPS.git that is a direct child of the commit in refs/branch-heads/1599 but is not part of that branch.
Fetch the new Chromium tag and create a new upstream branch.
```
git fetch https://chromium.googlesource.com/chromium/src.git +refs/tags/30.0.1599.66:upstream-copy-mine
```
Verify the new branch upstream-copy-mine has been created by running git branch.
Rebase existing fork-specific changes in master on top of the new upstream branch.
1. In the trivial case (ie. we have no commits on top of upstream):
```
git checkout master
git reset --hard upstream-copy-mine
```
1. If we do have commits of our own, use git log to check if some of the commit messages say certain commits can be safely removed when moving to a newer Chromium release, for examble version update commits for DEPS file , then rebase:
```
git checkout master
git rebase -i upstream-copy-mine # Choose the right commits, resolve conflicts.
```
Push your new branches to your fork.
```
git push -f my-fork master
```

Updating Crosswalk itself

Now that the forks themselves have been updated, we need to work on the Crosswalk part of the rebase. It can be divided in two parts: first, smoke-test your fork changes by building content shell, then update Crosswalk's code since some of the Chromium (and maybe V8) features it uses have changed (this is very much likely if you are tracking a new milestone, whereas stable updated should be fairly painless in this regard).

Reset your copy to the upstream one

cd src/xwalk
git fetch origin
git reset --hard origin/<BRANCH>

Update version numbers in Crosswalk.

Quick recap: Crosswalk follows a MAJOR.MINOR.BUILD.PATCH versioning scheme. See our Release Methodology page for an explanation of each of those numbers.

When moving to a new Chromium milestone, we need to bump the MINOR number: this is the major number of the new Chromium release we are going to track. For example, if Crosswalk's current version is 1.28.52.3 and we are now tracking Chromium 30.0.1599.66, the new Crosswalk version number should be 1.30.52.3.

These version numbers need to be updated in the following files:
- src/xwalk/VERSION
- src/xwalk/packaging/crosswalk-bin.spec
- src/xwalk/packaging/crosswalk-libs.spec
For new releases in the stabilization branch where we are just moving to a more recent version of the same Chromium milestone, nothing needs to be done.
Update DEPS.xwalk.

This should not require many explanations: it is the file used to generate .gclient-xwalk and determines where we fetch Blink, Chromium and V8 from and at what revision.

First of all, check if there are entries there that could be removed (for example, there could be an entry saying "Delete the dependency below once we track Chromium >M30"), and remove them.

After that, chromium_crosswalk_rev, blink_crosswalk_rev and v8_crosswalk_rev need to point to the new SHA1 hashes in chromium-crosswalk, blink-crosswalk and v8-crosswalk, respectively (including the Crosswalk commits that might exist on top of the upstream ones). You can use git rev-parse HEAD or git log to determine the SHA1 hashes.

ONLY ON CROSSWALK < 16: Additionally, you have to set blink_upstream_rev, which is the SVN commit number of the latest upstream Blink commit we are pulling. It can be obtained by running git log in blink-crosswalk and checking the line that says something like git-svn-id: svn://svn.chromium.org/blink/branches/chromium/2311@191638 bbb929c8-8fbe-4397-9dbb-9b2b20218538. The 191638 part there is the SVN commit number.
Smoke-test the fork updates.

The first way to verify your rebases went well and nothing is broken is to build Chromium's content shell. You should already be familiar with content shell, so let's go directly to the commands:
```
gclient sync -v
# gclient should now checkout a new 30.0.1599.66 directory and
# then fetch new versions of a lot of third-party dependencies.

cd /path/to/chromium-crosswalk
python build/gyp_chromium
ninja -C out/Release content_shell
```
There is nothing too special above, you just need to tell gclient to fetch the new dependencies, build content shell and then run it to verify everything is working. The exact way you build the content_shell target (with ninja or with make etc) is irrelevant. Building in debug mode is recommended in order to build assertions and other parts of the code ignored in a release build.

Ozone-Wayland and Chromium

A big difference between Chromium and the other forks is that another project also needs to be taken into account when rebasing it: Ozone-Wayland, which is used to build Crosswalk for Wayland.

One must always make sure that Chromium and Crosswalk build and run correctly with Ozone-Wayland. This is normally not a problem when updating versions within the same Chromium milestone (ie. from 35.0.1916.114 to 35.0.1916.120), but it usually requires some attention otherwise. Ozone-Wayland has a public release schedule which lists the branches being worked on and which Chromium milestones they correspond to.

An important thing to mention is that Ozone-Wayland has a certain number of patches in src/ozone/patches that may need to be applied to chromium-crosswalk itself. Always make sure the patches in chromium-crosswalk match the ones in Ozone-Wayland (since they can change when Ozone-Wayland starts tracking a different Chromium version).

The first and simplest test is just verifying if any change actually needs to be done, which amounts to building Crosswalk for Wayland instead of X11:

Install Wayland and Weston on your system.
Update your GYP_DEFINES as per setup instructions on Ozone-Wayland page.

Configure and build Crosswalk:

cd src
./xwalk/gyp_xwalk
ninja -C out/Release xwalk  # Not xwalk_builder!

Check that it works:

cd src
weston &
./out/Release/xwalk http://google.com

If you are able to see Crosswalk running inside your Weston instance, everything is fine and your work is done.

If building or running Crosswalk fails, make sure there isn't another Ozone-Wayland branch tracking your milestone, or that there aren't additional commits in the branch you are using that fixes your issues. If that is the case, just adjust the commit has in Crosswalk's DEPS.xwalk and go back to the tests described above. In any of those cases, make sure the patches in src/ozone/patches that are relevant to Crosswalk are properly applied in chromium-crosswalk. Particularly, make sure the versions in chromium-crosswalk are in sync with the ones in Ozone-Wayland.

In case no existing commit fixes your issues, you will need to fix Ozone-Wayland for your branch and coordinate with the Ozone-Wayland team (Kalyan Kondapally and Joone Hur). Build problems are normally caused by changes in the Chromium code (changes in method signatures, files being moved around etc). Runtime crashes can be debugged by building Content Shell or Crosswalk in Debug mode and later calling GDB (gdb --args ./out/Debug/xwalk --single-process foo.html).

After things are working, update Crosswalk's DEPS.xwalk and go back to the tests described above.

Try building Crosswalk and its tests.

Once you are sure content shell is OK, it is time to verify Crosswalk itself. Start by trying to build xwalk and its tests, then running them.
```
cd /path/to/chromium-crosswalk
python xwalk/gyp_xwalk # Optional arguments etc etc.
ninja -C out/Release xwalk_builder
./out/Release/xwalk_unittest # and others
```
Again, the exact command line arguments are not described above, and can be found in other pages. The important part is that you must build Crosswalk and test it. Try doing that with as many platforms as you can, such as Android and Tizen as well.

If you are working on a stable branch, the whole process should not have unexpected bumps.

On the other hand, if this is a rebase on top of a new Chromium milestone for Crosswalk's development branch, it is very likely that Crosswalk will fail to build. This is the time to start adapting Crosswalk's source code to the changes in Chromium itself. You can also git commit your current changes, push them to a branch in your Crosswalk fork and ask for more people to chime in and help, as Chromium's code can change a lot between releases at times.

Rinse and repeat until everything builds, all tests pass and Crosswalk seems to be working.

Tizen and its big patch

Once upon a time, Tizen developers started complaining very loudly about the time it took for them to build Crosswalk from scratch every time gbs build was invoked (or when a change in a package that src/xwalk depended on triggered an entire rebuild in Tizen OBS). We in Crosswalk ended up devising a solution that involved splitting the Tizen RPM package into two: crosswalk-libs contains all the shared libraries produced by building Chromium, Blink and all repositories other than Crosswalk, whereas crosswalk-bin contains the xwalk binary and other files generated by Crosswalk. The former depends on the latter as well as other Tizen-specific packages, so that crosswalk-libs needs to be rebuilt very infrequently and crosswalk-bin takes only a few minutes to build from scratch. In other words, when one builds the crosswalk-bin RPM package the Chromium targets that take a lot of time to build are skipped and just result in -lfoo being passed in the command line.

This is achieved by heavily patching Chromium's build system: we change targets such as net, content and base so that:

Instead of being of type shared_library or static_library they are of type none.
They do not depend on other targets so that depending on them does not cause files to be built.
They keep exported settings, such as libraries or other targets that targets depend on them also need to depend on those.
Actions that generate files are still run.

The patch containing these changes is called crosswalk-do-not-build-several-chromium-dependencies.patch, located in src/xwalk/packaging. It is a very intrusive patch.

From a rebasing perspective, whenever we are moving to a different Chromium milestone the patch needs to be adjusted, even if only slightly.

Build the crosswalk-libs RPM package.

cd src/xwalk
gbs build --arch x86_64 --debug --skip-srcrpm \
    --define 'BUILDDIR_NAME /tmp/incremental-build/libs' \
    --spec crosswalk-libs.spec

Check if the patch currently applies.
```
cd src
patch -p1 --dry-run < xwalk/packaging/crosswalk-do-not-build-several-chromium-dependencies.patch
```
- If the output does not mention any failures, it means it will at least be applied correctly.
- Otherwise, you will need to figure out what changed in the .gyp files that failed to be patched and then adjust the patch accordingly. This is a manual process that involves comparing an existing hunk of the patch with what the target currently looks like in Chromium and then determining if it was just moved to a different location, if the contents changed or if it was just renamed or moved to a different file.
- After adjusting the patch, commit your changes locally.
Try building the crosswalk-bin RPM package.
```
cd src/xwalk
gbs build --arch x86_64 --debug --skip-srcrpm --spec \
    --define 'BUILDDIR_NAME /tmp/incremental-build/bin \
    --spec crosswalk-bin.spec
```
- If the build finishes, everything is good. Hooray!
- Otherwise, you need to look at the error output. It might be the case that a target has been renamed, or you need to update the list of dependencies in one of them or just fix Crosswalk's build system.

Push your changes

Once everything is working, you can push your blink-crosswalk, chromium-crosswalk and v8-crosswalk changes to crosswalk-project if you haven't done so yet.

# Assuming origin points to [email protected]:crosswalk-project/{blink,chromium,v8}-crosswalk.git
cd /path/to/chromium-crosswalk/third_party/WebKit
git push -f origin master

cd /path/to/chromium-crosswalk/v8
git push -f origin master

cd /path/to/chromium-crosswalk
git push -f origin master

This should not break anything for Crosswalk users, as the SHA1 hashes referenced in the Crosswalk repository are still present in the forks.

Finally, create a single commit in Crosswalk that adjusts the code and changes DEPS.xwalk and send a pull request.