Estimated read time: 3 minutes
Collabora Online now has a
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
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:
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
./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.