Gerrit Workflow

KUnit can refer both to the unit testing code within the Linux kernel and to the project as a whole, which includes some other supporting code. The meaning is usually clear when used in context.

With that said, KUnit, as a project, is made up of several repositories. As mentioned elsewhere, the actual KUnit unit testing code is in the upstream Linux kernel. All our other code is in Gerrit. For an introduction to Gerrit (with a high level overview of git), see https://gerrit-review.googlesource.com/Documentation/intro-user.html. For detailed introduction to git, see https://try.github.io.

Starting from Scratch

This section describes how to start a change from scratch.

Cloning a repo for the first time

If you have not done so yet, clone the repository you want to make changes to. For example:

git clone https://kunit.googlesource.com/prow-presubmit

Checkout the desired branch

Checkout the branch on which you want to make changes to. For example:

git checkout master

Make sure your branch is up to date

If you have not done so in a while, you will need to update your repo and branches. Your remote references can be updated with the fetch command. For example:

git fetch origin

where origin it the name of the KUnit remote, by default origin is the name of the repository that was cloned.

Now that you have updated your remote references, you need to update the local branch you will be working on. If this branch is only local to your repository, you may need to rebase it on the remote branch you are trying to get your changes into (in this case, you would already have changes underway. See Updating Existing Changes for more information.); here we assume that is not the case. Update your branch with the pull command. For example:

git pull origin -ff

-ff forces git not to merge upstream changes into your branch. This is important as we, the KUnit project, do not want merge commits in our git repos. This command will fail if you have local changes.

Making a change

Once you have made a change, that you are happy with and would like to send up for review you first need to commit the change. For example:

git add path/to/a/file/you/modified
git add path/to/a/different/file/you/changed
git commit

A git commit should be a logical, bite-size change that is easy for your reviewer to understand.

Your commit message should have a:

  • subject - line on top that provides a vague idea of what you are doing.

  • body - which describes in more detail what you are doing.

The bottome of your commit message should have:

Sending changes for review

Now that you are happy with your commits, you need to send them for review. This is done by pushing them to Gerrit with the push command. For example, let’s say you want your changes to be submitted on master branch, and origin is the prow-presubmit repo:

git push -u origin HEAD:refs/for/master

If pushing succeeds, Gerrit will respond by printing out the link where you can find the review.

Updating Existing Changes

This section describes how to update your or another user’s changes.

Checking out someone else’s changes

Gerrit allows users to take over changes made by other users. This can be done by checking out a change that is currently under review (and then pushing modified versions of those changes). Let’s say there is a change at https://kunit-review.googlesource.com/c/prow-presubmit/+/2569; you can checkout this change and its dependencies by clicking on the download button; it will provide you several options, the first option provides a git command that you can copy to your command line and run, such as:

git fetch "https://kunit.googlesource.com/prow-presubmit" refs/changes/69/2569/1 && git checkout FETCH_HEAD

Tip

You can also use this to checkout changes that you have misplaced or lost.

Updating changes

Once you have checked out the changes that you need to update, you may want to update them, as the branch you are looking to submit to may have progressed; this can be accomplished by rebasing against the branch you want to submit to. For example:

git rebase master

Now you need to modify the commits to address reviewer’s comments, or maybe you realized that you forgot something that should be in an earlier commit. Modifying commits may be accomplished with interactive rebase. Interactive rebase is a very powerful git command and is discussed in some detail here: https://dev.to/blakedeboer/beginners-guide-to-interactive-rebasing-1ob.

You might start an interactive rebase with:

git rebase -i master

Note

Only modify commits that are actually under review; changing commits that have already been checked in will cause Gerrit to yell at you.

Sending changes for review (again)

All you need to do to update your changes on Gerrit under review is to push your modified commits to the same branch that you would have as if you were pushing for the first time.

For example, let’s say you want to submit your changes to master; you would then

git push -u origin HEAD:refs/for/master

You may wonder how Gerrit knows to replace the old commits at this location with the ones that you modified; the secret is the Change-Id. A Change-Id should almost never be changed when updating a commit; it tells Gerrit that the commit is the same commit as before even though everything else may have changed about the commit (including the commit hash).