A heads up: We love GitHub
People frequently mess up using GitHub for code review, because GitHub is a platform that lacks the necessary tools to achieve such a goal without any pain.‍
Reviewing pull requests is a very sensitive part of an engineering team’s workflow. That’s why developers will spend more hours than desired using GitHub for code review, even if the platform becomes perfect. However, if a developer is going to spend 30–50% of her time on GitHub for code review, it would be very nice if GitHub took to a whole new level their code review feature. We’ll explain this in-depth in this article.‍
A heads up (we know you’re thinking about this): We don’t hate GitHub. In fact, we love GitHub and have built products on top of it! It’s also the platform where we host our open-source repos. It’s because we have used GitHub so much that we feel free to have this opinion.‍
GitHub for code review will explain syntax, but does it help?
Let’s start by saying that they announced GitHub Copilot X will explain syntax in the different file diffs. Which is sort of useful, but… Is it just a little improvement? Yes. Is it a game-changer? No.‍
Using GitHub for code review is much more than checking for syntactic errors. In fact, if we go a step back, this isn’t a problem at all because linters on people’s IDEs exist. Linters will help you identify if an import is being done incorrectly, or if a variable is incorrectly typed, among many other things.‍
Let’s look at the example their landing page provides.‍
Taken from GitHub Copilot X’s landing page
We don’t have access to the code of the example per se, but the example tells us which files have been modified, what imports have been added, and what methods and constructors have been added.‍
All of these pieces of information can be easily inferred by the developer by looking at the file diffs. If you’re reading the code, we’ll presume you are a developer that knows the language.‍
Will it satisfy the business requirements? Is the code orthogonal and clean? What about any security vulnerabilities being introduced? What about the code not being efficient enough, perhaps? Testing instructions?‍
This is where the true opportunities for improvement of the GitHub for code review UI exist. We’ll make a few suggestions.‍
Improve diffing
Let’s be honest. When a file has a lot of line changes and has the “Load diff” text, it tends to get ignored in the GitHub for code review process. What people tend to incorrectly do is skim through the file diffs. Hopefully they might run the program in the new remote branch as well. But it’s not like people look at every green line in detail, and it’s not because developers are negligent people, it’s because it’s an overwhelming UI.‍
We understand that requesting full file diffs is wishful thinking. It has a huge technical challenge that may not be so obvious. People expect line coloring, language specific syntax highlighting, linkable trees, and start/end lines among other requirements. GitHub has to parse multiple files and patches in the same diff because diffs are generated per PR, not per file. Therefore it’s hard to think about a lightweight solution to this problem, to ultimately present it in some beautiful HTML/CSS.‍
But if someone finds a technically feasible way of doing it, those of us who use GitHub for code review will be grateful.‍
Reorganize discussions
The comments per file diff, to have as resolved/unresolved conversations is a little bit uncomfortable.‍
Has it ever happened to you using GitHub for code review that you send a PR, a teammate leaves a comment on a diff, you fix the objection, and then the reviewer doesn’t resolve the conversation and it feels vague to you whether the reviewer feels the new approach is correct or not?‍
This could be solved if there was a unique discussion thread on a sidebar. One that’s more visible, and makes resolving/unresolving conversations easier. The conversations tab on the code review UI (the main code review UI) works. However, comments sink in the sea of commits. It would be even better to have something like it but oriented towards resolving and unresolving conversations on the files changed tab.‍
GIFs
A smaller request, but imagine how expressive would the GitHub for code review process be if we could joyfully react to the approval of that PR that has been stale for months with something like this, as we do on Slack.
Taken from giphy
Pre-approve Pull Requests that satisfy the business requirements
This also sounds just like a wish, but hear us out.
‍A lot of PRs stay unmerged, in debate after debate, after weeks or even months not because of the technical complexity of the change (we’ve heard about horror stories of text changes staying stale for 6 months because of this), but because of the business impact debate: “Will this change increase engagement, revenue, etc?”‍
We thought that it would be really cool to build a tool that understands the business logic of the codebase and the changes being introduced to determine if the PR will or will not meet the user’s requirements. Then, pre-approve the PR based on that. Like a copilot for PRs, with business logic at its core.‍
That’s why we built an open-source passive docs search engine to contextualize your team’s pull requests. Index information from Slack, Notion, GitHub, Jira, and an ever-growing list of integrations. Then paste the most relevant information tied to that pull request on a comment, and finally use that indexed information to compare its intent with the actual intent of the pull request (its title) to label it as “🍉Safe to Merge” if those two intents are similar enough.‍
It looks like this.‍
Our tool concluded that PR #297 will satisfy the business requirements
Enjoy an enhanced GitHub for code review process!
Top comments (0)