At work, I am daily using the Gerrit Code Review. For those not familiar with the tool, it is a web interface in which one can review patches, before they are merged to a git repository. As an Emacs user I have always felt there would be potential in being able to perform the reviews directly from within Emacs.
I looked around for a package, this was around 2 years ago, but I couldn’t find any that met my needs. So I ended up slowly building a package over time, and gradually migrated more and more of my workflow to Emacs. The package uses Gerrit's exposed REST API.
I have named the package egerrit, as in Emacs + Gerrit. Use the link to get to gitlab where the source code resides. I have decided to build it without other pakckages as dependencies, and instead rely on all the powerful tools already built in to Emacs. In order to use the package version 27 and newer should be all that you need.
So what features does this package provide, you wonder? Let’s go through it!
Dashboard
The entry point of the package is its egerrit-dashboard command. The default dashboard mimics the Gerrit web interface dashboard.
The content of the dashboard have been obfuscated using functionality from unpackaged.el package.
The package supports multiple views. A view is consists of one or multiple Gerrit queries. This is a useful feature in order to be able to quickly switch what changes that are currently displayed in the dashboard. Here is another view featuring Recently closed changes.
In the dashboard the user has access to Gerrit actions that operate on the change at point. These actions are accessible via the prefix key a. Some of the actions are:
rebase- toggle
WIP - toggle
abandon - open in
browser - add
reviewer user - add
reviewer group - …
Other functionality that the package provides can be grouped by the two different roles that the package assumes the user can have, for a specific change. These are namely either reviewer or author. Depending on which role the user have, egerrit will customize the workflow.
Author role
As an author of a change, you are interested in engaging in conversations about your change, as well act on suggested alterations to the content of the change. In the dashboard there is a keybinding for the command egerrit-open-conversations.
Conversations
To the left is a buffer with conversations. A conversation is built up by the filename it revolves around, the state in which the conversation is in. Which can be either done or todo. The revision, or patch-set, from which the conversation was started. A org-mode inspired source code block, where the context on which the conversation revolves around are shown. The code is shown with syntax highlight provided by the appropriate major mode. If part of the code has been selected in the web interface, it will be highlighted accordingly in the source block. And lastly the comments are shown by the different users.
To the right is the actual source code from the git repository. When in author mode, it is assumed that the user has checked out the code locally, otherwise it can be downloaded by the keybinding C-c C-d. When navigating between conversations in the left buffer, the source code will automatically be shown in the right window. This makes it very smooth to jump between conversations and address feedback if required. If you want to share your thoughts in a conversation C-c ' will open a comment buffer for you to type in.
When there are multiple conversations all other conversation except the one where point is will be greyed out to give the user more focus on the current topic. For an example see the Reviewer section further down.
CI jobs
Another type of feedback that can be provided on a change, is that by a CI system. The package comes built in with support that assumes that CI information can be deduced by comments on change, which would be posted by a CI user.
If configured properly the user can select a job directly in the dashboard. The content of the job will be downloaded locally and shown in a dedicated buffer. The package will do what it can to make it as similar as possible as what could have been created if the CI job ran locally. This means enabling compilation mode in the buffer, to quickly be able to navigate between errors in the job output.
In the above figure the output of the CI job is shown to the left and the source code to the right.
Reviewer role
The reviewer role might be the most common role for most users of Gerrit. Reviewer commands are accessible via the prefix key r when in the dashboad. Actually all those commands are have an author counter part as well. The difference between the two types of commands are that the reviewer commands takes care of providing us with the correct context.
With correct context we mean the following. Whenever we enter a review command the package will asynchronously in the background checkout the change we are about to review. That way the repository is transformed to properly match what we are reviewing. This has a great benefit that we can look up anything in the repository and know how that is in the context of this patch. Whenver we disengage in reviewing with C-c C-q the package seamlessly switches back to whichever branch we currently where at.
Review
As I just mentioned there are multiple review commands but the most commonly used one is the egerrit-review-change when in the dashboard, then the following will be shown:
To the left we have a window displaying the patch diff for the change that is being reviewed. The major mode in this buffer is built on top of Emacs’s diff-mode. To the right we have the buffer displaying all conversations that relates to the change. Lastly at the bottom there is a window where a comment is being composed in a response to one of the conversations.
In review mode, we can engage in conversations or start new ones. For the latter the user simply selects as region in the diff buffer and composes a comment. When finalized with C-c C-c it will be shown in the conversations buffer. When navigating between comments, the behavior in review mode is to update the location of the diff buffer to reflect the context of the conversation. Its possible to navigate to the source code from either the diff buffer or the conversations buffer.
Another advantage of using egerrit compared to the web interface is that composing comments you have direct access to, snippets, spell checking, dabbrev, etc. Which makes writing comments easier and more powerful. I also personally use the emojify mode in the comment buffer, which makes it possible add emojis if appropriate :)
So if you think that this package could be of use for you, feel free to try it out! You can find the source code here.