| =============== |
| 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 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: |
| |
| .. 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). |