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 or is otherwise staged on Gerrit waiting to get into the 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
git fetch origin
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:
Change-Id- see https://gerrit-review.googlesource.com/Documentation/user-changeid.html for more information.
Signed-off-by- see https://www.kernel.org/doc/html/latest/process/submitting-patches.html#sign-your-work-the-developer-s-certificate-of-origin
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
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
You can also use this to checkout changes that you have misplaced or lost.
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
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
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).