
_Exciting News! We are joining Snyk!_

At Reviewpad, we are on a mission to help developers safely contribute to any codebase as fast as possible. Technological progress depends on the human ability to create and modify software systems.

Pull requests are used by millions of developers on a daily basis as a way to collaborate on code. However, pull requests are one of the major bottlenecks in the whole software development lifecycle.

With the current rise of AI-powered code generation tools, we are also seeing fundamental changes in the way developers collaborate around the world. We are convinced that pull requests will play a core role in accepting changes generated by AI tools.

Developers deserve a better experience in this collaborative process and it is this next-generation experience that drives our work at Reviewpad.

At the core of this experience is safety - developers should be able to go faster without increasing the risk of introducing changes that can hurt their products, users and organizations.

We have found Snyk's values to be aligned with our core values; bringing developers and security practitioners together so that AppSec can become developer-first.

In the past years, we have closely followed Snyk's path and it has been an inspiration to see them disrupt the AppSec market and improving the security of software products used by millions.

We are thrilled to announce that we will be joining Snyk to help developers code, commit, and stay secure without slowing down. 

By joining Snyk, we're doubling down on our mission to positively impact developers' lives. 

We would like to thank our users, champions, customers, partners and investors for their support in our journey. We are just getting started!

We are just getting started and excited for what's next!

Adriano Martins and Marcelo Sousa,

Co-Founders, Reviewpad


Last week, we launched the first in our series of posts on Reviewpad Check titled "Highlighting Friction Points in the Review Process With Help of Reviewpad Check." In it, we delved deep into the intricacies of the `long-pick-up-time`, `many-comments`, and `many-review-iterations` checks. Today's post shifts the focus to another trio of checks: `stale`, `large`, and `long-lived`. These particular checks are invaluable for identifying pull requests that are exceptionally bulky, drag on for an extended period, or receive little to no attention. Such PRs often become stumbling blocks in the development process, hampering efficient collaboration and bogging down progress.

## Understanding those Three Key Checks
### Stale Pull Requests

**Identified by the stale check, these pull requests see no activity for a set number of days**, with "no activity" defined as a lack of new commits or comments.


Neglecting such pull requests can inhibit project progression and jeopardize code quality. The older they get, the more out-of-sync they become with the main codebase, making their integration harder and their context less relevant. A collection of stale pull requests can also indicate broader issues in your review process, like communication gaps or bottlenecks.

### Large Pull Requests

**The large check identifies pull requests that add a significant number of lines to the codebase.**

Such pull requests, while sometimes necessary, can be daunting to review. The complexity introduced by their size can make errors easy to miss and muddy the clarity of changes, especially when those changes tackle multiple functionalities. A systematic approach to dissecting these large pull requests is crucial to ensure code review quality


### Long-lived Pull Requests

**With the long-lived check, pull requests that remain open for an extended period are flagged.**

These pull requests indicate inefficiencies in the development workflow. Extended open times suggest infrequent code integrations, which can result in complicated merges and a higher potential for conflicts. This disrupts team workflow and can delay feature releases, affecting overall project timelines.


### Activating those three Checks

Wondering how to track these pull requests using Reviewpad? It's effortless. By default, these checks are active when you enable Reviewpad Check. Identified pull requests will be automatically labeled by Reviewpad, giving you an immediate heads-up.

However, if you need customization, you can modify the behavior of these checks using the `reviewpad.yml` configuration file:


```yml
checks:
  stale:
    parameters:
      max-idle-days: 15
    label: stale

  large:
    parameters:
      max-lines: 400
    label: large

  long-lived:
    parameters:
      max-days: 30
    label: long-lived
```
## Conclusion
As we explore the diverse checks offered by Reviewpad in this series, it becomes abundantly clear that proactive pull request management is the cornerstone of efficient development workflows. With the spotlight on stale, large, and long-lived PRs today, we aim to equip tech leads and senior developers with the tools to sidestep common pitfalls and foster robust collaboration. Stay tuned for more insights in upcoming posts!


__Automation is key to increase the quality of code reviews. However, for some, there is a tendency to overestimate the power of automation and try to replace the human factor in code reviews. In this post, we explore what machines can do for us, and why they will never completely replace human interactions in code reviews_._

Automation is a catalyst of progress and widespread adoption. Taking GitHub’s pull requests as an example, in March 2021, [over 50% of the pull requests on public repositories were opened by bots like dependabot](https://twitter.com/codereviewpad/status/1380552021632299010).

Used correctly in code reviews, automation saves you time, alerts you for integration issues, finds bugs, and shields you from some of the more tiresome parts of doing code reviews.

There are three aspects of code reviewing where automation can make the difference:

- Enforcing code style with linters;
- Find bugs with bug finders;
- Catch regressions with testing.

#### Linters

Linters have been around for a very long time. The first was developed in 1978 at Bell Labs by Stephen C. Johnson. He was debugging the Yacc grammar for C, and he constantly found himself hindered by portability issues. The basic idea remains the same to this day.

Linters perform **static analysis**, looking for bugs and discrepancies typically as patterns over abstract syntax trees. This is especially useful if you’re using a dynamically-typed language, [like Python](https://realpython.com/python-code-quality/). The less strict the compiler’s rules, the more you need linting. Modern IDEs run linters in the background as you type, and will immediately flag the most common errors live, whether they’re logical or stylistic.

#### Bug finders

Code reviews are not (just) for finding bugs. There is absolutely nothing wrong with automating the search for them. Bug finders flag the most common kinds of bugs, and that will certainly avoid mistakes.

Having developed bug finders for more than 10 years, you should understand how they work to understand their results. The efficiency of bug finders is [a topic of much debate](https://engineering.nyu.edu/news/truth-about-bug-finders-theyre-essentially-useless) - mostly because users of these analyzers don’t understand their limitations and capabilities. There's no harm in using them, but to trust them entirely is not something you should do.

#### Running tests

Automatically running tests as a part of code reviews can save you a lot of time. There are multiple benefits of automatically running tests: first you guarantee that the build is passing and second you can catch regressions. **Good testing practices** can prevent unnecessary work for code reviewers. 

It might also be useful for you and your team to keep track of test coverage metrics during the review to discuss the overall code quality of the codebase.

### Code reviews are about the code, but also about the people

A good code review is not about ticking boxes on a checklist. It's about understanding the code and perfecting it in a collaborative and continuous way. As we said in previous articles, the earlier you can start doing code reviews the more you will increase its quality.

A key part of the review is allowing a second party to be part of the creative process, understanding the code and what you are trying to do with it. This will allow for a greater understanding of the code from everyone involved, and it will allow for **proper discussion and documentation** of design choices.

Of course, this doesn’t mean you need a human to validate every little thing. Sometimes a green continuous integration pipeline is enough to merge a pull request.

### Why automation should be done with care

It’s about **culture**.

Automation is a tool. It doesn’t have a connotation, it is as good or as bad as the use we make of it. As far as we’re concerned, automation is great for code reviews. It lowers the number of errors, saves time, and makes everyone more efficient and productive. 

Issues will start arising if and when developers only have automatic tools in their toolbox. When all you have is a hammer, everything is a nail.

If you apply the Continuous Improvement model to software development, then you will likely want code reviews to be integrated into your team’s processes. By thinking of code review as a boring chore that should be passed on to a machine, we risk creating a stigma around code reviews. They can be perceived as tedious. They can be perceived as an overzealous demand that doesn’t truly improve the code.

It is very important that teams understand **why** we do code reviews, and the best way to demonstrate it is by doing it right, because then the results speak for themselves.

### Tools are not perfect

A linter is just fine. You can trust it to do what it does because it does a basic thing. Security analyzers, for instance, aren’t. The number of [false positives](https://www.netsparker.com/blog/web-security/false-positives-web-application-security/) and false negatives they produce can kill your trust in the tool, and it would be tremendous irresponsibility to simply leave things the way the machine presents them to us with a shrug.

Codacy posted [an article](https://dev.to/codacy/code-review-vs-testing-8b8) telling a story that perfectly encapsulates why testing and automated processes aren't sufficient and will never replace proper code reviews.

A large political party was developing a comprehensive solution that would be used for their campaign. They had a dedicated testing team that ran tests every day on everything they made.

When the time came to launch the platform… it failed.

Why?

Because it was a **Sunday**.

The tests only considered the weekdays. Due to some issues with 0-indexed arrays, the program didn’t run.

This is the type of error that humans during code reviews would catch.

And, in our opinion, a human should always get the chance to do so.

* * *

At Reviewpad we are constantly developing new features to mitigate these issues:\
[Reviewpad Protect](https://reviewpad.com/protect) - Protect pull request merges by applying rules to your repositories to block merges that break your code review policies, code quality, compliance, and security standards.\
[Reviewpad Check](https://reviewpad.com/check) - Gain insights into the organization's pull requests, improve developer productivity, and prevent collaboration bottlenecks with insightful dashboards and alerts automatically generated for all your pull requests in all your repositories. \
[Reviewpad Automate](https://reviewpad.com/code-review-automation) - Automate tedious tasks with tailored workflows that streamline the Pull Request process, enabling faster scalability and hassle-free management.\
[Reviewpad AI Summary](https://reviewpad.com/ai-code-review) - Get a pull request description automatically generated and instant feedback on the code you are reviewing using our AI agent.


We are building a better future for pull requests and code reviews - [share with us](https://reviewpad.com/discord) your experience and pains.


_We introduced Reviewpad Check a month ago, a tool designed to promptly identify potential collaboration hitches in pull requests. Just as a code analyzer promptly detects bugs, Reviewpad Check discerns collaboration inefficiencies in real-time. Today, we'll delve into three specific checks that target friction points during the review process: `long-pick-up-time`, `many-comments`, and `many-review-iterations`._


## Understanding those Three Key Checks
### Long-Pick-Up-Time

**What it does:** This check identifies pull requests that have been awaiting review for an extended period.

**Why it's vital:** Extended waiting periods for PR reviews can significantly bottleneck progress. Such delays postpone the merge of new changes and create uncertainties for authors. This uncertainty can affect morale, ultimately impeding development momentum.

### Many-Comments

**What it does:** Flags pull requests that accumulate a high number of review comments.

**Why it's vital:** A surge in review comments can indicate potential alignment issues among team members. Such discrepancies might arise from varying views on code implementation, design choices, or even the project's trajectory. Besides suggesting complexities within the PR, numerous comments can elongate discussions, thus decelerating the development cycle.

### Many-Review-Iterations

**What it does:** Detects pull requests that have witnessed multiple code revisions due to reviews.

**Why it's vital:** Multiple code changes post-reviews can imply that the original PR wasn't sufficiently prepped or executed. This scenario often translates to additional time and effort during the review. Moreover, it can hint at ambiguities in project guidelines or differences in coding standards within the group.

### Activating those three Checks

Wondering how to integrate these checks into your workflow? It's straightforward:

Reviewpad’s checks come pre-activated. Simply install Reviewpad, and it'll start flagging problematic PRs. For every detected issue, Reviewpad automatically labels the PR. However, if you wish to adjust the checks, you can use the `reviewpad.yml` configuration file.

```yml
checks:
  long-pick-up-time:
    parameters:
      max-hours: 72 # 3 days by default
    label: long-pick-up-time


  many-comments:
    parameters:
      max-comments: 20
    label: many-comments


  many-review-iterations:
    parameters:
      max-iterations: 6
    label: many-review-iterations
```
## Conclusion
In conclusion, timely detection and resolution of collaboration inefficiencies can boost a team's productivity. With Reviewpad Check, tech leads and senior developers have a robust toolset to identify and mitigate potential hitches, ensuring smoother PR reviews and faster project turnarounds.



At the risk of sounding too cliché, the answer is clearly a maybe. More interesting than that though, is understanding how you can ensure they aren’t and put a process in place that is helpful instead of hurtful. Code reviews that are treated as chores and don’t add the value that was promised are more prevalent in our field than what we might like. However, if we start with the assumption that everyone is smart and doing their best, what are we left with?

## The purpose of Code Reviews

In my opinion, most of the times people complain about a code review process, it stems from a lack of a shared understanding of what problems it is solving.

According to [Wikipedia](https://en.wikipedia.org/wiki/Code_review) a Code Review is: 

> a software quality assurance activity

[Google defines](https://google.github.io/eng-practices/review/reviewer/standard.html) it’s purpose as: 

> … make sure that the overall code health of Google’s code base is improving over time.

We could look at more definitions, but they would all lead us through the same rabbit hole because both “quality” and “code health” are highly subjective concepts. It is hard to build a deterministic process around these concepts, therefore we are left with a faint sense that code reviews should make your code better. As a developer myself, I need something more concrete.

A few things I think we should aim for when thinking about a code reviewing process are:

- Two brains are better than one (three brains are not necessarily better than two)
- Leveling up team members
- Spreading knowledge, both technical and product wise
- Boring processes will yield boring results

You might agree with all, some or none of them, but more important is that you and your team can agree on a list similar to this, because if you can’t, maybe Code Reviews are not the right tool for you.

## Thinking through a Code Review process

Now that we have established a baseline to help us think through what we want out of the process, let’s look at each point separately and how we can incorporate it.

### Two brains are better than one

This one is a no-brainer (pun intended), when you are coding by yourself you are deep down in the weeds and it is easy to miss some things that a fresh pair of eyes will catch instantly. The fact that most code reviewing tools show only the diff for that particular patch of work, makes it even easier for a reviewer to catch some of those silly mistakes. A particular pain point for most reviewers is not having enough context around a change to move past reviewing how something is done, into why something was done that way. Honestly, this is an extremely hard problem to solve simply with a code review. Some suggest that you should download the changes and run them locally, try a few alternatives, maybe even read the specifications for the task, if they exist, but even if you are familiar with that part of the codebase it is a hard task. A decent solution I’ve seen to this is to ensure that there is a technical specifications document that provides context as to why things are being approached that way. This document can and should be reviewed before any code is written, thus minimizing the time wasted. Bare in mind though, that as a startup this might be more process than what you can chew. Another possible solution is to pair program. By pairing you are in essence moving the review process from after the code is written to while the code is being written. Not everyone enjoys it and it consumes a lot of energy, but it certainly is a very good tool to be able to reach for. When pairing you might even do away with code reviews altogether if the pair is confident in both the language they are using and the part of the product they are building. How many reviewers is a good amount of reviewers? It really depends on the dynamics of your team, but I’d say that a second reviewer will add very little and a third one is almost always a net loss in productivity (unless there is some very specific knowledge you need).

### Leveling up team members

More junior members of your team will learn a great deal from getting reviews from more senior members. It is, however, very important that there is a culture of positive feedback and of non-blaming, in order to create a safe environment for people to grow. Aggressive or demeaning comments in a review should simply not happen. There are multiple articles on code review etiquette, I recommend [this one](https://www.alexandra-hill.com/2018/06/25/the-art-of-giving-and-receiving-code-reviews/). Although a code review can be a good way to learn, it can also take a long time in an asynchronous back and forth between reviewer and reviewee. In that case, consider a synchronous mechanism of communication, such as a chat or preferably getting on a call. Pairing to start with is also a nice alternative here, depending on how much you prioritize the leveling up of said team member.

### Spreading knowledge

The simple existence of code reviews, more or less guarantees that there is no part of a codebase that only one person knows or has ever seen. Other than building a feature on a given codebase, this is probably the best mechanism I’ve seen to keep people in the loop of what is happening. Any process that entails keeping documentation up to date, I wouldn’t trust, as documentation can and will be outdated at some point. Periodical presentations on certain topics or parts of the system are also great, but nothing beats code reviews as a systematic way of sharing what is being worked on and how.

### Boring processes will yield boring results

Having a code review process with unnecessary steps is sure to make your team stop caring. Code reviews should not be about code formatting, an automatic linter can do that. They shouldn’t be about ensuring tests exist and pass, a CI can do that. The more of these repetitive tasks you can get rid of for your team, the less you leave for them that is not providing a good review. There’s a lot of companies that require a certain number of approvals, or even worse, that a certain person approves, in order for code to be merged. I understand that sometimes this is a legal requirement, but take into consideration that albeit well intentioned this could be a blocker for your team and in time become a pro forma, executed blindly.

### Final Process

To sum up, we want a code review process in which anyone can review anyone’s code, providing useful comments and positive feedback. This should lead to a well rounded team that is not afraid to tackle issues in any part of the codebase, that is excited by the possibility of helping build the best product they can.

## Common pitfalls

Even taking into account all of what we’ve discussed so far, there are some common pitfalls when doing code reviews

### Reviews taking too long

It is extremely common to have reviews taking too long, either because there is no reviewer available, or because there are many comments back and forth. The former can be solved by ensuring that when a code is up for review, there is a reviewer assigned and nagging them until they review it or find someone else to review it. It is important to understand that a couple of people at 50% is better than one at 100% and another at 0. The productivity is the same, but the mental toll is not. The latter is usually a sign that the initial specifications or assumptions were wrong, there is a junior developer involved or that there is a debate of opinions. All of which can and should be solved by moving to a synchronous mechanism of communication.

### Reviewer is always the same

The number of reviews any one team member does should be more or less the same, but it is not uncommon to see a big disproportion here. The best way I know of how to fix this is to have an automatic mechanism of assigning reviews that ensures everyone gets their turn.

### Too many comments

This usually happens on small sets of changes (which is what you should aim for), in which a reviewer has a tendency to put too much of their personal opinion into a review and question everything that is done in a different way of what they would’ve done it. Raising the issue and working on code review etiquette is my favorite approach here.

### No comments

Also common is a code change being approved without comments. This could be a good sign, nothing to point out, or, especially in large change sets, that the reviewers skimmed through the changes without paying proper attention. My recommendation here is to aim for smaller change sets, breaking down a feature into smaller chunks, or pairing on the feature instead.

##### About the author

![Luís Ferreira](/posts/images/image1.jpg)

Luis is a co-founder of Subvisual, a Venture Studio with offices in Portugal and the US that focuses on helping early stage entrepreneurs bring their ideas to life. Luis has been developing web applications for over 10 years, mostly using Ruby and Ruby on Rails and Elixir and Phoenix. On top of that, he has taught web technologies to hundreds of people, through workshops, bootcamps and university classes.

#### Interested in a Featured Blog Spot?

 If you are interested in having a featured article in our blog, please reach out on [@reviewpad](https://twitter.com/reviewpad) with your proposal.



_In the past ten years, the popularity of pull requests has skyrocketed. Today, if you ask most developers about code reviews, they will immediately start talking about pull requests. While you want to review most pull requests, some can be automatically approved._

### Pull requests are everywhere!

In the last ten years, pull-based development and pull requests became extremely popular. In March 2021 alone (the last month of data), there were over 5.5 million pull requests opened on public GitHub repositories. 

<LineChart
  sets={[
    'Opened: 16713, 53185, 124387, 241162, 446755, 813781, 1043864, 1245612, 1701565, 3941162, 5557089',
    'Closed: 14662, 47898, 108364, 229187, 426689, 758589, 966436, 1163686, 1576497, 2848926, 3613682'
  ]}
  categories={['March 2011', 'March 2012', 'March 2013', 'March 2014', 'March 2015', 'March 2016', 'March 2017', 'March 2018', 'March 2019', 'March 2020', 'March 2021']}
  yAxisLabel='Number of PRs on Public Repositories'
/>

And it makes sense. If you have an open source project, pull requests are an excellent tool to systematically **validate and accept contributions**. It’s only natural that in the open source setting, code reviews will coincide with pull request validation. 

However, code reviews are an independent aspect of the development process. Also, the dynamics of a non-open source team is typically very different from the one practiced by open source projects. In such teams, there are [many benefits](https://reviewpad.com/continuous-code-reviews-are-the-way-to-go/) of integrating code reviews earlier in the development process in a **review-centric development**.

Making code reviews _a check on a pull request_ or using _pull requests as the way to do code reviews_ will hurt your perception of the [benefits of code reviews](https://reviewpad.com/why-you-need-to-be-doing-code-reviews/).

### Pull requests may be hurting your team

Pull request management is starting to become a costly business. Opening, checking, resolving conflicts, merging a pull request takes time and costs money. 

If you use pull requests as the main way to ensure code quality and share knowledge across the team, you have the tendency to start enforcing certain rules to format pull requests. The most widely used one is a size limitation.

We’ve come across teams where a simple refactoring on a codebase had to be split into multiple pull requests to comply with certain requirements. Those recurring situations lead to increasing confusion around the review process.

There are two main aspects associated with pull request validation: **automated checks** and **human reviews**. Understanding when you need to perform an automated validation or a human review is key to a better interaction with pull requests.

Running a continuous integration pipeline on every push to a branch that is part of an open pull request is a waste of resources.

Asking a team member to review a pull request with very simple changes when the automated checks have passed is also a waste of resources.

Communication with strangers (as it happens in an open-source project) versus communication with your team members is very different. Pull requests are a method that is very poor in terms of empathy. And that’s okay - it was not designed to be an empathetic/educational way to communicate between developers.

* * *

As developers, we need better tooling to help us manage our resources and asynchronously communicate around pull requests. That will help us reduce useless energy consumption, miscommunication between our peers and increase collective ownership.

At Reviewpad we are constantly developing new features to mitigate those issues:\
[Reviewpad Protect](https://reviewpad.com/protect) - Protect pull request merges by applying rules to your repositories to block merges that break your code review policies, code quality, compliance, and security standards.\
[Reviewpad Check](https://reviewpad.com/check) - Gain insights into the organization's pull requests, improve developer productivity, and prevent collaboration bottlenecks with insightful dashboards and alerts automatically generated for all your pull requests in all your repositories. \
[Reviewpad Automate](https://reviewpad.com/code-review-automation) - Automate tedious tasks with tailored workflows that streamline the Pull Request process, enabling faster scalability and hassle-free management.\
[Reviewpad AI Summary](https://reviewpad.com/ai-code-review) - Get a pull request description automatically generated and instant feedback on the code you are reviewing using our AI agent.


We are building a better future for pull requests and code reviews - [share with us](https://reviewpad.com/discord) your experience and pains.

## Update

In 2021 we ran a [Twitter poll](https://twitter.com/reviewpad/status/1379104883794661379) asking how many pull requested were opened by bots in March 2021.

[![](/posts/images/code-reviews-need-to-outgrow-pull-requests-tweet.png)](https://twitter.com/reviewpad/status/1379104883794661379)

The correct answer is 50 - 75%.

#### Opened pull requests of March 2021

We crunched the numbers and found out that ~62% were open by bots. dependabot alone opened ~46% of the pull requests.

<PieChart
  series={[2561299, 351469, 288286, 256722, 2099313]}
  labels={[
    'dependabot[bot]',
    'pull[bot]',
    'dependabot-preview[bot]',
    'Others Bots',
    'Rest of the PRs',
  ]}
/>



_Code review is one of the most underrated processes to increase code quality. There is still resistance to a process that is seen as unproven and associated with useless overhead. However, by understanding how code reviews can work, it becomes clear that the advantages far outweigh its costs. I am here to directly address the most common concerns and to share a vision for the future of code reviews._ **_Spoiler alert: it’s not a fancy AI tool that replaces developers._**

Now, any developer worth their salt is going to be checking and documenting the code over time. This is a given. There are many stages throughout development where bugs and mistakes are found. 

This is why you have specifications and run tests.

So how do you arrive at the return on investment (ROI) of a code review?

### Return on investment is hard to measure

Full transparency: it’s not easy to define adequate metrics to find out a code review’s ROI.

We do know some things. For instance: fixing a bug in the testing stage costs you on average [almost eight times as much as if you catch it before](https://www.typemock.com/software-bugs-infographic). And if it’s ever found after the product has shipped? Well, that’s about 15 times as much.

The benefits of code reviews permeate the entire development process. It improves communication, the sustainability of products, the onboarding of new joiners, and a number of other issues.

Of course, if you want to kid yourself, you can [try](https://smartbear.com/product/collaborator/roi-calculator/) to put a number on it.

At the end of the day, though, we need to be comfortable with the idea that a formula will never capture how important code reviews are as well as the people in your team. It’s all about **continuous improvement** - and that’s an integral part of a team’s **culture**.

### Understanding code reviews is simple

Sometimes, the major roadblock for teams to engage in code reviews is that they don’t fully understand what it means. As a developer, that resonates a lot - code reviews are time consuming, are typically unstructured and it’s quite easy to get lost in the process because of their cognitive complexity and frequent context switching. 

So, how can we get more structure into it?

Properly done, here’s what an experienced reviewer will be looking for:

- **Design**: the code must fit the purpose for which it was created.
- **Functionality**: the code must behave in the intended way.
- **Complexity**: simpler is usually better. Both for functionality and for maintainability.
- **Tests**: there must be tests in place with sufficient coverage of the changes.
- **Naming**: variables, classes, methods names need to be clear and self-explanatory.
- **Style**: the code must respect the engineering guidelines of the company.
- **Documentation**: it must be updated, and it must be relevant.

This strategy is in many ways a methodical and rigorous process to improve code quality. However, in practice, valuable code reviews are not box ticking - the main goal is to collaborate and improve the codebase which is the common working environment for developers.

Code review brings in different sets of eyes to look at your code. Think of it as a manuscript, and of the reviewer as a proofreader. It’s a brand new set of eyes, someone likely unfamiliar with the text, and someone that needs to understand it on its own merits.

The author shouldn’t need to be at the reader’s shoulder, explaining what is happening in the story. In the same way, **a code reviewer constructively should point out when your “narrative” doesn’t make sense**. This way, reviewers and the author collaborate on the best solution.

This is a job for humans and adding automation helps but in the code reviews that matter, you ultimately need human interaction to reach the best outcome for the team.

### Code review will help your team do its job

By talking with hundreds of developers, we have learnt that teams with a strong culture on code reviews are able to **communicate effectively.** Not just sporadically, **consistently**. This is because code reviews don’t simply fix bugs, they also ensure that the codebase is clean and easily understandable for others to maintain.

As developers get used to comprehensive code reviews, they will start changing how they code accordingly. This means code becomes easier to understand by others and a lot of time is saved going back and forth within your team.

### (especially if your team is remote)

Most of us are working remotely at the moment, due to… ahem… current events. What we are starting to come to grips with is that some kind of remote work environment is not going away. Ecommerce in particular has been the canary in the coal mine regarding this issue. Consumers and companies alike have realised that there are a lot of advantages in working and buying from a distance, and in-office work will probably never revert to its pre-pandemic levels.

That means **effective communication is now at a premium**.

High quality code reviews help teams build codebases that facilitate communication, and that lets people get straight to work with very little synchronous guidance.

### Are code reviews a silver bullet?

Simple answer: no.

What if the original code is a huge incomprehensible mess? Won’t reviewers spend hours on end trying to figure out how to even begin to understand the changes? Probably.

The complexity of the review itself increases exponentially with the number of changes, the maturity of the codebase and the lack of expertise of the reviewer. However, somehow this complexity feels artificial at times and we believe that has to do with the interface most reviewers are using right now. It is just a **textual diff between files**.

We started Reviewpad because we believe that it should be possible for developers to have the relevant information about code changes out of the box. Ultimately, we want to systematically help developers create an intuitive guide for reviewers to dramatically reduce the number of useless interactions required today.

There’s also the issue of communication and documentation which I will write about in the future.

### We are working to make code reviews better

Reviewpad’s long-term goal is to make high quality code reviews easily accessible for teams of any size and working with codebases that might be recent or decades old. 

And we want to do it by protecting our most important resource: developers. For that reason, Reviewpad is being built with a _developers first_ mindset - it should **make code reviews better** by making it easier for developers to extricate themselves from bad code.

Reviewpad is always developing new features like:\
[Reviewpad Protect](https://reviewpad.com/protect) - Protect pull request merges by applying rules to your repositories to block merges that break your code review policies, code quality, compliance, and security standards.\
[Reviewpad Check](https://reviewpad.com/check) - Gain insights into the organization's pull requests, improve developer productivity, and prevent collaboration bottlenecks with insightful dashboards and alerts automatically generated for all your pull requests in all your repositories. \
[Reviewpad Automate](https://reviewpad.com/code-review-automation) - Automate tedious tasks with tailored workflows that streamline the Pull Request process, enabling faster scalability and hassle-free management.\
[Reviewpad AI Summary](https://reviewpad.com/ai-code-review) - Get a pull request description automatically generated and instant feedback on the code you are reviewing using our AI agent.



*The code review process can often be tedious and filled with bottlenecks, making it slow and time-consuming. However, there are tools like Promyze and Reviewpad that can greatly assist in improving the code review process and saving you and your team a significant amount of work. In this article provided by Promyze, you'll discover effective strategies on how to expedite your review process.*

Code reviews through Pull/Merge Requests have become an essential process for the majority of tech companies.
A recent study in 2022 unveils that 84% of the surveyed companies use it.
Several years of practice allowed practitioners to take a step back on this methodology to identify pain points and how to overcome them.
Besides, code reviews should always be continuously evaluated internally to improve how it’s done.
In this post, we discuss how to add more flexibility to the Pull Request process and, thus, improve the delivery time.

The lead time for change is the amount of time it takes a commit to get into production, and is part of the 4-key metrics defined by the DevOps Research and Assessment (DORA).
Engineering teams seek to optimize this delay to deliver sooner value to their customers. But before bringing solutions, let’s first define the problem:

> *During code reviews, what can slow down the whole process, create bottlenecks, and grow the lead time for change?*

<Iframe width="560" height="315" src="https://www.youtube.com/embed/cqxtE-DcvcA" title="YouTube video player" allowFullScreen={true} />

***

## Narrowing the context and purpose of code reviews

The most often quoted obstructions to code reviews are the lack of human resources and the workload of engineers that don’t allow enough time for code reviews. A common reaction consists in adding more human resources to address the issue. Not so fast!

First ask yourself:
*Is each code review truly necessary? Can we affirm that all the discussions within reviews are relevant and should happen there?*

Indeed, what we observe in practice is that code reviews often lack a clear context and purpose. If you’ve opened a merge/pull request, what do you expect from that? From our point of view, we propose two primary purposes for a Pull Request.

### #1 Code approval

*I need to ensure my code is okay before merging ⇒ I need your approval.*

In this case, it may raise friction from both sides, as reviews come late in the process.
Authors can feel reviews as a constraint that slows down their delivery, and a frustration to get many comments, with which they won’t always agree.
Reviewers can also adopt defensive behavior. What if they think: “I wouldn’t have done \[the code] this way.
Should I tell this? Should it be blocking for merging? My colleague waits for 2 days; how will my feedback be welcome?”
So you can see that frictions can emerge from code reviews, mainly because we have the pressure induced by the quest for a satisfying lead time for change.

### #2 Get help to improve the code

*I’d like to show you my code and get your feedback to improve it ⇒ I need your help.*

Compared with item #1, we’re looking to improve our code and learn from a peer.
In this context, it’s worth considering whether this review is part of the delivery process.
We may be convinced this code could be merged first. That’s something commonly observed in trunk-based development.

The workflows and policies are different based on the context of the PR, so it makes sense to define it clearly.

Another problem we observe during code reviews is the long discussion threads about implementation choices, design, and best coding practices.
And there, discussions get emotional and passionate: this is precisely what we want to avoid during reviews.

## Do we still need code reviews?

Aside from this discussion, you may ask whether doing code reviews still make sense in 2023, in an era where we can find plenty of “DevOps automation” tools on the market.

We consider that, yes, indeed, code reviews are still necessary.
Even though automatic tools have become increasingly powerful, they’re good at detecting known problems.
They can’t prove the absence of problems. Think about this Dijkstra quote:

*“Program testing can be used to show the presence of bugs, but never to show their absence!”*

So during a Pull Request, we seek for what tools can’t detect.

Now let’s go back to our main point: how to address the aforementioned issues?

## Do code reviews only when it makes sense

### The concept of Fluid Pull Request

To answer the question: “Do all Pull Requests require a code review?”, we can explore the model Ship Show Ask. In this approach\*,\* PR authors are considered free of trust to evaluate themselves if:

* The code doesn’t require a code review since the changes are trivial (Ship)
* They’d like to show the code changes to colleagues and get their feedback (Show); This mode can sound totally counternatural as the feedback can be provided after the merge. This is part of the paradigm shift.
* The code requires a review (Ask)

So instead of adding more human resources to review the code, we reconsider the necessity for each PR to be approved;
This is how we can positively impact the lead time for change. This concept is also called Fluid Pull Request.

### Next generation pull requests with Reviewpad

Reviewpad is a GitHub app designed to automate your code review process and which implements the Fluid Pull Request concept.
A single configuration file in your Git repository will contain all your workflows and policies for your Pull Requests.
Based on the context, you’ll define rules to enforce or relax your security net. With Reviewpad, you can define rules such as:

* If a file in this folder is edited, one person from this group should approve the code.
* If the PR includes a new method in the code with an annotation @Critical, add a label ‘security, and require a double-validation.
  Rules can decide whether PRs can be automatically merged or refused, define a validation workflow, and more.
  Rules can address syntactic patterns in the code changes.

Here is an example of workflow to automatically raise awareness when a critical change is introduced:

```yaml
labels:
  critical:
    description: Modifications to critical changes
    color: "#294b75"

groups:
  - name: owners
    spec: '["lina", "caris"]'

workflows:
  - name: changes to critical code
    run:
      - if: $hasAnnotation("critical") || $hasFileName("runner.go")
        then:
          - $addLabel("critical")
          - $assignReviewer($group("owners"), 1)
          - '$info("@samir: you are being notified because critical code was modified")'
```

## Discuss best practices and design outside code reviews

### Knowledge sharing should be collective

f you request a review to improve your code or show it, this shouldn’t be done under pressure before merging the code.
Engineers should instead find dedicated time to discuss code design and best practices, avoiding friction.
If you’re having a 1:1 conversation and debating about a best practice, you hold a discussion that may impact your whole team.
Indeed, if you come up with a decision, shouldn’t everyone agree with that? We can assume that you seek code uniformity and practice alignment.

So maybe it’s time to consider running dedicated workshops on your best coding practices, as 1:1 conversations should not be the right place for that purpose.

### Best practices sharing with Promyze

Promyze is a knowledge-sharing platform for developers and provides integrations with IDE and code reviews (GitHub, GitLab, Azure DevOps, Bitbucket, and Helix Swarm).
With the code review plugins, you can create a best coding practice from a comment, and the code is sent to Promyze along with your best practice proposal.
You thus avoid long 1:1 discussions during code reviews.

![](https://www.promyze.com/wp-content/uploads/image.gif)

Then, Promyze helps your team regularly run dedicated workshops to review contributions from developers (made during code reviews or within IDE).
It’s a suitable time to share knowledge and make technical decisions together and ensure everyone is aligned with the appropriate gestures to apply in the code.
This is a continuous improvement process for your best coding practices and to grow developers’ skills.

## Want to accelerate your code reviews?

If you feel your engineering team has bottlenecks in their code reviews, we hope you found in this post some insights to improve your process:

* Consider the necessity to approve each code change;
* Consider dedicated sessions to avoid never-ending discussions during reviews.

We also showed that Reviewpad and Promyze can be complementary to accelerate the code reviews while fostering knowledge sharing.

Tell us if you’ve improved your lead time for change in your context and how you made it; we’d be happy to learn!



In this second part of the evolution of code review, we explore the impact of emerging trends in application development. Discover the significance of the shift-left approach, the challenges posed by microservice architectures, and the rise of DevOps-related concepts like GitOps. Embrace change management and explore tools like ReviewPad that automate and streamline the code review process, ensuring swift and confident deployments for your applications.

This is the 2nd part of a 2-part series on the evolution of code reviews. If you haven’t already, check out [Part 1 here](/blog/the-evolution-of-code-reviews-the-beginnings). In the first part of this series we saw how code reviews were performed in the early days of application development, and how the process if stressed could result in major issues and disruptions. The story of the London Stock Exchange and … is just a couple of examples from a long list of stories where companies suffered because of their outdated or faulty code review process.\
In this second part, we will go over some of the trends that have come up in the world of application development. By understanding these trends we will be able to understand the needs for the future of the code review process. So lets continue on our journey.

## Emerging Trends and Their Impact on Code Reviews

Over the past decade, with the DevOps revolution kicking off, we have seen many emerging trends that have redefined how applications are developed and how code goes through development to review to production. Many of these trends, coming, have had an impact on the overall code review process, and it's necessary to understand these trends to understand what lies next.

### The Whole Org Shifts-left

Shift-left advocates for quality control measures of code to occur sooner in the development process, near the time code is being written. This approach enables teams to quickly spot and address any issues, reducing the possibility of defects and enhancing the general standard of the software.
As a result, code reviews became essential to software release as the QA testing phase merged into the code review phase. No longer was it enough just to ensure that the code was compliant and met set standards but also that it worked and did not result in any regression.

### The Rise of Microservice Architectures

Microservices architecture [became popular](https://articles.noodlefactory.ai/riseofmicroservices) due to its ability to allow for more flexible, scalable, and agile software development compared to monolithic architecture.

However, with the microservice paradigm, it does become difficult to track how different services are related to one another, especially as your application scales. As a result, a change in one service could affect and even disrupt another.

So it became necessary that these dependencies are realized during the code review process. Some of the related services to the service experiencing the change may be extremely sensitive to disruptions and downtime as per the business goals set. Putting more significance on an effective and clean code review process.

### DevOps, GitOps, NoOps…Why?

With the rise of the DevOps concept, concepts under its umbrella also emerged. These included concepts such as GitOps, AIOps, and even NoOps. Whatever type of “Ops” you may adopt, the goal is the same. Increase the velocity of product development while maintaining the availability and stability of the application.

Overall, what is expected is the use of automation wherever possible, combined with the shift-left mentality, to aid in the two goals mentioned. We have seen now how the significance of code reviews increased due to other emerging trends. With the “Ops” trend, we tried to lessen the pressure on the code review stage using automation to ensure that changes could roll out quickly but also safely with high confidence that it's not going to break anything.

### The Future of Code Review

Considering the various trends in the application development space, one thing that becomes clear is that pushing changes with a high degree of confidence is key. This is where the concept of change management arises.

Change management is identifying, planning, and implementing changes in an organized and systematic way. It helps organizations deal effectively with change, minimize disruption, and maximize the benefits of change initiatives. Change management includes various activities, such as identifying the need for change, assessing the impact of change, communicating change to stakeholders, implementing change, and monitoring the results.

By realizing the need for change management, it becomes clear why new paradigms, such as Fluid Pull Requests, are gaining momentum when it comes to adoption.

[Fluid Pull Requests](https://reviewpad.com/blog/fluid-pull-requests) are an advanced form of the Pull Request method utilized in software development. In the traditional Pull Request system, a developer submits code modifications for review and evaluation by the repository managers. Fluid Pull Requests attempt to resolve these challenges by modifying the code review process based on the risk of the change.

![manual code review meme](/posts/images/MemeEvolutionofCode.png)

Risk could depend on multiple factors such as how the service being affected is related to other services. The type of change of whether it is a config change or a change in the front, and the number of incidents reported by the team performing the change.

Depending on the outcome of this assessment, various code review procedures can be established and automated to either lessen or increase the rigor of the code review process. For instance, if an important security patch is added, it might be necessary to include the security team in the code review process.

This is exactly the methodology that a team performing change management needs. Any tooling employed could  instill confidence in accepting the change, and even automatically merge the pull requests when the risk score is lower below a certain threshold. Increasing both velocity and stability of the application development life cycle.

This is why we are seeing increased adoption of tools such as [ReviewPad](https://reviewpad.com/) that automate the review process and instill confidence in code changes. Reducing the need for manual intervention and overall reducing the time it takes for customers to see value in the applications you are developing.

## Conclusion

The rise of various trends such as DevOps-related concepts, developing in the cloud, and new architecture paradigms such as microservices greatly increased the importance of code review, making it a possible bottleneck to the entire application lifecycle. As a result further is tools such as ReviewPad, which enable you to perform change management with the speed and confidence required.

***



Code review is now a vital part of software development in the age of DevOps. Understand the evolution of code review from its early days to its present shape. We'll look at how code review has adjusted to the demands of development teams, from time-consuming manual reviews to efficient automated ones.

With the rise of DevOps, the code review process has become a substantial part of software development. The right code review process ensures that our applications are highly available and can be built with high velocity.

Over the years, code review has evolved from manual processes to automated tools, adapting to the changing needs of development teams. As application development continues to evolve, it's essential for code review to keep pace and provide teams with the best possible workflow for ensuring code quality.

In this 2 part series, we will explore the evolution of code review from its early days to its current state. We'll look at how code review has adapted to the needs of development teams, the trends driving its evolution, and the future of code review.

In this first part, we will go through the pages of history to understand how the code review process came into existence, and how some of the shortcomings led to major disruptions.

Whether you're a team leader trying to set the right practices for your development team, just a seasoned developer or simply starting in the software development world, this series will provide valuable insights into the importance of code review. Join us on a journey through the evolution of code review, and discover how it continues to shape the future of application development.

## The Dark Ages

In the early days of software development, code review was a manual process. Developers would physically sit down together and review the code line by line, discussing any issues or suggestions. While this method was effective, it was also time-consuming and not scalable for large development teams.

![Developer reviewing code in 2008 meme](/posts/images/DevelopersReviewingCodein2008.png)

The  [introduction of Git in 2005](https://www.welcometothejungle.com/en/articles/btc-history-git) revolutionized how software development teams worked. It scaled the way teams, and contributors could now collaborate as developers could submit their code changes as pull requests. These pull requests would then be discussed and reviewed by other team members and, once accepted, were automatically merged into the main codebase. This was the rise of version control and all its benefits, such as keeping a history of changes and being able to roll back to previous versions.

However, this method relied on manual reviews, and the feedback process was often slow and inconsistent. With Git, teams had the flexibility to conduct code reviews in any way they saw fit, which led to inconsistencies in how code was reviewed. Different teams used different processes and tools, and the process of manually checking the pull request still made it difficult to standardize the entire code review process.

Overall the code review process was very manual and slow. Cutting corners to get functionality out to production often meant disruptions and bugs.

## When Disaster Hit

This is exactly what happened to the [London Stock Exchange on February 8th, 2008](https://www.nytimes.com/2008/09/08/business/worldbusiness/08iht-lse.4.15984073.html). It's usually not the best time for a financial institution facilitating trade in Europe's financial hub to be down in the middle of a global recession. This disruption was caused due to a bug in the new trading system that was released then.

The impact was that trading came to a halt for almost an entire day, and till today the financial amount lost due to the impact is not publicly available. It is safe to say, though, there are significant losses for the Exchange and its customers. Given the scale of the incident and the impact, it had on the financial markets.

Another such example is that of [Knight Capital Group's trading systems](https://www.henricodolfing.com/2019/06/project-failure-case-study-knight-capital.html) which experienced an incident that led to a significant financial loss of $440 million in just 45 minutes. The issue was due to a code change that was not properly reviewed and tested, underscoring the significance of a comprehensive and efficient code review process.

## Conclusion

The code review process has become an integral part of software development with the rise of DevOps. Over the years, code review has evolved from manual processes to incorporating automation. This was due to the need to push changes faster while maintaining the stability of your systems.

However, meeting this requirement was something that was just not feasible with the way code reviews were being performed. Stress the system too much and you could have experienced great outages and disruptions such as that of the London Stock Exchange or…

By tracking the evolution of code reviews and being aware of the past issues, we know it is important for us to refine our coe review process. How we can do so is answered in [part 2](/blog/the-evolution-of-code-reviews-a-better-tomorrow) of this series where we continue our evolution into the future!

***



_Exciting News! We have raised €1M to streamline code reviews with AI._

We're excited to announce that we have raised €1M in a pre-seed funding round led by [Shilling VC](https://www.shilling.vc/) 
and supported by angel investors [Simon Brandhof](https://www.linkedin.com/in/simonbrandhof/) and [Freddy Mallet](https://www.linkedin.com/in/freddymallet/). 
This funding will support our mission to make Reviewpad an essential tool for developers worldwide, ensuring high-quality code, efficient collaboration, and seamless pull request management.

We've all struggled with time-consuming and inconsistent code reviews. 
That's why we created Reviewpad—to redefine the code review experience for developers. 
Our platform combines static analysis with artificial intelligence, including ChatGPT integration, to automate the review process and slash merge times by 50%.

Our AI-powered platform is set to transform both code reviews and pull requests, making the entire process faster and more efficient for developers. 
We believe that the purpose of AI is to assist in speeding up the review process and provide helpful information to developers, not to replace them. 
Developers are now using artificial intelligence to generate code, which makes the process of human code review even more important.

With this funding, we'll be expanding our team, investing in R&D, and integrating Reviewpad with platforms such as Gitlab, Linear, and Jira. 
If you want to be part of this amazing ride, [reach out to us](https://reviewpad.com/discord)!

Adriano Martins and Marcelo Sousa,  

Co-Founders, Reviewpad



_Introducing Reviewpad Summarize - an AI feature that summarizes changes on GitHub Pull Requests (and Issues) making code review more efficient and enjoyable._

At Reviewpad, we understand how precious time is for developers.

That's why we're excited to introduce `Reviewpad Summarize`, our new tool designed to help you save time while improving the quality of your code and fostering collaboration.

With `Reviewpad Summarize`, you can have a clear and comprehensive overview of the changes made in a pull request. It provides an easy-to-understand summary of code changes, highlighting the key modifications that require your attention, updated with every push. This way, you can focus on the critical aspects of the code and get your reviews done quickly and efficiently.

`Reviewpad Summarize` is not just any summarization tool.

It's an innovative approach to summarization that combines multiple summaries to generate a more comprehensive overview of the changes made in a pull request. Our research shows that this results in a higher quality summary, which allows for better communication among developers.


## How to Use `Reviewpad Summarize`

The `Reviewpad Summarize` feature can be triggered either by writing a comment in the pull request or by defining a workflow in the `reviewpad.yml` file.

### Using `Reviewpad Summarize` via Pull Request Comment

1. Comment `/reviewpad summarize` in a pull request.
4. Reviewpad will automatically generate a summary of the pull request and add it as a comment in the pull request thread.

![Reviewpad Summarize Comment Prompt](/posts/images/ReviewpadSummarizePrompt.png)
Source: <LinkExternal text="gitpod-io/gitpod: [dashboard] handle context resolution errors #17159" href="https://github.com/gitpod-io/gitpod/pull/17159#issuecomment-1505048273" />

### Using `Reviewpad Summarize` via `reviewpad.yml` file

#### Step 1. Add the following workflow to the `reviewpad.yml` congiguration file

```yaml
workflows:
  # This workflow calls Reviewpad AI agent to summarize the pull request.
  - name: summarize
    # Summarize the pull requests when they are opened or updated.
    if: $eventType() == "opened" || $eventType() == "synchronize"
    then: $summarize()
```

#### Step 2. `Reviewpad Summarize` will now run on every Pull Request
When a new pull request is created or updated, Reviewpad will automatically generate a summary and add it as a comment in the pull request thread.

![Reviewpad Summarize Workflow](/posts/images/ReviewpadSummarizeWorkflowResult.png)
Source: <LinkExternal text="pokt-network/pocket: Adding transactions via transaction indexer #660" href="https://github.com/pokt-network/pocket/pull/660#issuecomment-1502239330" />

This workflow is included in the default `reviewpad.yml` proposed after installing Reviewpad. <LinkExternal text="You can check it here" href="https://docs.reviewpad.com/" />.

Check the `Reviewpad Summarize` documentation <LinkExternal text="here" href="https://docs.reviewpad.com/guides/built-ins/#summarize" />.

## Benefits

Now that you know how to use `Reviewpad Summarize`, let's look at the benefits it offers:

* **Quick Reviews, More Time**: Complete your pull requests more quickly so that you can dedicate the additional time to other essential tasks.

* **Easy-to-See Changes**: Summarize code changes easily and clearly, helping you to understand the pull request at a glance.

* **Great Teamwork**: Picture your developer team working together smoothly, sharing ideas, and celebrating their success.

* **Better Code Quality**: Catch problems early, improve code, and make customers happy – that's the goal!

## `Reviewpad Summarize` vs GitHub Co-pilot for PRs

Finally, what sets `Reviewpad Summarize` apart from GitHub Co-pilot for PRs?

1. **Immediate Access** : Start using `Reviewpad Summarize` without any waitlist constraints.
2. **Innovative Approach:** Our distinctive summarization method offers enhanced results, as we found that combining multiple summaries generates a more comprehensive overview.
3. **Real-time Updates:** In contrast to GitHub Co-pilot for PRs, `Reviewpad Summarize` continuously updates summaries with new push information and even emphasizes changes made since the previous push (e.g. <LinkExternal text="https://github.com/reviewpad/reviewpad/pull/810#issuecomment-1493041723" href="https://github.com/reviewpad/reviewpad/pull/810#issuecomment-1493041723" />.)
![Reviewpad Summarize Workflow Update](/posts/images/ReviewpadSummarizeWorkflowDynamic.png)
Source: <LinkExternal text="gitpod-io/gitpod: feat: popular collections #5654" href="https://github.com/kodadot/nft-gallery/pull/5654#issuecomment-1507070857" />

## Wait, there's more!

`Reviewpad Summarize` also works on GitHub Issues.
Just add the following code to the `workflows` section of `reviewpad.yml`:

```yaml
  # Runs Reviewpad Summarize on open GitHub Issues
  - name: summarize-issue
    on:
      - issue
    # Summarize the issue when it is opened.
    if: $eventType() == "opened"
    then: $summarize()
```

&nbsp;  
So, there you have it - `Reviewpad Summarize` is here to revolutionize your code review experience.

We hope that by providing an easy-to-use code review tool, we can help you collaborate more efficiently, catch issues early, and make code review a more positive experience.

Happy coding!


_Optimize your code review process with Reviewpad’s auto-merge feature. Focus on other vital things rather than waiting for merge requests to be accepted._

## The Problem

Pull requests (PRs) are essential to the development process. They allow multiple people to collaborate and review code changes before they are merged into the target branch. However, this review process can take time and slow down the development cycle.

To speed things up, some organizations have turned to auto-merge. This article will look into a common use case for auto-merge. It automates the merge action after obtaining the approvals from specific users or teams that are required to merge a pull request. This can be extremely useful for changes to code that is not critical.

## The Solution

Auto-merge triggers the merge process automatically as soon as the required approvals are received; bypassing manual merge and saving precious time. **GitHub does not offer the ability to do this automatically**.

To configure auto-merge on required approvals, we can use tools like Reviewpad.

In this case, we will configure Reviewpad to verify if a pull request has at least a specified number of approvals from a specific team. To better understand how auto-merge works, we will now look into a step-by-step guide for a use case of Reviewpad’s Auto-Merge feature.

### Implementation

It is important to see a use case of auto-merge, so you can leverage this feature to its full potential to make the review process and the development cycle faster than before.

**Consider a software development team working on a large-scale project with multiple branches and many developers**. Here's how auto-merge can be used in this scenario:

- **Code review and approval**: All pull requests must undergo a thorough code review by designated team members to ensure that the changes align with the project's coding standards and do not introduce any bugs or errors. Usually this means that after the necessary reviews and approvals pull requests will sit still until someone reacts to a notification, or browses GitHub, and merges the pull request. Auto-merge can skip entirely this waiting time and merge the pull request as soon as the required reviews and approvals are in.
- **Continuous Integration and Continuous Deployment (CI/CD)**: The team uses a CI/CD pipeline to automate the build, test, and deployment process. Auto-merge can be integrated into the pipeline to ensure that approved pull requests are automatically merged into the main code repository.
- **Branches and merge policies**: The team has multiple branches, such as development, staging, and production. To ensure that only stable and tested code is merged into each branch, the team has established a set of merge policies. Auto-merge can enforce these policies and ensure that only approved changes are merged into the appropriate branch.

In this tutorial, we will learn how a code review and approval process can be implemented with auto-merge using Reviewpad. As an example, we will consider a **hypothetical organization that requires at least two approvals from a core team before merging critical changes into the codebase**.

We will now create a workflow that checks if the Pull Request has critical code and is approved by two approvers before being merged automatically. This practice helps to reduce the risk of unintended consequences and ensures that multiple individuals thoroughly review important changes.

#### Configure the Reviewpad workflow for auto-merge.

Add a Reviewpad workflow for the auto-merge feature, based on the use case discussed earlier, to the `reviewpad.yml` file.

```yaml
workflows:
  - name: auto-merge-on-required-approvals
    description: Automerge after required approvals if no changes were made critical code
    always-run: true
    if:
      - '!$hasAnnotation("critical") && $hasRequiredApprovals(2, $team("core"))'
    then:
      - $merge()
```

This workflow then verifies if the pull request doesn't have changes to critical code, and if it has at least two approvals from the core team with the check `$hasRequiredApprovals(2, $team("core"))`. If these conditions are met, Reviewpad automatically merges the pull request.

Now you can identify pieces of code that are critical to the project by adding the `@reviewpad-an: critical` annotation, so when changes are proposed to critical code, the `auto-merge-on-required-approvals` workflow is not triggered.

### The Result

Once a pull request is made, the `auto-merge-on-required-approvals` workflow is triggered.

![Pull Request checks](/posts/images/expediting-merge-with-auto-merge-1.png)

As soon as the checks are passed by Reviewpad and the required approval is received the staging branch is merged into the main branch of the repository as seen below.

![GitHub message "Pull Request successfuly merged and closed"](/posts/images/expediting-merge-with-auto-merge-2.png)

To learn more about Reviewpad, you can <LinkExternal text="check out our documentation" href="https://docs.reviewpad.com/" />.

## Final Thoughts

Auto-merge on required approvals is a powerful feature for streamlining the pull request review process. Organizations can save time and resources by automating the merge process based on specific conditions and speeding up their development cycle. Reviewpad allows developers to focus on coding while Reviewpad merges approved pull requests. As such, it should be considered as an essential part of any organization’s development toolkit when conducting code reviews.


_For the last few months, it was possible to use Reviewpad as a GitHub Action or a GitHub App.
In this post, we share our main lessons from maintaining both products and why we decided to fully focus on Reviewpad as a service through a GitHub app._

At the moment, it is possible to run Reviewpad as a GitHub action and a GitHub app. 

Today, we are announced that the Reviewpad core team will stop updating the Reviewpad action.

If you are wondering why we are doing this and our solution, read on!

### The problems with Reviewpad GitHub action

Running Reviewpad as a GitHub action has some advantages for users:
1. Control exactly on which events Reviewpad is triggered;
2. Control the execution environment; Reviewpad is deployed as a docker image.

However, it has some serious disadvantages:
1. For many Reviewpad users latency is super important. By running as a GitHub action with Github's runners, you can't really control when the action will be executed. You can't control the timing of the execution: it could be \<10 seconds or \>1 minute - this means that Reviewpad can't be used reliably to merge PRs on certain events or react to completion of other checks. Perhaps more seriously, we also have found that the stability of GitHub actions in the past year to be really shaky - check the number of incidents with GitHub actions in the [past year](https://www.githubstatus.com).
2. Reviewpad's features require it to react to multiple events. This creates a high burden on users to understand how to configure the GitHub action to be able react to the appropriate events.
3. Billing is starting to be a concern to some users - most users are running Reviewpad ~10x per pull request. On a team with 50+ developers, the GitHub action minutes are eaten up fast. 
4. On the subject of money, GitHub hasn't yet figure out a way to partner with providers of GitHub actions in terms of monetization - we believe it is not fair to work to increase GitHub's revenue without receiving any monetary benefit.
5. We are actively adding new features to Reviewpad that require permanent state. At the moment, the GitHub action is stateless - we can provide ways for users to connect to their DB or through our API but upon analyzing the burden to the user in terms of configuration found it to be unjustifiable.

### Our solution: Reviewpad service as a GitHub app
 
For the past few months, we have found that moving to a service via the GitHub app solves all these problems:
1. The GitHub app reacts to webhooks and with parallelism at the PR level, Reviewpad typically starts within 250ms.
2. Reviewpad's service only requires the Reviewpad configuration file and users do not have to worry about the interplay between events and Reviewpad executions.
3. As a GitHub app, you will not have to pay anything else to GitHub.
4. We have a [flexible pricing model](/pricing) and are willing to discuss particular conditions on a per case basis.
5. From an engineering perspective, we can focus on providing high-value features to users without major constraints.

For a while now, the core team has been both supporting the GitHub action and the app but that was not sustainable:
1. To do an excellent job in releasing both the action and the app, we need to test for each feature the behaviour in the action and the app. That takes time and focus away from providing value to users.
2. The [documentation](https://docs.reviewpad.com/) was becoming confusing because some built-ins can't properly work in the action.

### Information to current users of the GitHub action

At the core of our mission is an ecosystem to provide the best developer experience when it comes pull requests.

For current users of the action, we will keep providing support on the action. The action is pointing to a Docker image which we will continue to host on Docker Hub for the unforseeable future.
However, at this stage we do not plan to release bug fixes and actively recommend that you migrate to the Reviewpad GitHub App.

This migration only involves two steps:
1. Install app;
2. Remove the Reviewpad action workflow file.

The GitHub app is compatible with the action and will pick up the Reviewpad configuration file at the root of the repository.

We will work with current users of the GitHub action to ensure that any gaps in functionality between the action and the app will be closed so that they can continue to benefit from Reviewpad.

To address any security concerns about the service, Reviewpad's core will not only continue to be open-source but we have started the process to obtain SOC 2 attestation for the entire service.

Feel free to drop your comment in this dedicated [GitHub discussion](https://github.com/reviewpad/reviewpad/discussions/748).

*The Reviewpad Team*


_Streamline your code reviews with Reviewpad. Our advanced algorithm suggests the best reviewers for your pull requests, making your workflow faster and more efficient._

Are you tired of manually assigning reviewers to pull requests on GitHub? Do you find it time-consuming and difficult to ensure that each pull request is assigned to the most appropriate reviewer? If so, Reviewpad has the solution for you. With its new Code Reviewer Assignment feature, Reviewpad can help you streamline your code review process and ensure that each pull request is assigned to the right reviewer.

## The Problem with Manual PR Reviewer Assignments

For teams working on GitHub, the manual assignment of reviewers to pull requests can be a time-consuming and error-prone process. As development teams grow in size, the need for an automated review assignment mechanism becomes increasingly critical. Without such a mechanism, developers must spend valuable time manually selecting the most relevant and available reviewers for each pull request. This process can take critical time away from development tasks, slow down the review process, and lead to bias in the selection of reviewers.

In addition, it can be challenging to ensure that reviewers have the necessary expertise to review the code in the pull request. This can result in longer review cycles, errors in the code, and delays in the development process.

## Reviewpad's Innovative Solution for Effortless Reviews

Reviewpad's Code Author Reviewer Assignment Mechanism aims to solve these problems by automating the assignment of reviewers to pull requests. Reviewpad analyzes the past contribution history of code authors and uses that data to suggest the most appropriate reviewers for each pull request.

In this process, **Reviewpad considers two factors when assigning a reviewer**. Those are

- **Relevancy** and
- **Availability**

of the reviewers.

The relevancy evaluation is based on the authorship of the code. It analyzes how many lines of code have been written by possible reviewers in the latest version of the impacted source files.

The availability evaluation is based on the number of open reviews per reviewer, which ensures that reviewers with too many open reviews are considered unavailable.

If there are no reviewers available or identified by the algorithm, a random user within the organization will be assigned as the reviewer for the PR. This fallback mechanism ensures that the pull request does not remain unreviewed and that the code changes are still scrutinized by someone in the organization.

## The Crucial Role of assignCodeAuthorReviewers Function

Reviewpad's Code Author Reviewer Assignment Mechanism is powered by the `assignCodeAuthorReviewers` function, a built-in function that takes several parameters to determine the most relevant and available reviewers for each pull request.

This function is critical as it allows teams to customize the review assignment process to fit their specific needs.

### Understanding the Parameters of assignCodeAuthorReviewers

The `assignCodeAuthorReviewers()` function takes three parameters.

1. `Total` (Optional): This parameter specifies the total number of reviewers to assign to a pull request. The default value is one, but you can change it to assign more than one reviewer to a pull request.
2. `Excluded Reviewers` (Optional): This parameter is a list of reviewers to exclude from being assigned to a pull request. You can use this parameter to exclude specific reviewers who might not be appropriate for the review.
3. `Max Reviews` (Optional): This parameter specifies the maximum number of open reviews per reviewer. If a reviewer has more open reviews than this value, they will be considered unavailable and will not be assigned to the pull request. If we don't specify a value to Max Reviews, the algorithm ignores that parameter and considers reviewers regardless of the number of open reviews they have.

### Examples of assignCodeAuthorReviewers at Work

Let's look at an example of how you can use the `assignCodeAuthorReviewers` function in Reviewpad.

#### Example 1
```yaml
$assignCodeAuthorReviewers()
```

This example uses the default parameters for the `assignCodeAuthorReviewers` function. It will assign one reviewer to the pull request based on code authorship and availability.

#### Example 2
```yaml
$assignCodeAuthorReviewers(3)
```

This example assigns three reviewers to the pull request based on code authorship and availability.

#### Example 3
```yaml
$assignCodeAuthorReviewers(2, ["user1", "user2"])
```

This example assigns two reviewers to the pull request, but it excludes `"user1"` and `"user2"` from being assigned as reviewers.

#### Example 4
```yaml
$assignCodeAuthorReviewers(1, [], 2)
```

This example assigns one reviewer to the pull request, but it limits the number of open reviews per reviewer to two.

## A Step-by-Step Guide to Using Reviewpad's Code Author Reviewer Assignment Feature

Now that you have a better understanding of the `assignCodeAuthorReviewers` function, let's take a look at the steps of the workflow of the Reviewpad's Code Reviewer Assignment Mechanism.

**Step 1**: Sign up for Reviewpad and integrate it with your GitHub account. ([Installation Guide ↗︎](https://docs.reviewpad.com/))

**Step 2**: In your repository, create a new workflow with the following code:


```yaml
workflows:
  - name: Code Author Reviewer Assignment
    if:
      - '!$isDraft()'
    then:
      - $assignCodeAuthorReviewers()
```

**Step 3**: Customize the `assignCodeAuthorReviewers` function to fit your specific needs. You can use the parameters and variables mentioned earlier in this article to customize the review assignment process.

**Step 4**: Create a draft pull request in your repository.

**Step 5**: When the pull request is ready for review, move it to the `Ready for Review` status.

**Step 6**: Reviewpad's Code Author Reviewer Assignment Mechanism will analyze the relevancy and the availability of the reviewers and suggest the most appropriate reviewers for the pull request.

## Discovering the Advanced Functionality of Reviewpad

It's important to note that Reviewpad's Code Author Reviewer Assignment Mechanism is a powerful tool that can help you streamline your code review process. However, it's not a replacement for good code review practices. It's still important to ensure that reviewers have the necessary expertise to review the code in the pull request and to maintain a clear and organized review process.

In addition, Reviewpad provides other powerful features such as [automated pull request labeling](https://reviewpad.com/code-review-automation?category=put+labels), [automatic pull request merge](https://reviewpad.com/code-review-automation?category=merge+pull+request), and [enforcing branch conventions](https://reviewpad.com/code-review-automation?category=comment+pull+request&category=block+merge). By using Reviewpad's Code Reviewer Assignment feature in combination with these other features, you can create a robust and efficient code review process that saves time and reduces errors.


_Exciting News! We're proud to announce the next rockstar member of our team._

We're shaking up the software development world and bringing a fresh perspective to code collaboration, and we're thrilled to announce that Freddy Mallet, former Co-founder of SonarSource, is joining our team as Chief Product Officer!

With over 15 years of experience in software engineering, product management, and entrepreneurship, Freddy brings a wealth of knowledge and expertise to our team. He'll be leading our product strategy and vision as we revolutionize the code review process for software development teams.
At Reviewpad, we're taking code collaboration to the next level. We're automating manual tasks, freeing up developers' time and energy to focus on more meaningful tasks. We're taking a fresh approach to code reviews and code collaboration, delivering a game-changing solution that will simplify the lives of software developers and make a real difference in the industry.

"_I am thrilled to be operationally joining Reviewpad at this major milestone for the company. The Reviewpad service was launched at the end of 2022. All the foundations are today in place for Reviewpad to deeply impact the way we collaborate around Pull Requests_," said Freddy Mallet. "_The software development landscape is constantly evolving, and I believe that Reviewpad has the potential to completely transform the way developers work and collaborate. I am looking forward to working closely with Marcelo, Adriano, and the team to bring this vision to reality and deliver a solution that will make a real difference to software development teams around the world._"

We're ready to disrupt how developers collaborate with pull requests. Stay tuned for updates as we revolutionize the industry and bring a new era of efficiency and collaboration to software development teams everywhere.


_Pull Requests have become the backbone of the DevOps movement: the faster, the safer, the better. But the code review step, this systematic and synchronized communication task between humans, inherited from ancient times, slows down the overall development lifecycle for an illusion of safety. It’s time to introduce the Fluid Pull Requests paradigm._

Back in 2008, GitHub introduced the concept of Pull Request and, by doing so, significantly eased the contribution to **open-source** projects. For the first time, it had never been so simple for two strangers to collaborate on the same code base. At that time, the only purpose of a Pull Request was to provide a safe way to suggest code changes and discuss them in a collaborative interface. 

More than a decade later, **170 Million** [1] Pull Requests are created each year on **private projects** and 30 Million on public projects. So the concept has been embraced by the overall software industry and has become a de facto standard. During the same period, the **DevOps** movement took off, and nowadays, Pull Requests are the **backbone** of any automated SDLC (Software Delivery LifeCycle). On each Pull Request, many highly valuable tasks are fully automated: building, testing, static analysis to spot bugs, deployment on staging environments, etc. All this DevOps movement could be summarized in one mantra: **“The faster, the safer, the better”**. Starting in 2015, the DORA (DevOps Research and Assessment) [2] team has identified four key metrics that indicate the performance of a software development team. Three of those four metrics illustrate this mantra: Deployment Frequency, Lead Time for Changes, and Time to Restore Service.

So today, the lifecycle of a Pull Request should be a matter of a few hours, but it is always a few days or even a few weeks. Developers managed to automate many things, but we still have in the middle of each PR lifecycle a systematic and **synchronized communication task between humans**: the code review step. This inflexible code review step, inherited from 2008, slows down everything and is the main bottleneck.

Why do we keep on accepting to pay such a price? Why do we keep on pushing the stop-the-line button on each PR? Because no software, no static analyzer, nor AI will ever be able to formally prove that a code change is safe and maintainable. Our tooling will keep evolving to spot more patterns but proving the absence of problems is an unsolvable challenge. So we rely on humans to do so. But humans are even less efficient at spotting problems, tracking a flow of execution, or keeping more than 10 variables in our working memory. This is especially true when each PR has to be reviewed. Developers are progressively desensitized, and LGTM symptoms arise. We’re just accepting to pay the price for an **illusion of safety**.

So what do we suggest doing? As we said, Pull Requests are nowadays the backbone of the DevOps infrastructure, so we can’t work without them. Moreover, today there is no code analyzer to prove the absence of bugs or vulnerabilities, or critical design flaws, so we still need developers to review some code changes. The only problem is that this code review is done systematically, regardless of the context, and always involves synchronous communication between humans. Here is where the Fluid Pull Requests paradigm knocks on the door.

At the core of this Fluid Pull Requests paradigm is the capacity to adjust the code review process based on the **sensitivity of the code change**, either to **lighten or strengthen it**. This sensitivity evaluation must take into account several different elements. We can mention, for instance, the seniority of the developer on a code base, the complexity of the code change, or the history of changes. Based on this sensitivity evaluation, you can specify and automate **several code review processes** to automatically approve and merge, do an asynchronous review, assign several reviewers, and spot the most sensitive parts of the code changes. For instance, if a database migration script is added, it could be relevant to involve the database team, but only to approve this piece of code.

I guess you got it: Fluid Pull Requests is an extension of the Pull Request concept, to increase both the throughput and safety of delivery. We still rely on human review, but only when it’s the most relevant, and in a very driven way. **Instead of reviewing everything every time, we only have the most critical changes reviewed by the most impactful reviewers**.

### References

[1] Octoverse Report 2022: [https://octoverse.github.com/writing-code-faster](https://octoverse.github.com/)

[2] DevOps Research and Assessment: [https://www.devops-research.com/research.html](https://www.devops-research.com/research.html)


_This guide shows how you can set up GitHub workflow templates to automate common GitHub pull requests workflows!_

## The Problem

Every time a new repository is created in our GitHub organization, we need to ensure that it starts with a set of common pull request automations.

In the past, this meant that we needed to install multiple GitHub actions.

We were copying the GitHub action YML configurations from other repositories and then customizing it for the newly created repository.

This process was fine but it is error-prone and not very scalable because we need to maintain and customize multiple GitHub actions. 

## The Solution

Many GitHub repositories already use the `.github` folder to host workflows and templates for pull requests. 

GitHub provides the ability to share the files across all the repositories in an organization in the special `.github` repository.

This means that we can create a `.github` repository in our organization and then add the GitHub actions that we want to share across all the repositories.

GitHub calls these [starter workflows](https://docs.github.com/en/actions/using-workflows/creating-starter-workflows-for-your-organization).
A starter workflow could be used to easily add workflows to the newly created projects. 

This solves our problem of copying YML configurations between repositories but we need to create one starter workflow for each pull request automation.

So, we've decided to use [Reviewpad](https://reviewpad.com?utm_source=blog&utm_medium=organic&utm_campaign=automate_pull_request&utm_term=reviewpad) as a single source of truth for all the pull request automations.

This way, any repository can get these automations with a couple of clicks.

## The Setup

We will use Reviewpad to show case starter workflows.

To do that, we will need two steps:

1. Add the Reviewpad configuration with the specification of the automations
2. Add the Reviewpad starter workflow to the `.github` repository.

### Step 1. Specify the pull request automations in Reviewpad

We started with the following list of automations and checks:

1. Label pull requests based on their size
2. Check that the pull request commits come after one another (i.e. they have a linear history)
3. Check the commits messages against the [conventional commits specification](https://www.conventionalcommits.org/)
4. Check the pull request title against the [conventional commits specification](https://www.conventionalcommits.org/) (this makes sense because we squash and merge certain pull requests)
5. Warn pull requests that do not have an associated GitHub issue
6. Add a comment to pull requests if their description was empty
7. Greet users on their first pull request

These can be configured in Reviewpad in a few minutes. 

```yaml
api-version: reviewpad.com/v3.x

labels:
  small:
    color: "#294b69"
  medium:
    color: "#a8c3f7"
  large:
    color: "#8a2138"

workflows:
  - name: add-label-with-size
    always-run: true
    if:
      - rule: $size() <= 30
        extra-actions:
          - '$addLabel("small")'
      - rule: $size() > 30 && $size() <= 100
        extra-actions:
          - '$addLabel("medium")'
      - rule: $size() > 100
        extra-actions:
          - '$addLabel("large")'

  - name: lint-commits
    always-run: true
    if:
      - rule: '!$hasLinearHistory()'
        extra-actions:
          - '$warn($sprintf("The pull request it outdated with the base @%v", $base()))'
          - '$fail("Pull request is outdated")'
      - rule: 'true'
        extra-actions:
          - '$commitLint()'
          - '$titleLint()'

  - name: check-for-linked-issued
    always-run: true
    if:
      - '!$hasLinkedIssues()'
    then:
      - '$info("This pull request does not have a linked issue")'

  - name: first-time-contributor
    always-run: true
    if:
      - '$pullRequestCountBy($author(), "all") == 1'
    then:
      - '$commentOnce($sprintf("Welcome @%v! Thank you so much for your first pull request!", [$author()]))'

  - name: empty-description
    always-run: true
    if:
      - $description() == ""
    then:
      - '$warn("The description is empty. Please add more information!")'
      - '$fail("Empty description")'
```

Add this file to your organization `.github` repository so that it can be referenced later in the Reviewpad GitHub action.

For more information about the Reviewpad configuration, check our [documentation](https://docs.reviewpad.com/guides/syntax).


### Step 2. Add the Reviewpad starter workflow to the `.github` repository

The Reviewpad starter workflow is a GitHub action that will run Reviewpad on every pull request.

To add a starter workflow, you need to add two files to the `.github` repository under the folder `workflow-templates`.

The first file [reviewpad_action.yml](https://github.com/reviewpad/.github/blob/main/workflow-templates/reviewpad_action.yml) is the Reviewpad GitHub action that will be installed in the repositories.

```yml
name: Reviewpad

on: 
  pull_request_target:
    types:
      - opened
      - synchronize
      - edited

jobs:
  reviewpad_job:
    runs-on: ubuntu-latest
    name: Reviewpad
    steps:
      - name: Reviewpad
        uses: reviewpad/action@v3.x
        with:
          # Uses a default Reviewpad configuration file to get your started.
          # For customization and documentation, see https://github.com/reviewpad/action
          file_url: [URL-TO-REVIEWPAD-CONFIGURATION]
```

Note that you should update [file_url parameter](https://github.com/reviewpad/.github/blob/main/workflow-templates/reviewpad_action.yml#L21) to point to your organization configuration file.


The second file [reviewpad_action.properties.json](https://github.com/reviewpad/.github/blob/main/workflow-templates/reviewpad_action.properties.json) is the metadata file that specifies the starter workflow. 

```json
{
    "name": "Reviewpad Starter Workflow",
    "description": "Reviewpad starter workflow.",
    "iconName": "reviewpad-icon"
}
```

If you want to add the Reviewpad logo to the starter workflow, add the [icon](https://github.com/reviewpad/.github/blob/main/workflow-templates/reviewpad-icon.svg) to that folder.

## The Demo

<LoomVideo title="Demo" videoId="805542a1e20145419e4e563f61bdcc76"/>

&nbsp;  
If you liked this post, join our community on [Discord](https://reviewpad.com/discord) to keep learning new ways to save time in pull requests.

And, if you to get more features out of Reviewpad consider installing Reviewpad App.

PS: Support our project on [GitHub](https://github.com/reviewpad/reviewpad) with a star!


_For the old guard software developers, trunk-based development is the way to go. For younger developers, used to GitHub pull requests, it is unlikely that they know what trunk-based means. This article shows how we use automation to combine TBD principles with pull requests and get the best of both worlds._

Trunk-based development (TBD) is a software development methodology where the developers continuously merge changes into a single long-lived branch.

Two benefits of TBD stand out:

1. TBD avoids branches which save developers’s time from merge hell situations;
2. TBD fosters small atomic commits which are essential to build loosely-coupled systems where a developer has the ability to change one part of the system without impacting the rest.

For engineering leaders, TBD seems a no brainer and [Google’s State of DevOps Report](https://www.devops-research.com/research.html) has consistently associated TBD with a higher software delivery performance.

At the core, TBD fosters an high-trust and low-blame cultures which tend to have higher organizational performance.

However, one of the surprises of the [2022 State of DevOps Report](https://cloud.google.com/blog/products/devops-sre/dora-2022-accelerate-state-of-devops-report-now-out) is that trunk capabilities had a negative impact on software delivery performance.

### What changed?

According to the report, the number of respondents in the study with 16+ years of experience decrease from 40% to 13%.

**Developer experience is a key factor to implement and benefit from TBD practices.**

The report mentions that this difference is _likely due to the additional practices required to successfully implement Trunk-based development._ These additional practices can be resumed to a robust Continuous Integration (CI) mechanism that ensures that the trunk/main branch is never broken.

### A different perspective

Over the past years, we have also seen a decline of interest in TBD when we interviewed developers with less than 10 years of experience. However, we observed that the main reason is not related with the lack of a robust CI but with the adoption of git-based version control systems like GitHub, GitLab and Bitbucket.

These version control systems naturally force developers to use feature branches and asynchronous collaboration via pull requests. There are many junior developers that never heard of TBD.

We also found that teams that rely heavily on feature branches and pull requests typically have strong CI mechanisms to ensure that the pull request merge does not break the long lived branches. In fact, GitHub Actions or GitLab Pipelines simplify the process to quickly get a basic automated CI system up and running.

Pull requests as a git merge blocking mechanism is necessary in low-trust environments found in open source projects where you have contributions from untrusted parties.

Teams practicing TBD understand that it doesn’t make sense to generalize this reality to a team of software developers where high-trust, low-blame culture is key.

### The best of both worlds

We see pull requests as a useful mechanism to automate, document and audit three tasks:

1. Execute a set of automated tasks, e.g. build, tests, code analysis;
2. Code review;
3. Git merge approval.

We believe the adoption of pull requests will increase in the future for security reasons. For example, a [two-person reviewed](https://slsa.dev/spec/v0.1/requirements#two-person-reviewed) requirement must be fulfilled for a team to reach level 4 of the [Supply chain Levels for Software Artifacts](https://slsa.dev) standard.

We found that teams doing TBD find it hard to adopt pull requests because it creates a lot of friction in their processes.

**Reviewpad started from the observation that not every pull request is the same.**

This fits nicely for teams updating their TBD practices to use pull requests.

For example, a pull request that introduces a database migration is very different from a pull request that performs a minor refactoring of the code. In the first case, it makes sense to have a more in-depth code review and testing procedures to ensure the correctness of the migration.

At the moment, you can enforce pull request workflows to deal with this separation of concerns using the GitHub Reviewpad App.

To get Reviewpad in your repository you just need two steps:

1. Install the Reviewpad GitHub App;
2. Add the `reviewpad.yml` file that specifies the pull request rules and automation workflows. This file is read by the action to understand which actions to perform.

If you install the GitHub app in a single repository, Reviewpad will automatically open a pull request with a starter configuration with checks and automations for pull request best practices.

The pull request workflows are specified in YAML. Reviewpad uses a domain specific language (DSL) to quickly access contextual information in the pull request and perform actions.

Consider the following configuration:

```yaml
workflows:
  - name: label-pull-request-with-size
    run:
      - if: '$size() <= 50'
        then: '$addLabel("small")'
        else:
         - if: '$size() <= 150'
           then: '$addLabel("medium")'
           else: '$addLabel("large")'
```

It specifies a Reviewpad workflow to automatically add a label to the pull request based on the size of changes (measured in the number of lines added and deleted).

We currently have over [65 built-ins](https://reviewpad.com/code-review-automation?utm_source=blog&utm_medium=organic&utm_campaign=modern-truck-based-developement&utm_term=65-built-ins) that allow you to manage labels, comments, reviews and merge pull requests.

### Reviewpad’s trunk-based development

Based on TBD practices, we use Reviewpad to auto-merge pull requests in our main open-source repository [reviewpad/reviewpad](https://www.github.com/reviewpad/reviewpad).

For us, the first step was to define which scenarios it makes sense to auto-merge pull requests.

Since the repository is public, we need to restrict auto-merges to pull requests authored by owners of the project.

Additionally, to enable this auto-merge feature, the pull requests should be directly flagged by the owners as `Ship` pull requests. The only requirement was that this flag mechanism should be automatic when opening the pull request.

Finally, we established two criteria for auto-merges `Ship` pull requests opened by owners:

1. Changes to Markdown files should be automatically merged; additionally, such pull requests shouldn't waste resources such as running the CI process;
2. Other changes should be automatically merged if the CI process is successful.

Regardless of the author of the changes, we also wanted to avoid running the CI process unnecessarily. So, pull requests that only modify Markdown files should not trigger the CI process.

### The implementation

In this section, we show how we get Reviewpad to automate the merges.

The first step was to find a flexible mechanism for developers to open a pull request and flag them as `Ship`. We heavily rely on the [GitHub CLI](https://cli.github.com/) to open pull requests and we open them as fast as possible.

So we decided to use pull request templates to allow developers to select which approval/merge mode they want. This is part of our organization [pull request template](https://raw.githubusercontent.com/reviewpad/.github/main/.github/PULL_REQUEST_TEMPLATE.md):

```markdown
## Description

... for the entire file, please follow the link above :)

## Code review and merge strategy (ship/show/ask) 

 
 

```

In the final section of the template, authors of pull request select this mode.

As soon as the pull request is opened, the developer shouldn't have to do anything else.

You can check more prebuilt policies [Here](https://reviewpad.com/automated-code-policies?utm_source=blog&utm_medium=organic&utm_campaign=modern-truck-based-developement&utm_term=here)

As soon as a pull request is created, the Reviewpad app will be triggered and reads the [configuration file](https://github.com/reviewpad/reviewpad/blob/main/reviewpad.yml).

We now highlight the relevant sections of the specification.

#### Check for ship pull requests authored by owners

The first step is to specify a rule that will be true if the pull request has been selected as `Ship` and is authored by an owner.

We start by defining, with the Reviewpad DSL, the group `owners` as the list of GitHub usernames `marcelosousa` and `ferreiratiago`.

```yaml
groups:
  - name: owners
    spec: '["marcelosousa", "ferreiratiago"]'
```

Then, we define a rule that checks if the pull request contains in the description the section of the `Ship` mode. For this we can use the Reviewpad built-ins `$contains` and `$description`.

```yaml
rules:
  ...
  - name: ship-mode
    spec: '$contains($description(), "[x] Ship:")'
```

We can use this rule to define the rule `ship-authored-by-owners` that checks if the pull request is both authored by an owner and was flagged with `Ship`.

```yaml
rules:
  ...
  - name: ship-authored-by-owners
    spec: '$rule("ship-mode") && $isElementOf($author(), $group("owners"))'
```

#### Check for pull requests that only modify Markdown files

The first auto-merge criteria is to auto-merge pull requests that only modify Markdown files.

To do this, we define a rule `changes-are-in-markdown` that checks if the files modified only contain `.md` extensions.

```yaml
rules:
  ...
  - name: changes-are-in-markdown
    spec: '$hasFileExtensions([".md"])'
```

Finally, we define the rule `ship-markdown-changes` that chains the previous rules and if true, should trigger the merge action.

```yaml
rules:
  ...
  - name: ship-markdown-changes
    spec: '$rule("ship-authored-by-owners") && $rule("changes-are-in-markdown")'
```

#### Check for pull requests that have successful CI

The other criteria for the auto-merge involves the following steps:

1. Trigger the CI action if the changes are sensitive;
2. Check if the CI action was successful.

For the first step, we conservatively trigger the CI process if the changes involve other file extensions. We define it by simply negating the result of the rule `changes-are-in-markdown`.

```yaml
rules:
  ...
  - name: changes-should-be-built
    spec: '!$rule("changes-are-in-markdown")'
```

We then combine this rule to define a Reviewpad workflow that adds a special label `run-build`.

```yaml
workflows:
  - name: add-label-for-build
    if:
      - rule: changes-should-be-built
    then:
      - '$addLabel("run-build")'
```

The event of adding this label triggers the CI run in [pull\_request\_build.yml](https://github.com/reviewpad/reviewpad/blob/main/.github/workflows/pull_request_build.yml) with a job called `pr-build`.

We leverage the fact that you can trigger GitHub Actions based on other GitHub Action workflows. This allows us to trigger Reviewpad once the build finishes.

Reviewpad comes out of the box with built-in functions that allow us to check the result of workflow jobs. So, we defined a rule `ci-is-green` that checks if the `pr-build` job succeded.

```yaml
rules:
  ...
  - name: ci-is-green
    spec: '$workflowStatus("pr-build") == "success"'
```

Finally, we can combine the rules to define the second auto-merge criteria:

```yaml
rules:
  ...
  - name: auto-merge-authored-by-owners-with-ship-and-green-ci
    spec: '$rule("ship-authored-by-owners") && $rule("ci-is-green")'
```

#### Auto-merge pull requests

Once we have the rules that define the auto-merge criteria of interest, we just need to use them in a workflow that will trigger the `$merge` built-in. This built-in receives the merge method - we decided to use `rebase` to preserve the commits in the pull request.

```yaml
workflows:
  ...
  - name: auto-merge-owner-pull-requests
    if:
      - rule: auto-merge-authored-by-owners-with-ship-and-green-ci
      - rule: ship-markdown-changes
    then:
      - '$merge("rebase")'
```

### See it in action

When an owner opens a `Ship` pull request, if the changes are only in Markdown files, the pull request will be automatically merged without wasting the resources to run the CI.

See the following [pull request](https://github.com/reviewpad/reviewpad/pull/388) for an example.

If the changes are in other file extensions, Reviewpad will add the `run-build` label and this label will trigger the CI. Once the CI job is completed, Reviewpad will run again and now validate the result of the CI.

This way we can automatically merge pull requests with the guarantee that the CI process was successful.

See the [pull request](https://github.com/reviewpad/reviewpad/pull/390) for an example.

That's it! This is how we ensure that some pull requests are systematically merged without manual code reviews with the guarantee that the CI process is green.

If you are curious to see the whole process in action, check out our [GitHub repository](https://github.com/reviewpad/reviewpad).

PS. Please give us feedback on [Discord](http://reviewpad.com/discord) and support our project on [GitHub](https://github.com/reviewpad/reviewpad) with a star!


___Humans tend to overcomplicate, and devs are no exception (on the contrary!). We were paying 99$ a month for a Readme subscription and feeling a lot of friction. Along comes an intern looking for project ideas, and we couldn't be happier.___

## The road to Readme

Like many other startups, Reviewpad started its documentation on Notion. We use and abuse Notion internally (❤️). It was logical to create a new workspace for the documentation and give it a custom domain with `super.so`. It was a no-brainer: cheap, quick, easy, and pretty.

Notion+Super.so lasted quite a while, until we started to iterate faster and had the need to serve documentation to several versions of Reviewpad. That's when you go for the big guns: Readme, Gitbook, and Docusaurus.

We discarded Docusaurus pretty fast because it had to be self-hosted, and it didn't have a GUI to compose new versions. Little did we know these were its main advantages.

We eventually decided to go with Readme. At 99$ a month, it's a hefty price for any startup. Readme was very kind to give us a 50% discount for 3 months which, together with the urge for a new documentation platform, somehow convinced us to go for it.

Readme was pretty nice: easy to set up, responsive support, nice UI, fast, and all the features that we needed were there. We were happy for a good while.

## The breaking point

Only after making serious usage of Readme, we found out the friction points. To highlight the main ones:

- No automatic import of documentation generated by us
- A (new) UI that was slow and broke down all the time with bigger than usual pages
- Poor link preview on social platforms
- A heavy $1.2k yearly burden

With time, it became harder and harder to make a business case for Readme: it was very expensive, it was the source of a lot of frustration, and we kept seeing a lot of dev tools using free and open source documentation tools that looked very good.

We put up with these pains for a while until our intern, Pedro, had a spare month at the end of his internship. We sent him on a quest to replace Readme.

## The quest to replace Readme

### Phase 1. Finding a substitute

The quest took one week, and Pedro will admit that he only needed a couple of days. That's because he went deep and was trying out as many documentation platforms as he could. When he saw the time running out he decided to have a deep look only at the two most used ones: [Material for MKdocs](https://squidfunk.github.io/mkdocs-material/) and [Docusaurus](https://docusaurus.io/).

### Phase 2. Testing

For two weeks Pedro set up and fine-tuned an instance of Docusaurus, as well as an instance of Material for MkDocs. That gave us plenty of time to try out the platforms and make sure there weren't any missing features or hidden red flags.

This period was essential to compare the two platforms and make our decision. Here's a quick comparison of the pros and cons:

<Table
  headers={["", "Docusaurus", "Material for MkDocs"]}
  data={[
    "<b>Pros</b> | Sleek UI<br/>Uses React for the UI (easy to extend capabilities)<br/>No paid features | Sleekier UI",
    "<b>Cons</b> | No search out of the box | Some features were paid",
  ]}
/>

We decided to go for Docusaurus, mainly because it's built with React which we are pretty comfortable with, making it easy to bend it in whichever way we need in the future. Also, maybe due to React, it was a bit snappier than MkDocs.

It's important to say that both platforms offered on-point documentation (surprise!), the installation and configuration process was stupidly simple using each platform's documentation with absolutely no need to find guides or tutorials anywhere else. 💪

### Phase 3. Importing, deploying, sharing

The last week was spent importing all the docs from Readme into Docusaurus, setting up the architecture to preview and deploy Docusaurus in GitHub (FREE!) infrastructure, and finally educating and documenting the whole process with the Reviewpad team.

**And that's how you save a company $1.2k a year in the last month of your internship.**

![](/posts/images/Screenshot-2022-09-15-at-11.54.55-1024x889.png)

[**docs.reviewpad.com ↗︎**](https://docs.reviewpad.com/)

## About Docusaurus

Docussaurs is:

> An optimized site generator in React. Docusaurus helps you to move fast and write content. Build documentation websites, blogs, marketing pages, and more.  
> &nbsp;  
> [docusaurus.io](https://docusaurus.io)

### Challenges

#### Architecture and deployment

This was the first challenge, and though it was not necessarily related to Docusaurus, it was one that we needed to sort out. It's not complicated either, with a few YAML lines of configuration you can [make Docussaurs build and deploy automatically to GitHub pages](https://docusaurus.io/docs/deployment).

#### Collaborating with other people

You have Docusaurus up and running on your machine and you're able to deploy the build to GitHub pages, but what if you want to show something to a colleague? Out of the box, the solution was to push the changes to GitHub and have a colleague check out the code to run Docusaurus on their side.

For this we use AWS Amplify Previews, which is triggered by any PR against the main branch, that automatically spins up a machine with the new version and posts a link in the PR. Super handy.

#### Search

There's no search out of the box because Docusaurus is a static website, however it has [support for several search engines](https://docusaurus.io/docs/search), the main ones being Algolia and Typesense:

- Algolia: best in class, paid but free for open-source
- Typesense: second best in class, free and open-source

Fun fact, Algolia used to be open-source, Typesense is a fork of Algolia before it went private.



Explain to your grandparents what GitHub Actions are in 5 minutes. This is a topic that is getting thrown around more and more with the rise of Pull Request Automation, we have found out that even software engineers don’t fully understand what they are, but here’s a quick fix.

## A Cooking Analogy

**Whenever we feel hungry, we go into the kitchen and use a recipe to cook.**

In this action, a series of things happened. The first one was the event that triggered us to go into the kitchen and cook a recipe - feel hungry. The second one was the decision of where to execute/run our recipe - the kitchen. And finally what steps to follow - the recipe.

All these decisions have been orchestrated by us and can be summarized in the action of **`Eat when hungry`** with the following characteristics:

- **Trigger event** - feel hungry
- **Execute on** - the kitchen
- **Execution steps** - the recipe

GitHub actions work like this, but for GitHub repositories.

## GitHub Actions

A GitHub Action is an automation (also called **workflow**), triggered by certain **events**, which will execute one or more **jobs**, on a specific machine (**runner**).

The core components are:

- **Event**: anything that happens inside the GitHub Repository. [The list is pretty extensive](https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows). It goes from when labels are created, pull requests opened, or even when an issue is commented. The action can also be scheduled.
- **Workflow**: a workflow is triggered by an event and it’s comprised of one or more jobs run in parallel (that can also have dependencies between them).
- **Jobs**: A job is a series of steps to be executed in order. Each step is either a shell script that will be executed or an action that will be run.
- **Runners**: A runner is a server that runs one job at a time.

![](/posts/images/1_pOLCkdCmXxr2XePU1nsrrw-1-1024x628.png)

[Github Actions— Everything You Need to Know to Get Started](https://towardsdatascience.com/github-actions-everything-you-need-to-know-to-get-started-537f1dffa0ed) , by Ahmed Besbes

Let’s analyse a GitHub Action example: **Run the linter on a pull request update in a deno project.**

```yaml
name: Deno

on:
  pull_request:

jobs:
  test:
    runs-on: ubuntu-latest

    steps:
      - name: Setup repo
        uses: actions/checkout@v3

      - name: Setup Deno
        # uses: denoland/setup-deno@v1
        uses: denoland/setup-deno@004814556e37c54a2f6e31384c9e18e983317366
        with:
          deno-version: v1.x

      - name: Run linter
        run: deno lint
```

- **Event**: Update a pull request
- **Jobs**:
    - Check out the repository
    - Setup Deno
    - Run the linter
- **Runner**: Linux machine

**Do you want to know more?** GitHub offers a pretty good documentation page on GitHub Action that’s actually pretty easy to understand. Check it out: [Understanding Github Actions ↗︎](https://docs.github.com/en/actions/learn-github-actions/understanding-github-actions).

But this is the subject of another For Dummies blog post.



One of the pleasures of working on a relatively unexplored area like code reviews is that there is still plenty of room to learn and improve. Devs from around the world do reviews and face the review process in very different ways.

We have recently published our views on what the best practices for code reviews should be (you can find the posts [here](https://reviewpad.com/blog/six-best-practices-to-improve-your-code-reviews/) and [here](https://reviewpad.com/blog/six-more-best-practices-to-improve-your-code-review/)). People seemed to enjoy these articles a lot, and take a lot from them, so we decided to do a little experiment. We took to Twitter, and we put a little hashtag out there, called [#CodeReviewTip](https://twitter.com/search?q=(%23CodeReviewTip)&src=typed_query&f=live), encouraging all developers to add their two cents to the discussion.

We learned a lot!

The discussions this generated were fantastic, and even some devs who thought they were 100% familiar with code reviews realised there’s still a lot to learn for all of us. So we decided we couldn’t let it go to waste.

We **collected** all the tips.

We **categorised** them.

We **made them open source**.

And they are:

[↗︎ Code Review Repository](https://github.com/reviewpad/code-review-tips)

We are looking to build a true repository of the best practices for all devs everywhere.

So now it’s up to you guys to help us make it all it can be! Your contributions are very welcome, your input is necessary, and we really want you to make it your own.

So please share the love, improve the status of code reviews, and happy coding!



_Sharing knowledge usually comes as the last step of a process, or even worse, as something optional, that can be passed on if need be. This makes it easy to skip on this step if you feel you’re tired, or your team is busy. Developers are almost always creating new technologies and figuring out new solutions. Odds are, whatever knowledge you acquire won’t be available anywhere else. The time has come to remind everyone of the fundamental benefits of making whatever knowledge you’ve acquired available to your colleagues._

## Why it helps you

Knowledge sharing is [the second biggest problem software companies face](https://codingsans.com/state-of-software-development-2020). It affects everyone, so it also affects anyone. With the advent of remote work, this issue may become even more important. First of all, let’s appeal to our own self-interest. Sharing knowledge doesn’t only help our team, it actually helps those who are imparting the knowledge in more ways than one.

Let’s see:

- You are **advancing your own knowledge**. By explaining what you’ve learnt to someone else, you are consolidating what you’ve learnt. You will retain it better, systematise it better, and, frankly, you’ll probably advance it by seeing it through others’ eyes. You will have to consider what you’re sharing and think twice about it. That reflection will bring with it valuable learning.
- You will be **receiving feedback**. No developer is an island. We learn from others. By sharing what you’ve learnt, you will be receiving other people’s thoughts on the subject, which will surely advance your own understanding. Maybe they will even correct some aspect of it that you misunderstood.
- You will **help future you**. If you learn something and just file it away in the caverns of a closed pull request, odds are you may not remember it fully whenever you bump into the same problem again. If you write it down, though, and teach it to others, it will be right there for you when you need it. It’s the easiest way to **only solve problems once**.
- You will be **advancing your career**. Sharing knowledge and contributing to the team’s success does not go unnoticed. If when people are in trouble and seek solutions your name pops up all the time, everyone will take notice. This is how promotions happen.

## Why it helps your team

But sharing isn’t just about oneself, now is it? There must be advantages for the whole team. Let’s see what they are.

- It helps **build team spirit**. This may sound like a meaningless phrase, but it isn’t. What goes around comes around, and a team that is accustomed to helping each other will resort to helping each other naturally. Giving everyone a hand shouldn’t be contingent on someone being in trouble.
- You will be **saving everyone A LOT of time**. How long did it take you to solve the problem? An hour? Two? A whole day? Whenever someone on your team runs into the exact same issue, they will (depending on skill level or just sheer instinct) take roughly the same amount of time. If there’s an explanation available, though, that everyone has knowledge of… Not so much.
- You will be **building a knowledge base**. It may seem like just a small addition, but small additions build up. If your team develops a culture of sharing knowledge, they will inevitably create a repository that will become a cornerstone of success.

## How to do it

So, are there any best practices, aside from simply gathering the team and telling them, or writing stuff down somewhere public, such as an internal Wiki?

We do have some ideas:

- If you’re using **Reviewpad**, which you should, the _Comments from the Past_ feature makes it so whenever someone touches code with comments, they'll be able to see what was shared when that code was made. Forget about re-working the same problems, or going down avenues that somebody else already found out that don't work.
- Whenever a team member explains something to you, **encourage them to document it**. If it was useful to you, it will likely be useful to others.
- Much in the same way, whenever someone asks you for help, **document it**.
- Whenever you are the one who needs an explanation, avoid asking in private. **Ask on a public forum**, so everyone can read the discussion and take advantage of it.
- Make it **easily accessible**. Your knowledge base needs to be freely and easily accessible to everyone, at all times. Developers don’t particularly like over complicated wikis, so it’s up to you to create this space.

One of the reasons why we are building Reviewpad is making knowledge sharing easier and more convenient to everyone involved.

Reviewpad is about communication as much as it is about reviews.

[Are you ready to give it a go?](https://www.reviewpad.com/get-started)



_We have discussed best practices and principles. Now is time to get to the task and start arguing about practicalities. If you are leading a team, and you need your code reviews to be better, more effective, and a more perfect tool for team-building, what can you_ **_actually do_**_?_

We have the answers.

## Define what the truth is

Does that title sound excessively ambitious? Is Reviewpad finally becoming political? No to both!

What we mean is that you need to produce **and maintain** a well-documented source of truth to keep every member of your team on the same page. Code reviews are essentially about co-ownership of the final product, and at their core they are a collaborative endeavor. If all members of the team (especially the more opinionated) don’t agree on some basic principles, this can undermine the whole deal.

Here’s what this document should contain (at least):

- **A clear-cut definition of the team’s priorities**. What do you do in special/urgent cases? Can you skip tests when the team is in a hurry or not? Should code reviews supersede other work when the deadlines are getting close? What constitutes “a hurry”? What qualifies as “getting close”? Etc.
- **Establish a pull request description template**. And make sure people use it.
- **Establish a code review checklist**. And make sure more experienced developers, who probably won’t need a checklist, don’t fail to keep to its standards.

## Leverage automation

Code reviews are an engaging, interesting, personal experience. They are not an afternoon spent nitpicking for teeny bugs that a linter can easily find.

[We have written an article](https://reviewpad.com/blog/automation-in-code-reviews-dos-and-donts/) where we detail where and when automation is a must-have, and also some of our thoughts about when you can’t rely on it. We recommend going through it, but the bottom line is simple: figure out what kinds of work a machine can do better than you, and let it. Linters, test coverage tools, etc. are great tools that you should use to your advantage.

## In regards to pull requests: tell your team to favour what’s easy

We tend to focus much of our attention on how to improve the review itself. We do, however, know very well that the quality of the review is heavily reliant on how sensible requests are.

Speak to your team, and create clear guidelines: make life easier for the reviewer.

Encourage pull requests of **manageable size** and **clear context**, both of which can be defined in the document mentioned earlier.

## Everyone reviews code

This one is self-explanatory, but it must be said: everyone needs to be doing reviews. There’s no advantage in overworking your most senior teammates (which happens too frequently), and there’s a lot to lose in terms of learning and improvement from keeping juniors from doing them.

Be sensible in how you assign code reviews, **of course**, but share the wealth!

## Ban LGTM

Avoid rubber stamp reviews as much as possible. Code reviews are a process of **continuous improvement**, and every bit of work you do should follow in this spirit. If there are in fact no mistakes, and the code is absolutely pristine, share this achievement with the rest of the team.

## Power to the people

Team spirit is fundamental. Co-ownership is key. One of the reasons why code reviews sometimes fail, and create rifts among teams, is that people are working towards their own views and goals about the sprint/product instead of agreeing on **collective goals**.

Let your team control the review process. Allow the establishment of goals to be a collective process, and have everyone commit to it. This will naturally lead to what should be encouraged (positive/constructive/actionable) comments, instead of what should be discouraged (negative/damaging/empty) ones.

To empower your team is to make them responsible.

## Get Reviewpad

We may be a little biased, but the fact is we are using Reviewpad to do our reviews while we build it. We have been doing it from really early on. 

[Try it out yourself](https://reviewpad.com/get-started/)!



_When you’re dealing with code reviews, and making them a cornerstone of the development process (_[_as you should_](https://reviewpad.com/blog/continuous-code-reviews-are-the-way-to-go/)_),_ [_best practices_](https://reviewpad.com/blog/six-best-practices-to-improve-your-code-reviews/) _matter. We will concede, however, that the best practices in this field aren’t yet set in stone. Perhaps they never will be. Reviewers are different, and we are always careful to encourage them to experiment and figure out what works best for them. Our goal at Reviewpad is to create the tools that will allow every reviewer to find their footing and engage with reviews in the way that works best for them. We do believe, however, that there are principles that are key. Today, we tell you about them._

## 1\. Be thorough

Some people will prefer to have a checklist. Others, more experienced, will rather not. This is up to you. Some will prefer to time their reviews. Others will prefer to set a hard-limit in terms of either time or lines of code to know when to stop. All of this is debatable, and you should figure out what works for you. What truly matters is that you do a **thorough** review. It’s unacceptable to review the first half of the code with care and then speed through the rest to meet some sort of arbitrary time-limit. If the time-limit is wrong, fix it. If the limit is necessary, then break up the review into smaller pieces.

Do not half-ass it.

## 2\. Make your feedback actionable

There are many styles of feedback, and it’s hard to tell you what better suits your team and the project you’re working on, but it’s very important to keep things **precise**. Kindness is key - personal issues should be kept away from your reviews. Feedback shouldn’t just be positive/negative, it should be **actionable**. What needs changing, and why. What doesn’t work, and why it matters. When leaving a comment, make sure whoever reads it understands what you think should happen next (NB: “fix it” doesn’t count).

## 3\. Make sure you understand every change

If you’re not sure what something does, don’t just let it go. Even if the author of the code is a more experienced developer and you trust them. Everyone makes mistakes, regardless of seniority, and it’s your job to catch them. You can’t do that if you don’t fully understand what the code does.

Is it too complicated?

No worries. Just ask for an explanation or a simplified version. Code should be readable, and making it so is an important part of code reviews. Don’t shy away from saying you don’t get something.

## 4\. Don’t approve code that isn’t ready

This one seems like something that shouldn’t need to be said, yet it does. Developers will often approve code that doesn’t have obvious mistakes but could… you know… maybe… be improved…?

If you feel like the code isn’t ready to **ship to the client**, then you shouldn’t approve it. Of course, some exceptions apply, if you are in a crunch and a new feature needs to be tested, etc. but as a general rule? Only approve code that works.

## 5\. Always raise standards

Are you keeping to your team’s standards? Do they follow a checklist that you aren’t keeping to? How about documenting the code? Making sure everything has the required test coverage? Respecting the same coding conventions?

You are? Brilliant! **Time to raise those standards**.

We believe in continuous improvement, and that’s one of the keys of code reviews. Don’t ever find a comfort zone. If you feel like you are just coasting with your reviews, then odds are you will probably start making mistakes out of complacency. Don’t allow that to happen.

## 6\. Assume nothing

Senior devs make mistakes. Junior devs create wonderful code. So why would you not be every bit as attentive while reviewing a senior’s code? Why would you expect messy code from a junior? Never take anything for granted. Go into every review with a clear head and act like you had **no prior expectations**.

Make sure your comments also reflect this. Feedback in code reviews is no place to air out frustrations with someone who has made the same mistake three times. Leave actionable and precise feedback once again and figure out HR issues later.

## 7\. Be a team member!

Code reviews are the perfect place to set ego aside and ignore whether the code was written by your friend or the person you personally like the least on the team. They are the place to put aside your own preferences about what kind of code is “techie” or “fun”. They are the place to worry about one thing, and one thing only: the success of the project.

And the project belongs to no single individual. The whole team is working on it, and the whole team should feel like they own it. The goal is to create code that is as functional and maintainable as possible. Everything else doesn’t matter, whether they are pet peeves or history.

## 8\. Learn!

This one is the simplest of all.

Even if you are a rockstar developer, there’s a lot of knowledge being exchanged in code reviews. Even when doing them. Whenever you’re going through everyone else’s code, always be mindful of this. Maybe that mistake you were about to fix wasn’t a mistake at all.

Maybe it was just a different way of doing things. Maybe one that’s actually better.

Never stop learning.

Did you enjoy this article? We are building the tools to help people put all of these principles in practice by making code reviews as easy and painless as possible. [You can try it out for free right here](https://reviewpad.com/get-started/).



_João is a friend of Reviewpad and he asked us how we started the project._  
_Here’s the story in his words._

Adriano Martins and Marcelo Sousa, the two founders of Reviewpad, are old university buddies. They met at the University of Minho in 2006, two fresh-faced software engineering freshmen, and their friendship would endure. Fast-forward thirteen years to 2019 and you’ll find Adriano in Brussels, working at the European Parliament, and Marcelo in Geneva, working at SonarSource.

They’re still in touch, however, and they want to work together. This is not news. They had discussed entrepreneurship in the past, but nothing was ever solid enough to materialise. This time, however, it feels different. Marcelo has been working on advanced security offerings, and he’s growing increasingly frustrated at code reviews. He understands their value, and how crucial they are. The software he’s building shouldn’t fail, so code quality is key. And yet, the review process feels like it hasn’t changed in years. Maybe decades.

> We didn’t just want to do it for no reason, though, we wanted to make developers’ lives better

“Marcelo was the one who came up with the idea because he realised there was a sizable unexplored market there. We’ve discussed working together a lot, we were always looking for a project. We didn’t just want to do it for no reason, though, we wanted to make developers’ lives better. This is probably the most frustrating aspect of development right now” says Adriano.

## Four cities, one company

How do you organise a company when both founders and the people they want to invite to their team are all in different places?

You go remote.

“When my girlfriend moved to Algarve, I was working in Porto. I wanted to be with her, so I came to an arrangement with the company I was working for at the time, which would allow me to split my time between the North and the South. We did this for a while, and then I moved to fully remote work. It worked out great.” says Tiago Ferreira. He was one of the two engineers that joined Adriano and Marcelo at the very beginning of the project. “I was working remotely already, so I didn’t really need to change anything in that regard.”

Xavier Vilaça, the fourth element of the original Reviewpad team, was in Lisbon.

The founding team knew they wanted to be fully remote from the beginning. No one was in the same place, and they weren’t interested in limiting their scope to the talent available in any given location.

“We always made it a point to do everything we could remotely. I had to travel to Portugal to sign a few papers, but that was pretty much it. Getting a business started has its bureaucratic challenges, but we did most of it by phone, mail, or email.” The accountant, the bank, the lawyers. Most of the people that helped set up Reviewpad never met anyone from the company in person.

## By November, work started in earnest

“The goal was to have a hybrid model. We wanted to be able to operate remotely, but we also wanted to work together, meet, and socialise. It was never about having an office, but we did intend to get everyone in the same place for a week at a time, somewhere.” says Tiago. “Of course, that quickly became impossible.”

Work had been going on for three months when the lockdowns began. Everyone went back home. Gatherings and retreats were out of the question, and so was travel. The world was shut.

> We built a company for the pandemic unknowingly

“On the one hand, we built a company for the pandemic unknowingly” says Adriano. “The only practical thing in terms of our operations that changed was that we couldn’t do our meetings, which were always meant to be quite sporadic anyway. Our real concern was helping make sure everyone was handling it well on their side.”

With a fully remote company working in earnest, and every one of the company’s members relishing doing their job as a form of remaining focused and busy during a time when most activities were banned, the product grew.

“Initially, we were developing a sort of GitHub extension. We wanted to extend things to a tab within Github that provided extra info during reviews. We ended up doing a couple of iterations of this, but then we realised the concept wasn’t ideal. We could do better” says Tiago.

That meant bringing more people in.

## Hiring over the Internet
[![](/posts/images/born-to-be-remote-how-we-built-reviewpad-during-the-pandemic-tweet1.jpg)](https://twitter.com/codereviewpad/status/1364647727871762435)

“I didn’t expect much from the interns,” says Adriano. “I had interns in the past, and of course they did their jobs, but..” he says, visibly trying to find the kindest words possible. “I could’ve handled what they did myself with no problem. I always felt like internships were more valuable to the intern, who is learning a lot, than to whoever is training them.”

This wouldn’t be the case.

> It went incredibly well. Everyone who joined did fantastic work

“All the interns blew our minds,” says Adriano. “Hiring people over the Internet is a bit unnerving, and so is managing a team, because you can’t feel the room. You can’t tell if someone is excited in the same way. You can’t feel their frustration or discomfort either. And yet… It went incredibly well. Everyone who joined did fantastic work.”

One of Reviewpad’s [original two interns](https://reviewpad.com/blog/the-internship-of-a-lifetime/), Cheila, would go on to be hired by the company.

“I mean, look, she wrote code _in her first week_ that would go on to be in our product, that we shipped to customers. It’s unbelievable,” says Adriano.

The team was growing. The product was being built. And yet, the pandemic dragged on.

## Feeling the strain of lockdown

“I missed running the most, I think,” says Tiago. “I was already used to working remotely, you know? Not having that watercooler talk with your colleagues, those moments of in-person camaraderie. Sometimes it sucks, because you’re frustrated with work, and you can’t just go for a beer after. That I was used to. Not running? Being stuck at home? Not so much.”

Aside from Cheila, who made her way to the team via her internship, every single member of the Reviewpad team went to University together, including Rui Santos, who joined a little later than the original four. They were and are friends. The mental health of the team was a concern both for professional and personal reasons.

> These people are banking their future on our company

[![](/posts/images/born-to-be-remote-how-we-built-reviewpad-during-the-pandemic-tweet2.jpg)](https://twitter.com/codereviewpad/status/1372981846372315136)

“When you’re trying to get a startup going, you can’t offer your team the same conditions or security that a bigger company can. That’s inevitable. One of the things that can make the difference in hiring truly talented people is whether they can trust you,” says Adriano. “We contacted people we knew for fifteen years because they know us. They know we’re serious. There is no way a startup like ours could’ve gotten developers of this level of skill if they didn’t know how serious we were. With that, of course, comes great responsibility. These people are banking their future on our company.”

Reviewpad developed a number of digital social activities, and actively tried to think up ways of getting people to socialise in a non-work environment. All of this via computer screen. Games, such as [Gartic Phone](https://garticphone.com/), or [Jackbox Party](https://www.jackboxgames.com/) games, played a huge role, but also simply learning to switch off.

> We had to learn how to switch off. How to do small talk, discuss current events and the news. Act like we’re in an office

“Marcelo and I struggled a bit because we were trying to do too much. We thought… well, there’s work to be done, and it’s not like I’m going anywhere, so I might as well just work the whole weekend… and eat at my desk… and that’s not healthy. We had to learn how to switch off. How to do small talk, discuss current events and the news. Act like we’re in an office.”

“We were lucky because we already knew each other. We were so lucky,” says Tiago. “We gave each other breaks, in the most frustrating times, that we maybe wouldn’t have given people we didn’t know well. We were all scared, and managing this stress without the ability to just go out for a beer is awful. We’re all glad it’s over.”

## Opening up means meeting up

[![](/posts/images/born-to-be-remote-how-we-built-reviewpad-during-the-pandemic-tweet3.jpg)](https://twitter.com/codereviewpad/status/1413522069942329345)

As soon as sanitary conditions and government guidance allowed, Reviewpad emerged from its cocoon. In possession of a functioning prototype, and with a team that had withstood a truly grueling time in all our lives, the team met.

“It was truly delightful,” says Adriano. “We were so ready for that. To be together, bounce ideas off each other, laugh a little. The work we did in three days was what we would’ve done in like a month.”

The team hadn’t gathered for over five months. And yet, it all clicked.

“There’s a human element to working together. Working remotely is awesome, and it has a ton of advantages, but there’s something about just hanging out with your mates that can’t be replicated,” says Tiago.

Reviewpad is now operating as planned. The remote structure allowed them to work all the way through the pandemic with no hiccups. The reopening is now allowing for the meetups to strengthen the company’s core.

> Now I am genuinely excited

“When I first joined, I thought this was a good idea. I understood the potential. I wanted to be a part of it. But now? Now we have an actual product, and it works amazingly well. I am building Reviewpad using Reviewpad. We use our own product to do our code reviews, because it already is miles ahead of anything else out there. I was into it from the get go, but now I am genuinely excited,” finishes Tiago.

Do you want to know what he means by that?

You can.

All the hard work the team put in during the pandemic has translated into this. You can [try Reviewpad now](https://reviewpad.com/get-started/), for free.



_Best practices are_ [_one thing_](https://reviewpad.com/blog/six-best-practices-to-improve-your-code-reviews/) _that surely matters. Improving standards is always good. Who could argue against that? But what do you expect to get from code reviews? How do you expect the experience to go? Managing these expectations, especially when it’s often so hard to measure results, can be daunting. Here are some thoughts on how to manage this._

## Embrace the qualitative

Code reviews are about **continuous improvement**. That means it won’t always be easy (sometimes it will be impossible) to quantify how much you’ve improved. Any metric you can come up with to measure **return on investment (ROI)** is likely flawed, and will probably tell you as much about the quality of your other processes as the reviews themselves.

We do know some things, such as the skyrocketing costs of [catching bugs later](https://www.typemock.com/software-bugs-infographic), but the value of code reviews far exceeds that of simple debugging. The kinds of improvements code reviews achieve can sometimes only be felt years later, when an entirely different team is charged with updating the codebase and finding easily readable code.

Some things you just can’t measure. We need to accept this.

## Expect people will be reading you

This goes for several stages of the process. Sometimes developers will tend to forget that all their notes and comments will be read by a person that is also a teammate. A person with feelings, issues, and varying degrees of seniority and skill. Sometimes developers will tend to forget that their code will have to be read and understood by people over time.

This means you must be mindful of what you’re telling others, but also what you’re asking of them. A couple of examples:

- Massive pull requests will probably lead to shorter and more superficial comments. Is this what you want?
- Reviewers will need to place themselves. Have you provided the context that will allow them to fully understand what you’re going for?

Always keep in mind: if you’re typing it, expect someone will read it.

## People make mistakes

One of the hardest things to manage regarding code reviews is the frustration that comes from reviewing bad code. Lots of mistakes, bad choices in terms of style, and unreadable code.

This, however, is almost inevitable. You’re going to have to deal with bad code sometimes.

It’s important to not let that frustration boil over into aggressive or hurtful comments. Communication must always be geared towards improvement, both of the codebase and the team. Code reviews are a great way for everyone to learn from mistakes, but that depends on the kindness of the reviewers.

## Be mindful of people’s schedules

Full-time code reviewers are rare. And even if they weren’t, they would have a schedule anyway. Sometimes we expect our colleagues to pick up whatever is our priority as if it is also theirs, but that’s not how it works.

Code reviews are often treated by teams like an afterthought, something that can be done by anyone “as soon as they have a minute”. This is never the case, and reviewing is a task that should be treated with the same consideration as any other. Assign your reviews in due time, and expect people will be busy.

## Best practices matter

Your expectations of code reviews should always take into account how they are being done. Are you posting the pull requests to a public channel and expecting anyone to pick them up? Then you shouldn’t be surprised no one does, or if it takes them a long time to do so. Are you bundling up all the reviews and doing them at the end of the week? Then you should expect a lot of confusion. Are you reviewing for hours on end? Expect mistakes.

The full benefit of code reviews heavily depends on them being integrated into a continuous code-review-centric operational model, and the more your practices reflect this, the more you can expect from them.

## Code reviews are about your team

An underappreciated aspect of code reviews is how they are a collective endeavor. We believe in them as a form of fomenting co-ownership of the codebase, and always tell reviewers to not think of what they’re looking over as someone else’s work. It belongs to the whole team.

Code reviews, when done right, will expand the whole team’s knowledge of the product, and help everyone learn with both the mistakes and the skills of everyone else.

This is probably the most important thing you can expect from code reviews, if you make them work in that way: you can expect them to be not only a guarantor of your code’s quality, but also a true engine of team building.

What are your expectations for code reviews? Did we miss something important? Drop us a line on Twitter ([@codereviewpad](https://twitter.com/codereviewpad)) and let us know!



_Debate about code reviews is often dominated by debate about pull requests. The confusion between the two is so common we have made it a point to clarify that they are not the same quite often. So what are pull requests? And why are they called that way?_

Imagine you’re writing a book.

([You knew that was coming](https://reviewpad.com/blog/series-for-dummies/).) 

In this case, you’re writing collaboratively. Let’s say it’s a non-fiction book, or a technical manual. Something that requires a certain degree of responsibility and accuracy.

You will need to figure out a strategy to make sure there are as few mistakes as possible.

## How about… version control?

If this is a collaborative work, then it stands to reason that you will want to keep your file (let’s say a Word document) somewhere everyone can easily find it and work on it. Let’s say you keep your manuscript on Dropbox.

You (or any one of the other authors) are working on a specific chapter, so you download the manuscript that the team is keeping online. You would never edit the manuscript directly, that would be way too risky. You create a temporary version, and label it as such.

You do your work, write your lines, make sure everything is to your liking, and then what do you do?

You upload it to the Dropbox, always making sure that it’s labeled correctly as a temporary version. Why? Because you would like feedback from your colleagues before **pulling** everything together (notice our word choice there 🧐).

## What’s a simple word for asking for feedback?

A **review**.

Dictionaries are interesting.

Anyway, your colleagues will then look at your brand new text and they will carefully look over it. They will correct mistakes, leave notes and suggestions, make recommendations, and, of course, if all is well, simply accept it.

When this is done, and the author of the new chapter is confident he’s answered all the queries and fixed all the problems, they can then **request** whoever is responsible for the manuscript to **pull** his changed text into the main document.

And that is what a **pull request** is.

When a developer finishes a task, they will start a process to **join the new code to the project**. For that purpose, they will ask whoever’s in charge of the project to **pull** the changes from their working branch to the main branch. Voilá, a request to pull changes: a pull-request.

## So it’s not a review, but it implies a review?

Most of the time, yes.

Unless the changes are very trivial, it would be irresponsible to pull changes into the main branch without performing a code review.

What happens frequently is the opposite: code reviews happen all the time without the need for a pull request.

A developer might want to review the changes between different states of a project for many different purposes:

- Auditing the source code is always important;
- Reviewing code without making it visible to everyone else in the project (pull-requests are always visible), for whatever reason;
- Reviewing the code when the project is scattered across many repositories;
- There are even some software development methodologies that don't use pull requests at all! And they still review code.

* * *

We hope this helped clear up what pull requests are, and why they are often wrongly mistaken for code reviews. Are there any topics you’d like us to cover next on this series?

If so, you know where to find us on Twitter ([@reviewpad](https://www.twitter.com/codereviewpad))!

#### Article series: For Dummies



_Not everyone will need a checklist for code reviews, and not all code reviews will fit into your checklist. We accept that, and _[_we have written about how some more senior developers sometimes even think they get in their way_]_(https://reviewpad.com/blog/six-more-best-practices-to-improve-your-code-review/). They are a very good idea, however, if you haven’t yet reached a comfort zone with your reviews._

A good checklist will keep you **consistent**. It will also prevent mistakes and omissions.

Here’s our humble proposal, just to get you started:

### Are all requirements met? 📋 

Requirements are the basis for all development. Regardless of what the project you’re working on is, and its scope, you will have a series of basic (and not so basic) requirements that the code must accomplish.

Check them, one by one.

Find the relevant code.

Review it.

Job done.

### Are code conventions being followed? 🤝

Code conventions aren’t bylaws, and they will change from project to project, and from language to language. They must be kept consistent throughout, otherwise, you can give rise to a whole ocean of troubles.

Whatever’s been established for the project and language you’re working with, it’s your job while doing a code review, that everything is up to snuff. That ranges from things as trite as indentation to things as meaningful as comments.

**Consistency** is the key word.

### Are magic values/scenarios accounted for? 🦄  

What would you think if you saw the number 259200000 in the middle of a particularly important piece of code about dates (i.e. days and months, not romantic liaisons), with no explanation?

And that number is absolutely key for the way the function works?

You wouldn’t be happy, would you? Well, that’s the number of milliseconds in three days, and some people might immediately get it and others might not. Anything that is key for the inner workings of your code that isn’t explained, is said to just “magically” work.

There’s no magic in development. Make sure everything is clear. Which leads us to:

### Is the code easy to read? 🤓

Remember: you don’t know who is going to be doing maintenance on the code base your team is working on. It may be you, or not. And even if it is you, it’s going to be the **future you**. We can promise you right now that you will not remember why that wonderfully clever function you’ve just written down works.

Everything needs to be readable. As readable as you can possibly make it.

### Does it have good test coverage? ✅

As much as the codebase as possible should be covered when running your tests. If the percentage isn’t high enough, then you probably need to consider changing the battery of tests you’re running.

Tests aren’t technically a part of code reviews, but they definitely go hand in hand as two of the most effective practices to ensure code quality.

### Is there no unused code? 💤 

Pretty self-explanatory, right? If the code is unused, it shouldn’t be there. No good can come of it. Only mistakes.

* * *

Did you enjoy our little checklist? Did we miss something? Is there a key step to your reviewing process that you feel should be on everyone’s list?

Make sure to drop us a line on Twitter ([@CodeReviewpad](https://twitter.com/codereviewpad)) and let us know.

#### Article series: Code Reviews 101



_This is one of the most controversial aspects of code reviews. People just don’t seem to agree about how long one should be taking doing code reviews, how long the ideal code review is, or even if you should time them at all._

The underlying thought is **valid**: code reviews depend on our ability to remain focused and detect minor flaws. It’s not an activity that you can perform well for very long. Tiredness and distractedness will destroy your productivity.

So how do we optimise this? Should we measure time? Set targets, such as the number of lines of code reviewed? Trust our body and perceptions?

We have some thoughts ourselves, but we’ll leave those for the end of the article. In the meantime, let’s look at the best arguments.

## Code reviews should take a fixed amount of time

This is one of the more common suggestions. The idea is that whether you’re measuring how much code you actually go through or not (because this is heavily reliant on its quality), you should focus on time, so you know you aren’t doing too much and reviewing whilst tired.

Common answers range from [60 minutes](https://smartbear.com/learn/code-review/best-practices-for-peer-code-review/) to [2 hours](https://hamidmosalla.com/2020/11/11/code-review-best-practices-a-short-guide/), and it is generally agreed that anything that exceeds two hours is too much and would necessitate taking breaks.

Not everyone emphasizes fixed amounts, however.

## Code reviews should be limited by space, not time

This is the second most popular suggestion. The argument is that time isn’t the best way to limit reviewing, the number of lines of code checked is.

The idea is that different reviewers with different skill sets are likely to take varying amounts of time to get the same work done.

This makes time-limited sessions an unreliable predictor of when the job will be done.

Proponents of best practices usually recommend around [300](https://asus-aics.github.io/DeveloperGuide/pages/003_code_review/) or [400](https://smartbear.com/learn/code-review/best-practices-for-peer-code-review/) lines of code at one go.

## Cognitive loads vary, so you should do both

This is by far the most common answer out there.

To put it quite simply, different people in different teams have varying degrees of tolerance for cognitive load. Some can work for longer hours, some can deal with more work.

No one is superhuman, though, and we shouldn’t expect that.

The ideal solution, if you are doing both, is to set limits in terms of **both time and space** and stop whenever you reach whichever is first.

## Our suggestion: figure out what works for you

When recommendations for best practices are this divisive, odds are different strokes will work for different folks.

This is **not** a bad thing.

We do believe that best practices for code reviews will be better defined in the future (and we definitely hope to contribute to that conversation), but some aspects of it will always be up to the characteristics of the team.

Here’s our recommendation, that we’ve included in [our Best Practices article](https://reviewpad.com/blog/six-best-practices-to-improve-your-code-reviews/):

Time your own code reviews.

Figure out how long it usually takes you to get through your work, and be mindful of your own limitations. Once you’ve understood how long it usually takes you to get through the amount of work you’re comfortable with, you will learn a number of important things, such as:

1. Which part of the codebase takes you the longest;
2. How long it typically takes you to handle specific issues;
3. When any given review is taking longer than usual, which can mean there are problems that need fixing elsewhere in the development process;
4. When you will need to compartmentalise and divide the work.

This is part of a larger point about code reviews best practices, which is all about [acquiring metrics that make your work easier](https://reviewpad.com/blog/code-review-metrics-that-make-sense/).

Something else that makes your work easier is having the correct tools for the job.

Which, incidentally, is what we make.

[Take a look](https://reviewpad.com/get-started/).

#### Article series: Code Reviews 101



_When you’re working on a specific field, it is extremely important to never lose focus. What are the basics of your work? Why does it matter? Why do you do what you do?  
  
We have decided to step back a little and take a good hard look at code reviews as a concept, and think through the basics of the work, why it matters, and how it’s become a cornerstone of software development._

## What are code reviews?

Some concepts are so ingrained in our day-to-day activities that we have a hard time defining them precisely. A code review is one of them. A lot of confusion arises from this. One of the most common misconceptions about code reviews is that they are the same as pull requests.

This is false.

Not only are code reviews **not pull requests**, they can happen independently of them, and outside of version control systems, such as Git. These are all tools that make code reviews more effective and easier to perform, but they don’t define the practice.

Code reviews, or peer reviews, are any and all software quality assurance activities where a person (or persons) that is not the original creator of the code will verify it by reading it.

That’s it.

It’s that simple.

## Why do we need code reviews?

There are a ton of [automated processes](https://reviewpad.com/blog/automation-in-code-reviews-dos-and-donts/) for reviewing code, correct? And there’s a lot to be said about [metrics](https://reviewpad.com/blog/code-review-metrics-that-make-sense/) that can guide a review, which can also be systematised even by someone without a deep knowledge of the code, correct?

So why do we need some of our brighter development minds to be spending a significant amount of time poring over code that has already been tested and passed?

For several reasons.

We need code to be **readable**. When we are performing code reviews, we aren’t just debugging, we are doing an exercise in creative reading. We are checking to see if we can perfectly understand everything the code does. Every codebase needs to be updated, and it’s just not practical to always rely on the original developer to do so. The code needs to be readable by someone else.

We need to transfer **knowledge**. A team that is composed of individuals that only understand the code they wrote is a team that doesn’t understand its own product. Code reviews aren’t just about improving the codebase, they are also about improving on what the team knows.

We need **continuous improvement**, not just fixing problems. A code review shouldn’t just focus on picking bugs or defects. The reviewer is a second set of eyes and a second mind, and they always need to be thinking critically. Are there better solutions? Can we improve quality? Can this be done more efficiently?

We need it for **team building**. Collective ownership is key. The team needs to know that every single line of code is owned collectively by everyone, not just by the person who typed. Code reviews make the team understand that everyone can contribute with valuable input at any stage of development in a practical sense.

## So how do I do them?

[We have a lot of thoughts about best practices regarding code reviews](https://reviewpad.com/blog/continuous-code-reviews-are-the-way-to-go/).

We understand not all of them are consensual, though, so here’s the bare minimum you **need to do** to implement an effective code review process with your team:

- Establish **what to look for**. Not all code reviews are born equal, and not all of them are looking for the same things. If you are making very minor changes to a function, for instance, you might not even need a review, even if it affects a significant number of files. Here are some things to look out for:
    - _Purpose_: Does the code do **what** it’s supposed to?
    - _Requirements_: Does the code do **everything** it should?
    - _Design_: Is the code readable and elegant? 
    - _Functionality_:  Does the code serve its **users** adequately?
    - _Complexity_: Could the code be **simpler**?
- Figure out **how you are going to assign** the reviews. Don’t just blast the whole team with a notification and have them randomly review things in their free time. Whether you’re assigning a senior and a junior developer or partnering developers in other ways, make sure reviews are assigned in a timely fashion to specific people.
- Make sure reviews are done in a **humane** way. One of the major roadblocks teams face regarding code reviews is that people sometimes tend to not handle the emotional aspect of going over someone else’s work in the kindest way. Reviews need to be about **collaboration, not competition**. [We were lucky enough to have a guest post on our blog about precisely this](https://reviewpad.com/blog/are-code-reviews-hurting-your-team/).

## If you are just getting started

We have made it our mission to improve code reviews, to make them more accessible and simpler for teams, and to truly make them an industry standard.

Reviewpad was designed to do exactly that, and you can try it for free.

[You can do it right now, in fact](https://reviewpad.com/get-started/).

Let us know what you think.

#### Article series: Code Reviews 101



_We started_ [_this series_](https://reviewpad.com/blog/series-for-dummies/) _with_ [_a quick introduction to code reviews_](https://reviewpad.com/blog/code-reviews-for-dummies/)_, and now we are extending the analogy and applying it to one of the most important tools of our trade: Git. It’s a revolutionary technology that entirely changed the field when it came to be in 2005, and we are going to explain how it works._

Think of **a book**.

How many authors does a book have? One, you say? Not necessarily. Every kind of book, from [fiction](https://www.bookdepository.com/Sleeping-Beauties/9781473681286) to [non-fiction](https://www.bookdepository.com/Freakonomics/9780061956270), from [serious journalistic inquiries](https://www.bookdepository.com/The-Dead-Are-Arising/9781631491665) to [the most commercial of novels](https://www.bookdepository.com/Good-Omens-Neil-Gaiman/9781473200852?ref=grid-view&qid=1625100862402&sr=1-1), can have several authors.

Let us tell you how collaborating on a book usually happens, and you will understand how Git works.

### 1\. You are writing as a team

Let’s say you are writing a book and you have a co-author. Now, in the before-times, when the Internet wasn’t a key part of everything we do, you would probably write down your bit, they would write down theirs, and you would need to either meet physically or exchange documents somehow (mail, a delivery man, etc.) to be able to compare and contrast versions.

This has a number of problems.

You can’t work on the same section at the same time, for one. If you want to both work on the same section, one of the writers will have to combine the different documents.

What happens if an author wants to make a change to a chapter that is already written? What happens if an author makes a lot of changes, and the others dislike it and want to go back to the old text?

Writing code as a team had many of the same challenges before Git came along. Git is a VCS, or Version Control System.

### 2\. A good VCS changes everything

Contemporary writers have Dropbox, Google Docs, and other tools that allow for synchronous work. No one really exchanges paper manuscripts anymore because computers and the Internet make life significantly easier.

These tools use one form or another of a VCS much like Git.

If a team of writers is writing their manuscript on, say, Google Docs, they can do a number of things that were impossible in the past, such as:

- All writers can collaborate on the same document at the same time;
- The main version of the book will always be up-to-date, regardless of changes;
- Past versions can be accessed easily;

There are plenty of VCSs out there that facilitate development, but Git is definitely the most popular, and it allows developers to do all of these exact same things. The most popular Code Hosting companies using Git are GitHub, GitLab, and BitBucket. Yes, **Git and GitHub are not the same thing**.

### 3\. Keeping track of every line written

When you’re an author working on a book, you are going to take great care with the wording and every choice made. This is every bit as true even if you have co-authors.

This is why modern VCSs such as Google Docs (which is more than a little bit inspired by VCSs) have a number of features that allow you to keep track of what’s happening while you and everyone else works.

You can, for instance:

- Download and upload up-to-date versions of the book;
- Create alternate/temporary versions of the book which you can share with the other authors;
- Join temporary versions with the main one;
- Easily deal with new chapters added while other writers worked on other parts of the book;
- Go back to older versions in case something was deleted or lost;

But what if a writer particularly likes or dislikes a specific line, section, or chapter, and wants to know who wrote it?

You can **do that too**.

When VCSs came up with the ability to identify the author of every single line of code, this changed things. Now it’s normal.

Most of the things we’ve listed are taken for granted. They seem like the basic features of any online text editor. Every single one of these features was introduced or made mainstream by Git, though, and every single one was hailed as the key innovation they truly were.

So now, as a way to break this little analogy we’ve built, here’s some Git terminology and what it compares to:

<Table
  headers={["Writing a Book in a Team with a VCS", "Writing Code in a Team with Git"]}
  data={[
    "Book | Code Project",
    "Book Section or Chapter |  Project Folder or File",
    "Main version of the book | <code>main</code> branch, or <code>head</code>",
    "Download the book for the first time | Check out the project - <code>git checkout</code>",
    "Update the book to the latest version | Pull changes, or Fetch changes - <code>git pull</code> / <code>git fetch</code>",
    "Temporary version to try new ideas | Branch - <code>git branch</code>",
    "Request to join temporary version to the main | Pull request, or Merge request - <code>git request-pull</code>",
    "Join temporary version to the main | Merge branches, or pull changes to Main branch - <code>git merge</code> / <code>git pull</code> / <code>git fetch</code>",
    "Save changes on the computer | Commit changes - <code>git commit</code>",
    "Upload changes to the team server | Push changes - <code>git push</code>",
    "Find who wrote a line of text | <code>git blame</code>",
  ]}
/>

_Git terminology_

* * *

We hope you enjoyed this little foray into Git, and please let us know what topics we can explain next in this [“For Dummies” series](https://reviewpad.com/blog/series-for-dummies/) on Twitter ([@reviewpad](https://twitter.com/codereviewpad))!



_This blog was started to foment discussion about the practice of code reviews. That’s because our goal is to change how code reviews are done. To us, code reviews are the most important thing teams can do to ensure code quality. We recommend a code review-centric philosophy of development. We are building the ultimate tool to do so, and today we are telling you a bit about how it will work._

### How Reviewpad will change the way you do reviews

One of the most important features of a code host nowadays is the ability to review code, which in GitHub and GitLab takes the form of pull and merge requests respectively.

Reviewpad seeks to enhance the way code reviews are executed, according to very specific guidelines. We want, for instance, to provide the tools for Reviewpad and code host users to **interact and communicate**. We want users to manipulate code reviews **in new ways** by providing extra features. And we definitely want to provide **more context** about the code being displayed than a simple textual diff.

The aim, however, is not to replace code hosts, but to synchronise with them. We want to provide a **unified interface** for opening and tracking code reviews across multiple hosts.

We will achieve this by using three independent mechanisms:

The first one is a mechanism that **extracts the code from code hosts** so that Reviewpad may analyse it and provide more context about the changes. This can be achieved by using a git client to clone each repository in a local database, after which it will perform frequent fetch operations to keep the code up to date.

We also have a mechanism that propagates changes performed by Reviewpad on this information to the code hosts. This is achieved by establishing a map between the unified code review model of Reviewpad and the models of each code host.

Last but not least, there is a mechanism that **retrieves and stores information about code reviews**. This article is about this mechanism, which will be explained in depth.

You will have noticed that the first and second mechanisms are relatively simple to explain.

We use the code hosts’ remote APIs for propagating changes and whenever a user manipulates a code review (e.g., performs a comment, opens or closes a code review), we map it into a sequence of operations of the code host’s API and execute them as soon as possible.

Let’s focus on the last mechanism, then.

### The challenge

The issue with retrieving this information about code reviews is not so much the implementation, but **the task itself**: the requirements are often conflicting.

Let’s look at these requirements in order.

The information we must retrieve comes in a **wide variety**.

**First of all**, we must retrieve the code’s location in terms of code host hierarchy. Because the organization is always hierarchical, regardless of the code host. For instance, in GitHub, repositories belong to an organization or a user and are identified as `{org/user name}/{repository name}`. Things are different in GitLab, where repositories can belong to users, but there are no organizations. Repositories can instead belong to a hierarchy of projects of any depth. For instance: a repository may belong to a project A, a subproject B of A, a subsubproject C of B, and so on.

Now, in general, a code host consists of trees of code sites. A leaf node is a repository, inner nodes are users/organizations/projects, and the root nodes are the code host itself. What we are setting out to do is locate code reviews in this hierarchy so as to play with the natural way of locating code reviews in code hosts.

Evidently, there’s plenty of other stuff to find, such as:

- Meta-data, including title, description, reviewers, comments, or user reviews;
- History of commits and pushes;
- Checks that determine whether the code review is ready to be merged;

And, last but not least, **access control information**. This is what makes it so that users can access or manipulate only the data the code host’s rules allow them to.

**Second requirement**: We have limited access. This information can only be imported through the code host’s remote APIs, which have rate limits of requests. We must figure out a way to import all of the information without reaching that limit. If we reach it, some  requests may fail.

**Number three**: We want to provide context about the changes that happened during the review. To compute this analysis takes **time**. We want operations to be as fast as possible to ensure a good user experience.

**The fourth requirement** is that we must ensure quality of data. That means data needs to be as up-to-date as possible and consistent.

**The fifth one** is true of all software products: we want code complexity to be manageable so Reviewpad is easy to maintain.

To achieve this, we had to make some key design decisions.

### The design decisions

The first thing we took into consideration when planning this feature was who was going to be using it. Who are Reviewpad’s users? What are their needs and expectations? We figure that Reviewpad users will spend most of their time reading code review changes, and changes outside of Reviewpad will happen relatively infrequently, such as when users:

- push changes to the code review code;
- add/remove/edit comments directly in the code host;
- make changes to the code review meta data, e.g., change the description or the base branch

This also suggests changes to the code sites in which code reviews are located will be even more rare.

This led us to make a call: we are going to import (or compute) the majority of the information beforehand, store it in a local database, and only react to changes **as they happen**. Resource-intensive operations of importing mostly static information can be triggered once by system admins before normal Reviewpad usage, and that allows for most subsequent operations to require only light updates on the database. In the rare cases of more resource-intensive updates, such as a full code site refresh, they can be performed in the background without affecting Reviewpad usage. The idea is for the operations to be concluded in the time between their beginning and the moment when users take a look for any new information.

Let’s look at this in more detail:

Since repositories are organized into a tree of code sites, we have chosen to allow users to import **all the repositories and their code reviews** under a given code site (which may be a single repository).

By doing this, let’s say a user imports a github organization. We will then import **all the repositories** under that organization. Moreover, we will start tracking said organization, so any subsequent changes, such as an added repository, will feature on Reviewpad.

How?

**Webhooks**. Webhooks are essentially subscriptions of changes on repositories. Whenever a change happens on the code host end, Reviewpad is notified with a message, which triggers an update.

### The challenges we faced

The fact that we made our decisions doesn’t mean it’s all smooth sailing. By deciding to import everything, we ran the risk of creating slow operations that would be hard to debug in the case of very large repositories. And relying on webhooks is always a risk. They can fail, or quite simply not be available. And, of course, as we mentioned, there’s a rate limit to what we can import. By doing it in bulk, we will reach it faster.

We had to tackle **every single one** of these issues.

The first thing we did is make sure we import all the info **asynchronously**. Whenever a user starts an operation, they can start using Reviewpad immediately. In the background, the database is being uploaded. A nifty little tracking mechanism will be shown so the user knows the current state.

How about important information, such as when a user detects an inconsistency? Reviewpad will allow for users to refresh imported info **manually** when needed.

These measures accomplish **two things**: we are no longer dependent on webhooks not failing, and we can work with repositories that don’t allow for them (such as open-source).

The next thing was to break up all important operations into much smaller tasks. Each task **imports information regarding a subset of entities**, e.g., tasks for retrieving the code site tree, for retrieving the list of code reviews in a repo, for importing the code review metadata, for extracting information about pushes and commits, for synchronizing the git repository.

Tasks will obey a specific hierarchy, spawning others as needed:

![Reviewpad's backend task hierarchy](/posts/images/16.-Task-Hierarchy-B.svg)

Task Hierarchy

As you can see in the graph, code site retrieval is the root task. Under it, we have tasks for extracting the repositories’ metadata and their list of code reviews, as well as for synchronizing the code, among other things.

### Why we made these choices

The main advantage of taking this approach is that we can improve the performance of the import operation by running tasks in parallel, all the while keeping a refined log of the import operation.

This way, instead of seeing a single flat log, we can organize it into a hierarchy of logs which follows the same structure as the task hierarchy. Each individual log will contain the main events of each task, and we will then be able to quickly trace down any problems to the exact task in which they occurred.

Our **entity-refresh approach** allowed us to reuse these tasks in update operations, which decreases code complexity.

This means that instead of computing the minimum required changes on the database for every update operation, we instead identify a set of entities affected by the update and retrieve all their information from scratch.

There are advantages and disadvantages to this approach, of course, especially when compared to more refined approaches that would involve calculating the deltas in the affected entities.

On the one hand, we can reuse the import tasks in every refresh operation, refreshing itself is quite simple (you just extract the latest information of every affected entity and insert it in the database, or replace the previous information in case it exists), and a single refresh can quickly fix any inconsistencies.

On the other hand, we will make more requests to the code host’s API per refresh operation. Remember, the rate limit.

To ensure the limit isn’t reached, we use **throttling**. Whenever we have access to the rate of requests available to a user at any given point in time, we can throttle the requests on our side, controlling the rate at which requests are sent and slowing them down if necessary. This may slow down the operation, of course, and that information is not always available (such as in Bitbucket), but it is an important measure to have in place.

In any case, what we can do is to refine tasks as much as possible so that refreshing only affects the smallest number of entities possible, minimising requests to the code hosts. We can also optimise only **the most critical** refresh operations to only update what is really necessary.

Some trade-offs will still be required, of course. We only enforce eventual consistency. Failures are relatively rare, and update operations are quite fast, which means information is kept up to date **most of the time**. Given that any inconsistencies can be quickly fixed by the manual refresh, we think not enforcing total consistency is an acceptable trade-off.

### This is how we built it

We used Go as our primary language and there are four key mechanisms to the implementation.

1. **The throttling of code hosts’ API requests**, which quite simply consists in controlling the rate of requests such that it never exceeds the rate limit we’ve mentioned earlier. We have based our algorithm on the [token bucket](https://en.wikipedia.org/wiki/Token_bucket), which delays any requests that will cause an abuse. We don’t enforce a constant rate limit, instead adapting it to our expected usage profile. We also make sure that more important operations are performed first, and, thus, at a higher rate.
2. **Asynchronous Task Mechanism**, which uses Go synchronisation primitives to organise the code into asynchronous tasks, specifying the hierarchical relationships and dependencies between them, and submitting them to be run in the background. We’ve also gotten the help of the front-end team to create an interface and tracking mechanism that allows us to visually track any and all tasks where errors occur.
3. **Manual refresh** will avoid a more costly and unnecessary untimely refresh of code reviews and entities at higher levels by allowing the user to trigger specific refreshes whenever they detect inconsistencies.
4. **Webhooks administration** will provide users with a very simple interface to add or remove webhooks from repositories. Once added, Reviewpad will process the corresponding events using much the same mechanisms as those in manual refresh and code site import operations.

We hope you have enjoyed this deep dive into how we are building this tool. If you have, then we are quite confident you will love to explore it yourself. You can [try it now for free](https://reviewpad.com/get-started/), and we encourage you to do so!



_The right branching model will improve any team's collaboration skills, quality, and speed. The wrong model will do exactly the opposite. These are the 3 most used._

Name a company that develops software. There's a very high chance they are are using Git to source control their codebase. Actually, there's a 77% chance, according to [Smartbear's State of Code Review 2020 Report](https://smartbear.com/resources/ebooks/the-state-of-code-review-2020-report).

There's also a very high chance any given company has a code review process in place. An 84% chance according to [Codegrip's Code Review Trends in 2020 report](https://www.codegrip.tech/code-review-trends-2020/).

However, there isn't a single standardized methodology to develop software using Git and Code Reviews. This is because whatever strategy is best is highly dependent on the team and the project's characteristics. It's entirely up to the team to choose which methodology better suits their software development needs and goals.

Let's take a look at the 3 main methodologies (also called branching models or branching strategies):

- Git Flow
- GitHub Flow
- Trunk Based Development

### The original: Git Flow

Rarely does a blog post impact the industry as the one Vincent Driessen published on January 05, 2010, named [A successful Git branching model](https://nvie.com/posts/a-successful-git-branching-model/).

In his post, Driessen laid out Git Flow, a robust and strict branching model that became the industry standard for software development for years.

It brought parallel development to the masses, created the perfect conditions for collaborative programming, and it scaled easily.

With it, many companies managed to grow large and efficient teams and to deploy very complex software.

With Git Flow, the repository is centered on the `main` and `develop` branches, and it is supported by `feature-n`, `release`, and `hotfix` branches, as described in this diagram:

![Git Flow workflow](/posts/images/branching/Git-Flow.svg)

Git Flow

Code Reviews play an essential part in ensuring the code is up to standard and bug-free when merging `feature` branches to the `develop` branch.

Git Flow allows for a very methodic and orchestrated software development but comes at a very high cost:

- the sheer volume of branches and their overhead are a nightmare to maintain
- teams have to be extremely disciplined, otherwise they will end up with long-lived branches which become impossible to merge

### The successor: GitHub Flow

With the advent of web apps and continuous delivery, a lighter and faster branching model gained traction: [GitHub Flow](https://guides.github.com/introduction/flow/). As you might've guessed, it was created and popularized by the GitHub themselves.

It's centered on the `main` and `feature` branches. `Main` is always releasable. Developers create a new `feature` branch to make changes. After reviewing these changes for bugs and code quality they will be deployed to production. If they cause problems, a rollback from `main` will take place. Otherwise, the `feature` branch will be merged to the `main` branch.

![GitHub Flow workflow](/posts/images/branching/GitHub-Flow.svg)

GitHub Flow

Compared to Git Flow, GitHub Flow is much lighter. Maintenance is very low because the only long-lived branch is `Main`.

However, GitHub Flow inherits other drawbacks from Git Flow. Undisciplined teams that keep `feature` branches open for weeks risk serious problems when trying to merge. Ultimately, a failed merge can leave `main` undeployable, and that's a big red flag for continuous delivery.

### The shift: Trunk-Based Development

Also going by TBD, Trunk-Based Development is somewhat famously documented at [trunkbaseddevelopment.com](https://trunkbaseddevelopment.com/). In this branching model, developers make changes directly in a single branch called `trunk`.

`Trunk` is deployable at all times. Changes should be summited daily. Unfinished features should be unexposed with the help of [feature flags](https://martinfowler.com/articles/feature-toggles.html).

![Trunk-Based Development for Small Teams workflow](/posts/images/branching/Trunk-Based-Development-for-Small-Teams.svg)

Trunk-Based Development for Small Teams

![YOLO Merge](/posts/images/branching/YoloMerge.png)

Yes, you read it right. It sounds like Yolo Software Development. There is no code review in TBD, either.

The catch is that this method can only work with/for small teams, with seasoned developers. Pair-programming is highly recommended. The pace is very fast because there is very little, if any, overhead. The team must be very skilled and cautious because everything goes directly to the `trunk`.

This TBD model is actually officially called **Trunk-Based Development For Smaller Teams**. Despite its shortcomings, TBD for Smaller Teams is highly regarded by the software development community for its extremely lightweight workflow.

### The seasoned: Scaled Trunk-Based Development

Luckily, TBD has another trick up its sleeve: Scaled Trunk-Based Development. In order to operate at scale, this branching model uses short-lived `feature` branches with a life span of a few days (maximum) before merging to the `trunk`, which is deployable at all times.

Work in progress should be kept to a minimum, not only to avoid merging problems with long-lived `feature` branches, but also to make up for easier and faster code reviews.

Code reviews will guarantee only quality code is merged to the `trunk` and will allow for very early defect detection.

![Scaled Trunk-Based Development workflow](/posts/images/branching/Scaled-Trunk-Based-Development.svg)

Scaled Trunk-Based Development

With Scale TBD, continuous integration is guaranteed, parallel development is supported, and quality is ensured with simple code reviews. It allows for quicker iterations with fewer errors, and it's always deployable with very little branch management.

### Own it!

It goes without saying that each team and/or product might warrant different needs in a branching model. Teams should take extra care choosing one.

Whichever branching model is chosen, it is very (!) important that it's crystal clear to every team member what are the rules and steps in the workflow. Without it, any model will fail to bring out the best of the team and the product.



_There are many pains associated with code reviews, from GitHub’s web interface that only displays a textual diff between files, to the inadequate processes that cause you to review highly complex changes._

Reviewpad is **a new code review tool** with a single purpose: to help developers by simplifying the process. This must happen regardless of the code host, the number of changes, the maturity of the codebase, or the expertise of the reviewer. We wholeheartedly believe in this mission because code reviews are too important to be neglected.

In this post, we will describe Reviewpad’s key design decisions, architecture, and some lessons learned while coliving with GitHub, GitLab, and Bitbucket.

### Key Design Features

Reviewpad is a **web code review tool for git repositories**.

It provides seamless integration with code hosts such as Bitbucket, GitHub, and GitLab (including their self-hosted versions) with a dedicated interface for code reviews featuring new code visualisation methods and static code analysis technology.

Reviewpad was developed with the following key design features:

1. **On-premise deployments.** You can set up Reviewpad in a single developer environment, in a server for dozens of developers to use, or even scale it with a Kubernetes cluster for hundreds of developers. You can monitor all of Reviewpad's requests for maximum security.
2. **Zero configuration required.** You don't need to configure your team members or review settings. Reviewpad mirrors the permission system from your code hosts so that users only have access to the same information as they would have there. The same is applied to actions: you can't merge a pull request on Reviewpad unless you can do it on the code host.
3. **Smooth team adoption.** Reviewpad integrates seamlessly with code hosts. That means that in a team of 10 developers, you don't need all 10 developers to use Reviewpad in their review process. Because all the actions in Reviewpad are propagated back and forth between code hosts, a subset of the team can safely use it for reviews without breaking the existing review process.
4. **Security first.** It has been designed to ease security concerns that are connected with any tool that handles sensitive and proprietary information such as code, comments, and personal information. A running instance of Reviewpad does not communicate with Reviewpad.com servers or any non-disclosed third party to send any information.

### Complete abstraction from code hosts

So what is Reviewpad? Reviewpad can be seen as an abstraction layer on top of existing git-based code hosts.

![Reviewpad Conceptual Overview](/posts/images/architecture/Fig-1.svg)

_Reviewpad Conceptual Overview_

The integration with a code host is so that communication is performed both ways. Reviewpad users will connect to a code host through personal access tokens or via OAuth apps. Actions on Reviewpad (e.g. submission of a user review) will then be sent to the code host using their REST or GraphQL API. Actions on the code host are propagated back to Reviewpad through Webhooks.

To be able to achieve this feature in a modular and scalable way, we needed to overcome two major technical challenges:

1. Converting data from git repositories and code reviews from code hosts into a single internal data representation. 
2. Unifying the code hosts’ APIs so that Reviewpad core services can be code host agnostic.

The first challenge was much harder than we anticipated. We weren’t expecting so many differences between code hosts.

Here’s an example: when it comes to commenting features, GitHub and Bitbucket Cloud behave very differently -  the concept of user reviews where you can aggregate a set of comments into the same review doesn’t exist on Bitbucket. A notification will be sent to the PR author **for each review comment**. Another surprising factor was the API differences between the SaaS and the enterprise versions.

To overcome our second challenge, we brought in our experience-designing program analysers. Akin to LLVM IR (low level virtual machine intermediate representation) when it comes to translation of high-level programming languages, we have designed an intermediate API layer that unifies the code hosts’ APIs. When you are designing an IR for multiple source languages, the first main decision is whether to take the intersection or the union of the language constructs. In our case, we decided to do a fine-tuned intersection where we support the best of multiple code hosts.

### Basic Architecture

Reviewpad is composed of two main components:

- **Front-end service**: React application that implements the review interface. This is the main service that users interact with in their browser. In terms of network, the front-end service only communicates with the back-end service.
- **Back-end service**: Microservices application that exposes a REST API.

The following diagram represents an overview of Reviewpad's architecture.

![Reviewpad Architecture Overview](/posts/images/architecture/Fig-2a.svg)

__Reviewpad Architecture Overview__

As we are effectively importing the metadata from the code hosts and also performing analysis over the code, we use two permanent storage mechanisms:

- PostgreSQL database that stores code host metadata, analysis results, and internal information.
- Docker volume to store git objects.

Reviewpad also comes with a notification system that sends a Slack message or an email similar to the integration that you can already achieve with existing code hosts.

Not depicted in the overview are the services that perform the semantic analysis of the code and the relational analysis of the diff belonging to a pull request.

We have reached a stage where the foundations of Reviewpad allow us to easily implement new features. We have discussed the need to [make code reviews independent](https://reviewpad.com/blog/code-reviews-need-to-outgrow-pull-requests/) of pull requests in the past. We now feel like we are in a position to provide **the same review experience** without them. Even if these pull requests span across multiple repositories in multiple code hosts.

* * *

We will be looking to expand on the possibilities of Reviewpad in the next few posts, so please stay tuned! Next week we will be looking at what happens when a repository is imported.

In the meantime, you should [try the beta now](https://reviewpad.com/get-started/).



_This blog has dedicated itself to the intricacies of code reviews. We’ve written about best practices, our review-centric philosophy for development, the case for simpler code reviews, and a few more topics of interest. We haven’t, however, taken the time to explain what code reviews are to the non-developers. Now is that time._

Think of **a book**.

Do you have one next to you? Do you know how it was made? Let us tell you about editing a book. When we’re done, you’ll know exactly what a code review is.

### 1\. The author creates a draft

You can’t have a book without a writer, much in the same way that you can’t have code without a developer. The book can be of any kind. It can be a novel, it can be a collection of short stories, or even non-fiction and essays.

No matter how gifted the author, they can always use the help of a publisher to print and sell the book, but also **an editor** to work on the text.

Regardless, it’s up to the writer to produce a draft before they come in. It doesn’t need to be a finished book, by the way. For many publishers, the editor (sometimes two or more) will work right alongside the author throughout the writing process.

Developing code is similar. The developer creates the code and the reviewer looks it over for inconsistencies, problems, mistakes… Anything, really.

This is how we see things:

- Author - Developer;
- Book - Feature/task the developer is writing code for;
- Editor - Reviewer assigned to this feature/task;
- Publisher - The company or team.

### 2\. The author edits their own work

“Editing is writing” is an old creative writing slogan that rings quite true. Any author worth their salt will never dump their uncorrected first draft on an editor. They will always go back to work, retrace their footsteps and improve what they’ve done. Ideally, the author will be able to answer any questions the editor asks about their work, and the choices they made.

In code reviews, every developer should be their own first reviewer, always checking their code while the decisions made are still fresh, so the reviewer will have as easy a task as possible.

### 3\. The author will hand off the draft

When the author is happy with their work, they will then send it off into the wild. The wild, in this case, is an editor. This is a relationship that is sometimes described as adversarial, with both authors and editors feeling like they should have the last word over the text, because they are, in their own ways, specialists. This is, of course, **pure nonsense**. It’s in fact an exercise of co-ownership, where both parties profit from the text being of the highest quality.

One of the hangups people have about code reviews is quite similar to this. Developers, like authors, are fearful of the critiques and suggestions that reviewers and editors send their way, and they feel exposed when their work is in the hands of others.

There’s no need for this. Reviewing, much like editing, should be about collaboration, not confrontation.

### 4\. The editor will fix mistakes, but, above all, they will make suggestions

The editor is a second pair of eyes. The author is living inside the world of their writing, which many times is a little too close to see the bigger picture. Someone else that comes in fresh, and is encountering the text for the first time, will be able to see elements that are missing and things that aren’t doing their job properly.

A reviewer will do the same thing for a codebase. They will find mistakes, of course, but the most important part of the job is to look at the code and try to understand it. To ask questions and make suggestions. The goal is to elevate the work.

### 5\. The draft goes right back to the author

This is a moment of great anxiety. The work you put so much into is coming back with \*gasp\* criticism. Comments. Suggestions. It’s wrong, it’s all wrong. It’s terrible. You are a fraud.

No.

Of course not. If the editor is good at their job, and sensitive to the idea that the author is another human being who’s doing their best, the comments and suggestions should be light-weight, thoughtful, and humane. Whenever there’s an issue that is a little more complicated to follow, authors are encouraged to get in touch with their editors to discuss them and come up with a joint solution.

There is no difference for code reviews here. The reviewer and the developer will ideally engage in creative dialogues that will produce solutions that neither of the two could’ve come up with alone.

### 6\. Time to make changes

Sometimes changes are small, and the first draft only gets slightly altered. Sometimes the editor will find a serious problem that needs a complete rewrite. Most of the time, the result is somewhere in between. The author will select which comments and suggestions to disregard and which to pursue. Some text will be rewritten, some mistakes will simply be fixed.

In code reviews, the developer will go through the same process. Not all suggestions need to be handled right away (or ever), and the reviewer isn’t the final authority. The suggestions and comments will bring forth new ideas and, ideally, result in a better code.

### 7\. Do it again

The editing process only culminates when the book is ready to be printed. **Until that printing press starts whirring, changes can and will be made**. Other people will be proofreading the book as well, not just the original two. Most books will be read by assistant editors and proofreaders as well somewhere along the process, to ensure that as many issues as possible are ironed out.

Code reviews should be a continuous process as well. As long as the developers are making significant changes to the code, it should be getting reviewed as well. Other reviewers should definitely come in as well, allowing for collective ownership of the codebase.

### 8\. Never be satisfied

What if the book is printed and you find a mistake? What if you want to update the book with more recent findings? What if you decide the story needs to be expanded? That’s what second, third, etc. printings are for. As long as the book is on the market, edits can and will happen. Expanded editions will be published. Revised editions as well.

That is the life of software development too. Software needs to be maintained and updated. Much more so than books.

And where there’s development, there should be reviews.

* * *

Let us know what software development topic you would like to see in the [“For Dummies”](https://reviewpad.com/blog/series-for-dummies/) series next in Twitter [@codereviewpad](https://twitter.com/codereviewpad)!



_Code reviews are (still) complex_. _We started this series_ [_here_](https://reviewpad.com/blog/six-best-practices-to-improve-your-code-reviews/)_, and we are back now to complete it with six more recommendations._

### 1\. Stick to the point

There is a school of thought that recommends creating very broad and ample pull requests that will encompass a variety of issues and promote a more thorough review. We don’t share that idea. Development is a fast-paced environment and code reviews should be continuous and integrated into the dev process. That means pull requests need to be specific and as clear as possible to the reviewer, so that communication is as seamless as possible.

### 2\. Focus more on questions than answers

We believe in co-ownership of the codebase. That means the reviewer and the original developer are cooperating on a project that is of both their responsibilities.

The reviewer isn’t “fixing” their colleague’s “mistakes” any more than the developer is being evaluated.

What’s happening is a dialogue, a collaboration that will improve the quality of the codebase. That means that when you find an issue, or something you don’t entirely agree with, it may be more interesting to make suggestions, or question why the developer made that choice, instead of simply stating a fix that may not fully fit the original intent of the code.

### 3\. Impact matters much more than the size

While some may recommend that any change warrants a full review, or that every change must be manually reviewed, we don’t think that’s the way to go if you are getting familiar with the code review process.

If you replace the name of a variable, it hardly matters that you have changed fifty files or five. You know exactly what you’ve done, and automation ensures that there’s no point whatsoever in checking every instance of the change.

What matters is when you’re making **conceptual changes**.

### 4\. Clearly label changes that aren’t conceptual

This stems from the previous point. If all you’re doing is fixing a bug, or changing a small detail that is self-contained and doesn’t affect the rest of the codebase, it’s very useful to make that clear for your colleagues.

A small note indicating clearly that “_this change here is separate from everything_” and explaining your train of thought and reasoning will go a very long way in avoiding roadblocks.

### 5\. Speak up to improve the process

What if you usually allocated half an hour for code reviews in the past, but now you’ve become better, started seeing more issues, and now you need more? **Speak up**. What if you used checklists when you were a junior developer and reviewer (a good idea) to make sure you didn’t miss anything, but now you feel like they are getting in your way? **Speak up**. What if you feel like an inadequate amount of conflicts are being generated by code reviews? **Speak up**.

It’s very important to not let so-called “best practices” get in the way of actually doing good work. Teams are different, and what is helpful for people with different skill sets and levels of experience is also different. If something isn’t working, it needs to be changed.

### 6\. Talk to people directly

Code reviews are not a place for conflict. They’re not a conflict resolution tool. You should be writing code you can defend but you **shouldn’t need to be on the defensive**.

Positivity in the review itself, and keeping things as light-hearted and communicative as possible will help with this. Making sure the reviewer and the developer understand they are co-owners of the same thing and not competitors too.

The one thing that almost always fixes things, however, is a good old-fashioned conversation. If you move the review from async comments to a synchronous discussion, most gritty misunderstandings and tonal difficulties will evaporate in no time. This will not only protect your team from a lot of mental wear and tear, but it will actually save you plenty of time in useless back and forths in the comments.

Just **talk to your teammates**.

* * *

**These are our recommendations**

What did we miss? Is there a particular issue that you feel helped your team immensely that we didn’t cover? Are we wrong about any of this?

  
We’d love to hear from you. Just follow us on Twitter ([@codereviewpad](https://twitter.com/codereviewpad)) and drop us a line.



_Code reviews are one of the best ways to ensure code quality. A_ [_recent survey_](https://www.codegrip.tech/code-review-trends-2020/) _has found that 36% of the companies that do code reviews (84% of the total) think it is_ **_the_** _best way to improve code quality. Too often, however, they are understood as an individual task, instead of a team effort. This article will delve into the_ status quo _of code reviews and where the roadblocks lie._

### We aren’t teaching enough how to do code reviews

The number of software developers working is increasing at an [impressive rate](https://www.daxx.com/blog/development-trends/number-software-developers-world). The number of people working in the field, both in the US and the EU, is quite encouraging from a marketplace point of view. In the US, for instance, the number has climbed from 3.4 million to 4.4 million in just a few years (2017-2019).

No complaints here.

However, this also means one thing: the proportion of junior to senior developers is also changing. People are entering the market much faster than they are being promoted. Code reviews, by and large, are not taught at University. They are something you learn on the job, ideally while being mentored by a more senior developer.

As that ratio changes, however, this becomes harder to achieve.

### Code reviews aren’t being prioritised

Effective code reviews, [as we have written in the past](https://reviewpad.com/blog/continuous-code-reviews-are-the-way-to-go/), need to be **continuous**. When the code is being developed without an effective integration of the reviewing processes, it often gets done last minute. Teams that are using agile techniques often end up bundling a lot of code reviews and doing them at the later stages of a sprint.

This will hurt your reviews even when you **do have** highly skilled reviewers. If you don’t… then you have a serious problem.

### Code reviews are not an individual task

There are two aspects to doing code reviews. A part of it can, in fact, be an individual effort. The reviewing itself doesn’t imply working in pairs. But that’s only a small part of it.

If you aren’t assigning the reviews throughout the process and are, in fact, bundling them as we described, odds are you won’t assign them evenly. You will want the most skilled reviewers in your team to be doing them, to avoid creating massive bottlenecks.

![People responsible for Code Quality in their companies](/posts/images/People-responsible-for-Code-Quality-in-their-companies-300x252.png)

[Codegrip's survey Code Review Trends in 2020](https://www.codegrip.tech/code-review-trends-2020/)

The same study we quoted in the intro, focused on [code review trends](https://www.codegrip.tech/code-review-trends-2020/), has discovered that the Team Lead alone is responsible for code quality in **more teams** (38%) than those who share the responsibility (36%). In fact, a staggering half (50%) of teams assign this responsibility either to the Team Leads or senior developers alone.

Evidently, this is unsustainable. And the numbers show it. **Only 35%** of the companies that do code reviews are happy with their results. The others all mentioned they needed to improve them.

### Code reviews need to withstand staffing changes

Let’s dive deeper into those numbers: 67% of the companies that **aren’t** doing code reviews yet say they would want to. So what’s stopping them?

![Number one obstruction to implementing code reviews](/posts/images/Number-one-obstruction-to-implementing-code-reviews-300x255.png)

[Codegrip's survey Code Review Trends in 2020](https://www.codegrip.tech/code-review-trends-2020/)

Fewer than 50% of **smaller teams** had code review processes in place. 36% of all companies that don’t have these processes blamed not having enough staff.

This clearly indicates that code reviews are still seen as a separate process from development, something to be done afterwards, separately. The immediate result of this is that leads and senior developers end up doing most of the work, and junior developers don’t learn how to do reviews.

Worse: Leads and senior developers leave. Sometimes they’re absent. Unforeseen events happen, and the processes must be in place to deal with them. A continuous, code-review centric, development process will organise reviews so they are spread purposefully amongst the team in a way that mitigates this issue.

### We need the right tools

We have also learnt that only 57% of teams are performing tool-based (or using a combination that includes tools) code reviews. The market is failing 43% of teams, who are performing code reviews without the help of the software that makes the task easier.

This will inevitably contribute to code reviews feeling like much more of a demand on time than they need be. I have [tweeted recently](https://twitter.com/marceloabsousa/status/1382643884333924359) about using Reviewpad for short sessions of pair programming followed by asynchronous code reviews. I found it to be a powerful way of working, and certainly something to explore further. It’s hard to develop better practices for code reviews if you don’t have an **adequate toolkit**.

### Good and simpler

Gergely Orosz has written [an excellent article](https://stackoverflow.blog/2019/09/30/how-to-make-good-code-reviews-better/) about perfecting code reviews, and a lot of his suggestions ring true. He differentiates between **good** and **better** practices for code reviews. We would, however, suggest a different way of thinking about this: **good** and **simpler** practices.

At the end of the day, we believe in a code review culture that integrates this process into development in a way that doesn’t make them feel like a separate entity.

We want to switch the focus of the best practices analysis from what’s ideal to the code reviewer as a separate, individual, entity to what’s best for the team and the shared ownership of the codebase.

This usually means adopting **simpler** practices that make code reviews more lightweight. It means sharing the load, instead of demanding so much from senior developers. It means bringing junior developers in early, so they can learn from the best. It means doing code reviews continuously, instead of at the latter stages of a sprint. It also means having the right tools.

**And this, in a nutshell, is why we’re building Reviewpad.**



_Code reviews are complex. They involve good time management, high emotional intelligence, knowledge of the codebase, and technical expertise. It is a team process where practice and communication are everything. In this post, we share six key practices that software development teams are doing to elevate the quality of their code reviews._

### 1\. Review your pull requests before Others

By reviewing your pull requests before asking for other reviews, you are first checking that your pull request is reviewable. If you can’t understand the code changes or go over them in a reasonable time you immediately realize that others will probably face the same difficulties. Also by reviewing your code first, you can save review iterations by spotting and fixing minor inconsistencies. Write pull requests to your future self.

### 2\. Encourage reviewers to be co-owners

There’s a tendency among reviewers to treat comments as sticky notes. Reminders. Things that will **call your attention to a problem**. You’ll see things like “Fix this”, or “To do”, all the time.

This isn’t ideal because reviewers are playing the role of gatekeeper which will inevitably lead to friction associated with the inherent power dynamics.

By encouraging reviewers to play the role of co-owners you are establishing a common goal between the stakeholders in the process.

A concrete way of doing this is to treat comments as written thoughts while you are going through the changes. This will inevitably lead to a lot of questions. Why does this need fixing? How would you go about it? Do you have suggestions, or guidance? 

Still, if you have these questions, probably someone else will too. Do not be afraid to share your **doubts and questions** about the code. You took the time to go through the changes. Document this knowledge.

Remember that not every comment needs to be resolved.

### 3\. Leverage automation

[Automation is key to improving the quality of code reviews](https://reviewpad.com/blog/automation-in-code-reviews-dos-and-donts/). Understand why you are asking for a review. If you are looking to merge a pull request, ensure that the code compiles and the tests are passing. Use automation as a safety net to prevent reviews or merges of code changes that are fundamentally broken.

Dedicate time to set up automation that can save you and your team a lot of time and useless review iterations.

### 4\. Always have a reviewer in mind

**Never** (ever!) approach a group of people asking for reviews. This means slack channels, group emails, or any other form of communication that will essentially amount to asking for a volunteer. People are busy. They will always secretly expect someone else to answer, and time will be wasted. It will also generate resentment towards the task of code reviewing, making it feel like something **extra** to do, aside from your actual work. This isn’t true or fair.

Ask someone ahead of time for a review, and let them know as soon as the review can start. This way, they can set aside time to do it and there will be no roadblocks.

### 5\. Time your code reviews 

It’s important to [keep metrics](https://reviewpad.com/blog/code-review-metrics-that-make-sense/) that help you understand where roadblocks are and in what ways you can improve your workflow. If you time your code reviews, you will always know how long they took you. You will learn how fast you can tackle specific issues, and which parts of the codebase are hard to review.

Metrics are a great way to improve your own productivity and to start conversations on how to balance the review load and improve the overall review process.

### 6\. Create a top 10 list of pull requests

Treat code reviews like amazing feats of skill. Sports managers improve their athletes’ performance by selecting footage for them to watch, and you should be doing pretty much the same.

Find pull requests that illustrate specific practices you think your team can learn from. How to leave perfect comments that are actually helpful. How to detect the kinds of problems a developer typically misses. How to illustrate a problem effectively so that someone can pick it back up even months later.

Always have this top 10 available for developers to look at and derive inspiration from. Use it often in learning sessions.



_Interns are having to adapt to the realities of the job market in a series of unprecedented circumstances. With the pandemic, and the proliferation of remote work, internships are happening at a distance. Young people who have never seen the inside of an office may never do it at all. We sat down with our own interns to see how they are dealing with this new experience._

It is customary for profiles like this to start with a quirky anecdote about how the interviewer and interviewee (in this case interviewees) met. Alas, the meeting was, of course, remote. All that can be described is the flickering of computer screens and bright faces in video call frames. Cheila and Inês were happy to talk to us, however, and tell us what it’s like to be an intern in 2021, working fully remote.

### Embracing the remote ethos

“We didn’t really have a choice, at the start, did we?” says Inês. “When we applied for the internships, everyone was working remotely, whether they liked it or not.”

Reviewpad is a fully remote company. It was built this way by design. Whenever health-related restrictions are lifted, little will change in regards to its day-to-day operations. Neither Cheila or Inês seem to be fazed in the slightest by this.

“A few of the companies we could’ve applied to are now working in offices again. I did want that experience when we started out. If I had gotten the chance, I would’ve picked it. Now, I’ve realised being in a healthy working environment is what’s truly important”, continues Inês.

Both have fully adapted to working in a remote environment, and both are thriving. They are students of the Porto University Faculty of Sciences (FCUP - Faculdade de Ciências da Universidade do Porto), and they came to Reviewpad in very different circumstances.

### One internship becomes two

![Cheila Alves](/posts/images/Portrait-SquareCheila.jpg)
_Cheila Alves_

“I actually had offers from several companies”, says Cheila, “and I picked Reviewpad because of the interview. The company felt more dynamic, more comfortable. It really did feel different to me.”

Inês was interviewing for the same spot as Cheila, and she wasn’t picked. But that wasn’t because the company felt she was any less valuable.

![Inês Silva](/posts/images/Portrait-SquareInes.jpg)
_Inês Silva_

“I wasn’t entirely sure I was up for it. I loved the theoretical aspect of studying. I wanted to stay in academia for a little longer. I wasn’t sure I was ready to just start working, since the practical aspect of our courses is lacking. Marcelo (Reviewpad's CEO) picked up on that immediately, and he got in touch with me to create a position within the company that would suit my strengths. He just immediately understood what I was about. I couldn’t waste that opportunity”, she says.

### Getting started

So how does one go about getting people started in a software company, when we don’t have an office, and the company doesn’t even have fixed hours?

It starts with **trust**, and it ends with **accountability**. Both Cheila and Inês are closely shadowing one of the senior elements of the company, Tiago Ferreira (front-end navigator) and Adriano Martins (COO) respectively. They are the ones that set their tasks in the beginning, and evaluated their progress. In just a few months, however, both have become highly independent.

“We do have hours in which we must be available, and of course we have to deliver on our work, but I am now working on a larger project that I am in charge of. I don’t have specific tasks with specific deadlines”, says Inês. Cheila has a similar experience. She has been given access to the larger codebase, and she can choose what to work on at any given time. They are treated by their mentors as colleagues, not underlings.

“I don’t think a lot of companies would embrace us in the way Reviewpad has. I’m in touch with friends who are working elsewhere, and they are stunned with how we are treated”, says Cheila.

> A lot of interns are just hired to do the busywork that no one likes. We feel we are part of the team.  
> &nbsp;  
> _- Cheila Alves_

### Teams for the digital era

Because that’s one of the key aspects of building a remote company. Understanding how you can build a team that’s solid, and that feels a strong team spirit, without being physically present for each other.

“I had some stuff left over for school that I still had to get to”, says Inês, “and I feel like that was when I really understood how this remote thing could work. My time was my own, and I could manage my tasks very effectively while always remaining online and available. I was given the freedom to do that, and everyone was very understanding. If I was inside an office, I could’ve never managed it as well”, says Inês.

Reviewpad is a company founded by friends, and most of the people who work there see each other as family.

“Sometimes it’s the little things, like when the company sent us some merchandise and games directly to our homes. It made us feel appreciated”, says Cheila.

### The future is theirs

> I want to continue working in UX and UI. I didn’t even realise all you can do in these areas. We don’t focus on them at all in university.  
> &nbsp;  
> _- Inês Silva_

“I have always wanted to work in web development. I knew it from the get-go, and now I am even more sure”, finishes Cheila.

While no one knows what the future holds after an internship, both Cheila and Inês have changed their views on what remote work can be, team spirit, and even the areas they want to specialise in.

At the end of the day, that’s what it’s all about.



_Nowadays, GitHub is the home of open source. The_ [_adoption of pull requests has been incredible_](https://reviewpad.com/code-reviews-need-to-outgrow-pull-requests/)_. But what happens when we move away from open source? What is the most widely used code review tool? To get a better understanding, we took a deep dive into_ [_JetBrains Developer Ecosystem Survey 2020 data_](https://blog.jetbrains.com/blog/2020/10/01/developer-ecosystem-2020-raw-survey-data-ready-to-be-explored/)_._

We analysed the data from 23589 respondents of the survey [_JetBrains Developer Ecosystem Survey 2020_](https://blog.jetbrains.com/blog/2020/10/01/developer-ecosystem-2020-raw-survey-data-ready-to-be-explored/). This survey is **very comprehensive**. The PDF with the questionnaire alone is **168 pages** (!!). Hats off to JetBrains for this huge accomplishment and providing the data for others to use.

**The big three are dominant**

As expected, the data suggests the majority of developers are using the big three (Bitbucket, GitHub, and GitLab) for code reviews. Our analysis shows that 90% of developers that use more than one code review tool are using **both** GitHub and GitLab. The latter has a slight edge. What else can we learn?

We focused on the following questions, related to employment status, job role and code reviews:

1. What is your employment status?
2. Which of the following best describes your job role regardless of the level of your position?
3. In which kinds of activities are you involved?
4. Which of the following tools do you regularly use?
5. Which tools do you use in your company / organization for Code Review?

### A look at the key statistics

From the 23589 respondents of the survey:

- 82% regularly use code hosts
- 59.5% have activities that include code reviews
- 12.2% regularly use code review tools
- 18.2% regularly use code reviews tools given than their activity includes code reviews

The big gap between people that have activities that **include** code reviews and those that **regularly use** code reviews helps us figure out which numbers we can use to deal with the untapped market of code reviews. The market will necessarily grow as more and more teams start both doing them and using specific tools to do so.

### Who is doing code reviews? 

#### Employment status

Not surprisingly, the vast majority of people in the survey are **fully employed**. Code reviews are performed by people that are fully employed at an even greater rate. This is also not surprising.

Check out the following table that details this information with the percentage of respondents per employment status and the percentage whose main activity includes code reviews.

<Table 
  headers={['Employment Status', 'Percentage (%)', 'Doing Code reviews (%)']}
  data={[
    "<b>Fully employed by a company/organization</b> | 65.91 | 78.40",
    "<b>Student</b> | 12.59 | 4.50",
    "<b>Working Student</b> | 6.98 | 4.82",
    "<b>Self-employed</b> <i>(a person earning income directly from their own business, trade, or profession)</i> | 5.86 | 5.48",
    "<b>Freelancer</b> <i>(a person pursuing a profession without a long-term commitment to any employer)</i> | 4.80 | 3.97",
    "<b>Partially employed by a company/organization</b> | 2.74 | 2.24",
    "<b>Other</b> | 0.83 | 0.56",
    "<b>Retired</b> | 0.28 | 0.05",
  ]}
/>

#### Job role

We often hear that code reviews are performed by more senior developers. The data **corroborates this intuition**, as the percentage of senior developers doing code reviews is greater than those who aren’t doing them. The opposite occurs for junior developers. This indicates that not all junior developers are regularly involved in code reviews. The numbers are on the following table:

<Table
  headers={['Job Role', 'Percentage (%)', 'Doing Code reviews (%)']}
  data={[
    "<b>Senior</b> | 41.95 | 49.74",
    "<b>Middle</b> | 35.12 | 34.69",
    "<b>Junior</b> | 18.88 | 13.26",
    "<b>Trainee</b> | 3.36 | 1.63",
    "<b>Other</b> | 0.69 | 0.68",
  ]}
/>

### Code review tools usage

The following plot shows the ranking of code review tools per usage.

<BarChart
  yAxisLabel="Number of users"
  sets={[
    ' : 26, 31, 41, 51, 52, 57, 110, 126, 161, 187, 217, 248, 589, 628, 657'
  ]}
  categories={[
    'AWS CodeCommit',
    'Collaborator',
    'Helix Swarm',
    'None',
    'Phabricator',
    'Review Board',
    'Custom tool',
    'Other',
    'Gerrit',
    'Upsource',
    'Azure DevOps',
    'Crucible',
    'Bitbucket',
    'GitHub',
    'GitLab',
  ]}
/>
_Note that it is possible for a developer to be using more than one tool._

Developers are doing code reviews with the code hosts interfaces of Bitbucket, GitHub, and GitLab. These three tools combined represent more than 50% of all tool usage. About 9% of the developers do code reviews without code review-specific tools or, of course, using custom tools.

The last thing we did was look into the developers that regularly use more than one code review tool. 

**We found out that 1 out of 4 developers that do regular code reviews use more than a code review tool.**

Initially, we thought that these were developers that were using a major code host and a dedicated code review, for example using GitLab and Gerrit. 

**It turns out that 90% of those developers actually use both GitHub and GitLab.** 

Assuming that a lot of time spent in GitHub/GitLab is in the code review interface and considering that GitHub is the home of open source, one wonders if more of the teams that are doing code reviews are paying for GitLab than GitHub.

[Perhaps GitLab really is growing faster than GitHub](https://twitter.com/sytses/status/1182692575599366144?s=20).



_It’s part of our nature to optimise every single process and code reviews are not an exception. If you are part of a team doing code reviews, at some point someone will want to measure some aspects of the process. It’s important to acknowledge that part of the_ [_ROI in code reviews_](https://reviewpad.com/why-you-need-to-be-doing-code-reviews/) _is not directly measurable. Identifying the right metrics to monitor and start discussions around code reviews optimisations is problematic for developers and engineering leaders. Here are some best practices that we find work well in practice._

In our experience with Reviewpad, people look at metrics for two reasons:

1. They have the feeling that bottlenecks exist in the process and want to identify potential reasons;
2. They want to monitor the quality of their processes.

When it comes to code reviews, the metrics selected to deal with these scenarios are deeply connected to the underlying software development process and team organization. 

### Code reviews should always have specifications

Code reviews should always be associated with your project management tool through issues or tickets. You want to keep them correlated. If you are to understand where bottlenecks lie, you need to look at metrics in both areas. This is how you identify if the execution and/or the specification of a task are the issue.

This is why the first metric you should have is the **percentage of code reviews without linked issues**. 

Issues and code reviews typically contain project-specific labels that describe if they are new features, bug fixes, or other improvements. If you want to drill down, split reviews down by label and consider the percentage of code reviews without linked issues **for each one**.

It is true some teams find it acceptable to **not label** some code reviews. As a best practice, you will want all bug fixes to be properly documented so that you avoid future regressions.

If you are following a model of [continuous code reviews](https://reviewpad.com/continuous-code-reviews-are-the-way-to-go/), the recommended method is that you create an issue and a corresponding draft pull request. This allows you to promote continuous discussion about the specification and code development.

### Optimise for your release cycle

If your team needs to release multiple times a week, or once a month, your team organization will reflect it. As a result, the metrics that matter to you will also change in a fundamental way. 

For teams that use pull requests and want to minimize their release cycle, a standard metric to have is the **average time to merge pull requests**. We consider this number as the average time a pull request is opened until it is merged for a given release cycle. This metric is more valuable when you have an _a priori_ fixed release cycle (say every 2 weeks) and you want to see if pull request merge is blocking your release. 

There is one issue with this method, which is a verified tendency to merge a lot of pull requests **when the release deadline approaches**.

We find it more informative to measure the **distribution of pull requests merged over time** to understand if the workload of the team is evenly distributed.

### Minimise conflicts

There is a lot of information out there about how important it is to minimize the size of a pull request and the time to merge. Everyone is trying to avoid the same fundamental problem. Whenever you work in collaboration, you have to deal with **conflicts.** 

Let’s face it: it is extremely annoying for anyone to spend a whole morning fixing git conflicts because someone else changed the codebase in a way that impacted their work.

If there is a metric you should be paying attention to, that certainly is the **number of conflicts in pull requests.** Make sure you monitor the distribution over time during the release cycle and ensure that it is always close to zero.

The size and duration of a pull request **don’t matter** as long as two things are true:

- You are doing incremental and continuous reviews;
- You’re not introducing potential conflicts with other team members. 

Enforcing size constraints in pull requests to avoid conflicts **is a kind of developer micromanagement technique**. As a side effect, you will also end up with a pipeline of atomic pull requests wasting continuous integration resources and putting pressure on people to context switch to review them. 

### Share the review load and  
measure communication

Even if your absolute priority is to lower the release cycle, you don’t want to ship low quality products. **The best way to increase the quality is through code reviews**. There are three key metrics that can help understand the quality of code reviews:

1 - **Average time before reviewer assignment**

Two facts:

- There can’t be code reviews without reviewers;
- A pending review is helping no one.

Nowadays, broadcasting on Slack that a pull request is ready for review is considered spam (and, to be fair, it’s hard to argue that it isn’t). Having a system picking you as a reviewer for whatever reason is a really good way to minimize this number without actually adding practical value. 

When you practice continuous code reviews, you mitigate this problem by opening a draft pull request and not neglecting to immediately assign a team member to work with you as a reviewer.

2 - **Distribution of reviews per team member**

This distribution indicates if the review load is being evenly distributed. The team must feel code reviews are a part of the software development process. That means making them **continuous** and the distribution **fair**. If only one team member, typically the team lead or the principal developer, is in charge of the vast majority of the reviews, you are **creating a bottleneck** to merge. As a consequence, either this person will be spending their days doing reviews or the quality of the reviews will decrease with time. A good way to overcome this problem is to have two reviewers to break the review down between them.

3 - **Distribution of comments per review**

**Reviews are dialogues, not checklists**. Deep diving into the quality of the comments in the reviews is an excellent way to understand if the reviews themselves are any good. If most reviews have very few comments, this is an indication that either the **actual** review is taking place elsewhere (which might not be properly documented) or not happening at all. Even if you have a strong culture of pair programming, you will still [benefit from code reviews](https://twitter.com/marceloabsousa/status/1382643884333924359).

### Measure groups, not individuals

If you are an engineering manager, the only metrics you should pay attention to are at the team level. As with code reviews, the value of a code change is not linear. Any metric that will be focused on an individual will be biased — maybe they only performed one code review this week but the review suggested a change that saved the company a lot of money. We recommend nurturing a culture of continuous improvement where individuals can measure themselves and keep metrics used by engineering leaders at the team level.



_One of the major roadblocks for quality code reviews is how their complexity can quickly get overwhelming. The three major factors of this increasing complexity are well-known: the number of changes; the maturity of the codebase; the expertise of the reviewer. Of course, you also have time constraints that amplify this complexity._
&nbsp;  
&nbsp;  
_If we don’t figure out techniques and workarounds for these issues, we are hindering the full benefits of code reviews._
&nbsp;  
&nbsp;  
_**We have made it our mission to tackle this complexity.**_

### It is all about the process

In a recent [Harvard Business Review article](https://lnkd.in/db7nNuA), David De Cremer and Garry Kasparov write about **_Augmented Intelligence_** and how the synergy between artificial intelligence and human intelligence can lead us to new levels of productivity.

> Weak human + machine + better process was superior to a strong computer alone and, more remarkably, superior to a strong human + machine + inferior process.  
> &nbsp;  
> _- Garry Kasparov_

The key aspect for success is the **process** by which humans and machines collaborate. This is our philosophy for Reviewpad. So what’s this process for us?

### Continuous code reviews are the way to go

We are stating this **outright**. We are very much continuous code review evangelists.

We believe it is the practice that best allows us to avoid the single greatest hurdle in code reviews, which is its mounting complexity. In this article, we will explain why. We will also explain what we mean, because:

### Continuous can mean different things

> Context switching incurs a lot of overhead. (...) In a continuous code review you don’t have this problem. Your pair is right there giving you feedback as you go. From little things like variable naming to bigger things like noticing a bug or telling you about an existing class you should use. The code is updated in real time.  
> &nbsp;  
> [_- Allan Stuart on Continuous Code Reviews_](https://www.pluralsight.com/tech-blog/continuous-code-reviews/)

His solution implies two developers working on the same code at the same time. One of them actually creating original code, and the other reviewing live.

This is possibly as close to _actually_ continuous as you can possibly get, but it’s not the only way to achieve this effect.

Not every company can assign two developers to the same job at any given time. Also, not every company has a pair like [Jeff Dean and Sanjay Ghemawat](https://www.newyorker.com/magazine/2018/12/10/the-friendship-that-made-google-huge). And the truth is, we are still understanding how pair or mob programming is adapting to remote environments.

Reviewpad is being designed to provide the same sort of **collaborative and continuous mindset** without this multiplication of effort.

The analyses it provides address the aspects where people are more error-prone. **It’s a tool that augments human intelligence.**

We believe in **breaking things up into tiny parts.** We also know that you don’t need pull requests to achieve that.

### Our process: code review centric development

It is a well-known practice in software development to separate work into sprints and do daily syncs. In these daily syncs, you have a _squad_, which typically includes developers, designers, and a product owner. Someone puts up a board of issues from Jira (or some other project management tool) and the entire team goes over it.

This is a problem.

Miscommunication between the description of a Jira task and the description of a pull request happens all the time.

We propose an **inversion of control**. After a written high-level specification is shared with a developer, it is up to them to specify the intent of a particular changeset for development. The product owner must then understand what fraction of the high-level task these changes amount to, and adjust if necessary.

Why is this preferable? It significantly reduces **specification overhead** by product owners who do not have (or don’t have the time to acquire) a good understanding of the codebase. It also reduces artificial pressure on development by reducing the guesswork regarding the completion of a task.

### Reviewing ideas will save you ages

Think of it as architecture. You’re building a castle. When do you bring in someone to check your work? **When the castle’s already built may be a tad too late**.

The idea that code reviews should only be about fixing mistakes is misguided. Code reviews should be about creating better, more efficient, code. **If an idea is misguided, or flawed, then it hardly matters whether the code brings it to life perfectly**.

Reviewers should be a part of the process from the get-go.

**Code reviews** are the central piece of this approach and that’s why we call it **code review centric** development.

### How does it work?

As soon as a developer plans to change something in the codebase, the first step is to open a code review stating the intent of the changes and assigning reviewers. This signals to the rest of the team what this person is working on and how we can help them achieve success **continuously**.

Some of the benefits we have experienced in the past months are:

- **reduced miscommunication**, because we are asking early technical and non-technical questions about the approach;
- **faster development,** because we are regularly checking changes to see the progress;
- **more shared knowledge**, because of more frequent and better feedback;
- **fewer integration problems**, because we detect potential future conflicts.

Reviewpad was built to facilitate this type of development. Instead of forcing developers to look at a kanban of issues (which relate to the product owner, but not them), we use a dashboard of code reviews to easily communicate **real** progress and potential pain points.

The length of the review is as long as the developer **wants it to be**, since feedback is given on a continuous basis.

Instead of forcing developers to switch between contexts a dozen times to complete a code review, you can do reviews that are quicker, more focused, and kinder to your brain. 

### Draft Pull/Merge Requests are an excellent starting point

![](/posts/images/draft-pull-requests-1024x590.jpg)

The adoption of code review-centric development is going to take time. This is why Reviewpad seamlessly integrates with GitHub and GitLab. 

An excellent starting point  to this approach is to use WIP or [draft pull requests](https://github.blog/2019-02-14-introducing-draft-pull-requests/). 

This feature allows you to create a draft of your pull request before you make any changes at all. And you can immediately assign a reviewer. **Ideally, more than one.**

If you do this diligently (and we recommend making at least two checkpoints in your draft PR a day), any reviewer who is available will be able to come in whenever they’re notified of changes, and provide you with more feedback. This way, you and your team can start feeling the benefits of continuous, iterative code reviews. 

Reviewpad’s integration of the code host draft pull/merge requests, alongside its sophisticated communications arsenal means that it’s possible and easy to start the review process earlier. In the **brilliant idea** stage.

We recommend that developers draft every pull request they do as soon as they think it up. **Before they even touch the code**. Again: If you clearly signal your code changes before they are even made, a reviewer will not only know what they’re looking for, they’ll be able to comment on your intention as well.

### Async, yet continuous

If you take this iterative approach and take full advantage of the draft PRs, your reviewer doesn’t need to be working the code at the same time as you. They will be notified as soon as you have your idea, and they will be able to provide feedback on it much earlier.

Still, you need to help them! They will only be able to understand changes that much **quicker** if your intent is laid out clearly. If they know what they’re looking at, they will have an **easier** time spotting mistakes, or code that quite simply doesn’t do what it’s supposed to.

This back and forth between a developer and a reviewer is the perfect way to go about it. It’s async, yet continuous. We’re working on the right set of features to make this process easy and enjoyable.

If reviews are done this way, then they will effectively keep up with development. Over time, your codebase will **never build up unreviewed**, regardless of how mature it is. Conversations between developers and product owners will feel more natural and transparent. In the long-term, your team will have the right mechanisms to re-enforce trust and ownership - and when that happens, you have coding superpowers.

* * *

If you are interested in Reviewpad or hearing more about code review centric development [talk with us](https://reviewpad.com/slack)!



_Context switching, not fear, is_ [_the mind-killer_](https://www.youtube.com/watch?v=A54yfyi00dI&t=77s)_. One of the main obstacles to quality code reviews is the simple fact that developers have a lot to do. The cost of going back and forth during code reviews and between code reviews and other tasks is standing between us and excellence._  
  
_**But we can help.**_

### We are letting context switching get in our way

In several ways, actually. There are several types of context switching, and they are all harmful in their own specific manner.

One of Reviewpad's main goals is to reduce the amount of context switching you are doing today.

So, what exactly do we mean by context switching?

### Our brains don’t excel at multitasking

A bold claim, right? But it’s true. [Cognitive load theory](https://link.springer.com/article/10.1023/A:1022193728205) is a useful framework to understand how our brain processes information. There’s a [lot](https://www.mindtools.com/pages/article/cognitive-load-theory.htm) [of](https://www.sciencedirect.com/topics/psychology/cognitive-load-theory) [science](https://www.bbc.com/worklife/article/20201103-cognitive-load-theory-explaining-our-fight-for-focus) about this.

The basic idea is that we store knowledge in the long-term memory of our brains, yet we are only consciously aware of a chunk of this memory. The so-called **working memory**. In other words, our brains (much in the same way as a computer that has limited RAM) can only store and manipulate a certain amount of information at any given time. If you exceed that amount, you generate errors, stereotyping, or both.

No two brains are the same. However, according to [Miller’s law](https://en.wikipedia.org/wiki/Miller%27s_law), an average human can only concurrently store and manipulate seven different elements in their working memory. This is what we call **cognitive load**.

Whether the [magic number](https://en.wikipedia.org/wiki/The_Magical_Number_Seven,_Plus_or_Minus_Two) is 7, 9 or 4, several studies have suggested that humans are particularly poor at complex reasoning using totally new information in working memory. Still, this memory is fundamental to form knowledge that will be stored in long-term memory.

According to cognitive load theory, working memory load can be affected by three kinds of cognitive load.

- **Intrinsic cognitive load**: How difficult the subject matter actually is. (2+2 is easier to understand than E=mc2).
- **Extraneous cognitive load**: How much the format is helping or hindering you. (It’s easier to read in your native language than your second language).
- **Germane cognitive load**: How efficient you are at structuring your thoughts. (A trained mathematician will learn new math faster than an equally skilled linguist).

What happens when you’re reading a novel and you **stop** to reply to a tweet? Even if you were paying the utmost attention to what you were reading, you will replace whatever elements were in your working memory. When you get back, you will have to reread a couple of words, maybe a couple of sentences, to find your place. It may take you a couple of minutes to refocus on what you were doing.

This is pretty much how we’re doing code reviews **at all times**.

### Context switching hurts all developers

We have [context-dependent memories](https://www.alleydog.com/glossary/definition.php?term=Context+Dependent+Memory#:~:text=Context%20dependent%20memory%20refers%20to,the%20original%20encoding%20and%20retrieval.). We have, as we mentioned above, limited cognitive loads. Modern work environments aren’t ideal for total focus. Especially in the kind of fast-paced environments that most developers find themselves in. Context switching is constant. Email, Slack, IDE, Jira, Teams, Zoom, meetings, clients. Every time you go from one environment to another, your brain needs to gather context so it can refocus. The effects of this [are known](https://www.linkedin.com/pulse/context-switching-developers-paul-graham/), and they’re not ideal.

Code reviews, in particular, are heavily affected by this.

### We need to prioritize code reviews in our work

Code reviews often **are** context switches. If a developer is squeezing code reviews into a busy schedule, then the code review itself will constitute a switch in context.

So why would we prioritize code reviews?

Shouldn’t we let code review requests accumulate and then handle them all at once?

Absolutely **not**.

As I have discussed in [my previous post](https://reviewpad.com/why-you-need-to-be-doing-code-reviews/), the complexity of reviews increases exponentially with the number of changes, the maturity of the codebase and the expertise of the reviewer. For a team to move forward with a project with a lot of unreviewed code is **a costly thing to do**. It will lead to mistakes and bugs that will be costlier to fix with every passing day.

It goes without saying that for any elements of your team to be stuck waiting for code reviews **isn’t ideal either**. Even if they do have other tasks they can get to in the meantime, that’s just extra context switches.

There are solutions for this. Greg Sanford, from Slack, advocates for checking (and resolving) your code review requests [whenever you interrupt work](https://medium.com/@9len/on-code-review-16ea85f7c585). Allan Stewart, of Pluralsight, advocates for [continuous code reviews](https://www.pluralsight.com/tech-blog/continuous-code-reviews/), with developers working in pairs. We’ll write about how we cope with it in a future post.

Teams need to find strategies to reduce the amount of **context switching between development and code reviews**.

But that's not the only kind of context switching.

### Context switching between tools during review is hell

And that’s where we come in.

When developers are doing code reviews, they are using **an excessive number of tools**.

Slack, or another **messaging app**, will be there, to get a notification and reach the original author of the code.

Then you move to a **review interface** to understand the differences and provide feedback. This typically will be the Web UI of GitHub, GitLab, Bitbucket or some other code host.

After that, there will be some juggling with a **project management tool**, such as Jira, to understand the scope of the changes, and with the **IDE** to understand some parts of the code.

This is a veritable Babel tower of context switching. Reviewers will be switching between a series of environments to help **understand the code and its scope**. And then, they will switch between tools to **communicate the review**. A typical code review requires the developer to switch context endless times and none of these tools was actually designed from the ground-up for the review process. What ends up happening is that you spend a big chunk of your review time context switching. After a while, your brain will be screaming “LGTM”.

This is detrimental not only to the review itself but to all the other tasks being carried out alongside them. Can you imagine what happens to your short-term memory with that much extraneous cognitive load? It’s not a coincidence that you get a coffee before and after doing a complex review.

### Here’s how we’re fixing it

I acknowledge that **context switching between tasks** isn’t something Reviewpad can fix. That’s a question of team culture that companies have to tackle (we hope they will!). But we can help with both the tools used to **understand the code** and those used to **communicate**.

**Code reviewers shouldn’t be switching between these many tools**. At Reviewpad, we believe that your browser can replace most of the suite of apps we described above.

We are integrating the entire review cycle into **one tool**.

First of all, you shouldn’t need an IDE anymore. **IDEs are for coding** \- that’s a different cognitive task than understanding code or suggesting edits in a review. Reviewpad will provide you with the semantic context that you need to understand the code changes and identify functional bugs and security vulnerabilities. You will also be able to review changes easily by iteration (push or commit) to break down complex reviews into manageable chunks. We’re designing Reviewpad while aware of the limits in cognitive load so that you don’t feel overwhelmed with information.

How about **communication**?

Reviewpad provides new ways of giving and receiving feedback during reviews. It achieves this without comments being lost (because you modified a line of code) or having to go into a meeting to understand the overall structure of the changes. Everything is integrated with current code hosts so that you can have a smooth transition process.

If you are facing problems with code reviews, please share them with us - we’re here to help.



_Hi there! In_ [_our first article_](https://explore.dev/2020s-pull-requests-part-i/) _we showed how many pull requests were closed this year on 50 known organizations and projects, and we looked into the duration of those pull requests._

For our second article, we decided to do a **deep dive into the merged pull requests from 283 034 starred public projects**.

### Data Selection

We will continue with the data from the [GH Archive project](https://www.gharchive.org/) from **January to March of 2020**, and the same initial selection of **~2.6M merged pull requests**. We collected for each pull request (PR):

- The name of the project 
- The username of the GitHub user that merged the PR
- The number of stars in the project
- The duration (closed - opened time)
- The number of comments

To recap from last week, here’s a summary of the data:

<Table 
  headers={["Timeline of Data", "Number of Pull Requests", "Number of Projects", "Number of Organizations"]}
  data={[
    "Jan'20 - Mar'20 | 2 631 366 | 283 034 | 153 688"
  ]}
/>

### Analysis

This week we’ll **examine this PR data at the project level**. For that reason, we started by aggregating the data per project. 

Regarding the statistics, we knew that the number of projects is quite high and there’s a huge variety of activity in these projects. Since we wanted an overview that could be easy and fun to understand for all projects, we decided to consider averages and [percentiles](https://en.wikipedia.org/wiki/Percentile).

#### Stars, Pull Requests and GitHub users

The following table presents the statistics for the number of stars, pull requests and GitHub users on all projects. For the number of stars, since it could be different between pull requests, we considered the stars of the project from a random merged pull request.

<Table 
  headers={["", "Number of Stars", "Number of Pull Requests", "Number of GitHub Users"]}
  data={[
    "Average | 204.7 | 9.3 | 1.4",
    "10th Percentile | 1.0 | 1.0 | 1.0",
    "20th Percentile | 1.0 | 1.0 | 1.0",
    "30th Percentile | 2.0 | 1.0 | 1.0",
    "40th Percentile | 3.0 | 2.0 | 1.0",
    "50th Percentile | 4.0 | 2.0 | 1.0",
    "60th Percentile | 8.0 | 3.0 | 1.0",
    "70th Percentile | 18.0 | 5.0 | 1.0",
    "80th Percentile | 48.0 | 8.0 | 2.0",
    "90th Percentile | 190.0 | 18.0 | 2.0",
    "95th Percentile | 581.0 | 36.0 | 3.0",
    "99th Percentile | 4005.3 | 117.0 | 7.0"
  ]}
/>

The average number of stars across all projects (205 stars) is higher than we were anticipating considering the number of projects. Looking at the percentiles we can get more insights about the distribution. We observe that the median (50th percentile) is only 4 stars and at least 90% of the projects have fewer stars than the average. **So, if you care about the stars on your project and your project has more than 190 stars: congratulations you made it to the top 10% starred public GitHub projects!**

Considering that the first complete week of April was Week 15 of 2020, the average number of merged pull requests this year is actually high (9.3 in total or 0.7 merged PRs per week). On the other hand, at least 80% of the projects are below the average. A median of 2 pull requests tells us that **50% of the projects merged at most one PR every 7 weeks**. 

We know that a lot of public GitHub projects are the hard work of a small group of people. As an estimate of the team size in these projects, we consider the number of users that merge pull requests. The average of 1.4 users per project shows that a lot of these projects are still likely to have a single main leader. **Assuming that mature open source projects have teams with more than 3 leading members, at most 5% of the public GitHub projects (~14152 projects) would be in this category**!

#### Duration

Extending the results from [our previous post](https://explore.dev/2020s-pull-requests-part-i/), we computed the duration of the 2.6M pull requests and aggregated them per project. For the list of PR durations per project, we computed the average, 50th, 90th and 99th percentiles. In the following table we present the average and percentiles across all projects. The table can be hard to understand as it presents nested information. For example, the cell in the second row and the first column (0.01 hours) is the 10th percentile of 283 034 values, where each value is the average of the PR durations for individual projects.

<Table 
  headers={["", "Average Duration (hours)", "50th Percentile (hours)", "90th Percentile (hours)", "99th Percentile (hours)"]}
  data={[
    "Average | 362.19 | 683.75 | 589.02 | 312.73",
    "10th Percentile | 0.01 | 0.01 | 0.01 | 0.01",
    "20th Percentile | 0.13 | 0.19 | 0.17 | 0.04",
    "30th Percentile | 1.35 | 2.30 | 2.00 | 0.27",
    "40th Percentile | 6.58 | 14.01 | 12.03 | 1.33",
    "50th Percentile | 17.94 | 40.34 | 32.80 | 5.26",
    "60th Percentile | 41.85 | 104.06 | 87.14 | 15.59",
    "70th Percentile | 91.56 | 248.36 | 195.29 | 36.55",
    "80th Percentile | 213.50 | 601.07 | 467.93 | 106.75",
    "90th Percentile | 690.03 | 1698.95 | 1395.04 | 472.50",
    "95th Percentile | 1631.81 | 3194.42 | 2748.21 | 1432.51",
    "99th Percentile | 6173.70 | 10397.11 | 9230.97 | 5998.52"
  ]}
/>

The average of the average durations across all projects is 362.2 hours (~15 days) which is not far off from 309.3 hours (~13 days) -- the average over the 50 known projects we analyzed last week.

Looking at the percentiles over the projects, we see that the **durations grow exponentially**.  It means that some projects have a lot more activity than others -- for example, **50% of the projects have pull requests with an average duration of less than one day** while **10% of projects have pull requests with an average duration of around one month**!

#### Comments in Pull Requests

Finally, we analyzed the comment activity in the pull requests. GitHub has two main types of comments associated with pull requests shown in the conversation tab:

1. **Pull request comments**: these are single comments on the file diff between the two branches or general comments in the pull request.
2. **Pull request review comments**: these are comments on the file diff made during a pull request review and they show up grouped in the conversation tab when the review is finished.

We separated the analysis into two groups because we consider pull requests review comments as a representation of the code review process and all comments as a representation of the discussion of the pull request. We were curious about the percentage of pull requests that are merged without any comment activity so we also computed for each project, the percentage of pull requests without any comment or review comment.

In the following table, we present the average and percentiles across all projects.

<Table
  headers={["", "Average Comments", "50th Percentile Comments", "90th Percentile Comments", "99th Percentile Comments", "% of PRs without any Comment", "Average Review Comments", "50th Percentile Review Comments", "90th Percentile Review Comments", "99th Percentile Review Comments", "% of PRs without any Review Comment"]}
  data={[
    "Average | 1.00 | 0.66 | 2.37 | 3.34 | 0.74 | 0.51 | 0.26 | 1.46 | 2.25 | 0.92",
    "10th Percentile | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0.69",
    "20th Percentile | 0 | 0 | 0 | 0 | 0.38 | 0 | 0 | 0 | 0 | 0.97",
    "30th Percentile | 0 | 0 | 0 | 0 | 0.67 | 0 | 0 | 0 | 0 | 1.00",
    "40th Percentile | 0 | 0 | 0 | 0 | 0.90 | 0 | 0 | 0 | 0 | 1.00",
    "50th Percentile | 0 | 0 | 0 | 0 | 1.00 | 0 | 0 | 0 | 0 | 1.00",
    "60th Percentile | 0.15 | 0 | 0.80 | 0.97 | 1.00 | 0 | 0 | 0 | 0 | 1.00",
    "70th Percentile | 0.74 | 0 | 1.00 | 1.00 | 1.00 | 0 | 0 | 0 | 0 | 1.00",
    "80th Percentile | 1.08 | 1.00 | 2.60 | 2.98 | 1.00 | 0.07 | 0 | 0 | 0.91 | 1.00",
    "90th Percentile | 2.75 | 2.00 | 6.50 | 8.46 | 1.00 | 1.17 | 0 | 3.80 | 5.35 | 1.00",
    "95th Percentile | 4.80 | 3.00 | 12.10 | 16.98 | 1.00 | 2.84 | 1.00 | 8.55 | 12.74 | 1.00",
    "99th Percentile | 12.00 | 9.50 | 31.00 | 48.68 | 1.00 | 9.00 | 6.00 | 25.28 | 40.59 | 1.00"
  ]}
/>

We were surprised to see such low numbers in the overall comment activity on pull requests:

- **At least 50% of the public projects don’t have a single merged PR with any comment**
- **The average of the average comments across all projects is 1**
- **The average of the percentage of PRs across all projects without a single comment is 74%**
- **Only 10% of the projects have an average higher than 2.75 comments per PR**

The activity regarding reviews comments is even lower:

- **At least 70% of the public projects don’t have a single merged PR with any comment in the PR**
- **The average of the average comments across all projects is 0.5**
- **The average of the percentage of PRs across all public projects without a single review comment is 93%**
- **Only 5% of the projects have an average higher than 2.84 comments per PR**

This data shows that the process of pull request reviews is still restricted to a very small percentage of public repositories. It will be interesting to understand how much automation is involved in this comment activity. If the presence of code reviews is an indication of high code quality, we hope that this percentage includes the mature open-source projects used by thousands of developers on a daily basis. In any case, we hope to see these numbers going up as we recompute them in the future. If you have insights on how these results generalize to private repositories feel free to reach us!

Next week we’ll deep dive into a set of projects -- let us know if you have any requests!


Faster and Safer
Pull Requests

Next Generation Pull Requests

Blazingly Fast Reviewer Assignment

Advanced Merge Protection Policies

Great Developer Experience For Everyone

Save Your Engineering Team Valuable Time

Channable x Reviewpad

Disrupting software developers collaboration

Faster and SaferPull Requests