Index ¦ Archives ¦ RSS

Effecting code review and backporting for Collabora Online

Estimated read time: 3 minutes

Collabora Online now has a ./g script that tries to bring some of the Gerrit-based review benefits to a workflow based on GitHub.


Collabora Online is on GitHub, but core.git is still on Gerrit, so it made sense to spend some time on a small shell script that gives you review and backport experience that is closer to Gerrit than the stock GitHub workflow.

How we use GitHub

Most Online committers push their code for review directly to online.git, to private namespaced branches, like private/kendy/master, then a pull request can be created to get commits from that branch into master after CI, review, etc. This workflow has the benefit that you don’t have to deal with the complexity of multiple repos.

Next to master, there are distro branches like distro/collabora/co-6-4, we may or may not want to backport the contents of a PR to that stable branch.

It’s important that Gerrit used to have a git review command to just submit your changes for review, without asking anything. That explains why the stock GitHub workflow where you need to name the source branch of your PR feels unnecessary complexity. Creating the PR by visiting a webpage is again something we want to avoid. Not to mention open questions like should you delete your source branch after a PR is merged? Should you delete your source repo?

On the other hand, we’re interested in GitHub’s ability to have multiple commits in a PR: Gerrit forces to have one commit per change. The GitHub way encourages developers to split changes into more commits, now that the review and CI cost won’t increase just due to such splits.

Submit for review

The happy path is when you have one or more local commits and you want to submit it for review. In this case now you can do:

./g review

And the script will figure out that you want to push your local branch to a remote branch like private/kendy/master and also create a pull request for you, printing its URL.

In case that branch already exists then you need to specify a name:

./g review myhack

So parallel reviews are possible, but only the first gets an inferred name. Both cases need no clicking in a browser, thanks to gh.

Submit a backport

The easiest case is when you can assume that the master branch and the distro branch is so close to each other that there won’t be conflicts to be resolved. In that case, you can do:

./g backport distro/collabora/co-6-4 790

to pick all commits from PR 790 (which is already merged to master) to a distro branch.

Again, you can have multiple backports in progress, e.g. you can do:

./g backport distro/collabora/co-6-4 790 myhack

If the default name is already used. The backport syntax is a bit longer, so you can always just type ./g backport and you’ll get the usage.

This second command is a bit more complicated, as gh has no trivial way to expose what is the commit range of a PR. But there is gh api graphql which can do arbitrary GraphQL queries, which provide this information. At this stage it may make sense to just rewrite the whole ./g script in e.g. Python, but till that happens, we parse the output of the query using jq.

Finally, if you do have conflicts or you want a local build test / manual test before submitting, you can always check out the distro branch manually, cherry-pick there and use plain ./g review to submit your backport for review.

Want to start using this?

You can go to the Collabora Online community website and see how to build the code. Then you may want to solve an easy hack, finally submit your commit for review either by using the above method or whichever way you prefer contributing to GitHub projects.

© Miklos Vajna. Built using Pelican. Theme by Giulio Fidente on github.