=============== 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: .. code-block:: bash 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: .. code-block:: bash 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: .. code-block:: bash 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 :ref:`updating-changes` for more information.); here we assume that is not the case. Update your branch with the `pull` command. For example: .. code-block:: bash 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: .. code-block:: bash 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 ``master`` branch, and ``origin`` is the prow-presubmit repo: .. code-block:: bash 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-changes: 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: .. code-block:: bash 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: .. code-block:: bash 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: .. code-block:: bash 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 .. code-block:: bash 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).