One of the things I really enjoy about working in the Envato Marketplace development team is the opportunity to learn and to teach via pull requests (PRs) and code reviews. Although the main reason we use pull requests is to obtain approval for production deployment, a useful indirect benefit is the transfer of knowledge within the development team.
Pull Request Lifecycle
In the development team we use GitHub to manage our code and the pull request functionality is a large part of our process. Every change in the codebase is put up for review on GitHub before it is merged into the master codebase and deployed to the web servers.
The main reason we use PRs is to get other developers’ approval for the code to go into production. This approval is usually given via a “plus one” (+1). It is up to the developer to decide how many +1s they need before they merge and deploy their code. Generally, the more large and complex the piece, the more +1s are required.
How does one get a +1? When a developer comments with a +1, they are saying “I am willing to support this code in production”. It must meet their idea of quality. From the overall architectural decisions made in your code, right down to whitespace formatting - everything is up for comment.
This graph is of our PR comments, the thickness of the lines reflect the number of comments from one developer to another’s pull request.
However, what it represents is of more importance. It represents knowledge sharing, teaching and learning.
We are now approaching pull request number 6000 on our main Marketplace codebase with many comments on each - in effect creating a large database that provides a platform for knowledge transfer. Outlined below are some of the ways we use pull requests comment at Envato to enhance learning and teaching.
How we use pull requests to share knowledge
At Envato, PRs are not just a request to merge code, they can and do have many more purposes. I’ll outline a few of many below…
1. Explaining the purpose of the code
One of the most important parts of a PR is to outline the purpose of the code upfront and any relevant assumptions. This is useful to reviewers of the code as it allows them to pick up any issues related to how the code relates to the bigger picture, rather than mere technicalities with the code itself.
2. Collaborating on our engineering culture and coding guidelines
Discussions in comments can form the nucleus of future coding guidelines, such as this suggestion from Warren on a piece of code that contained some meta programming.
I would say as a general rule, we should favour explicit, readable solutions over meta-programming - it’s more maintainable over the long term.
3. Asking Questions…
Asking questions is a great way to provide feedback.
Asking a question like this allows for open discussion. It is a suggestion, but in a question format. Very diplomatic. It is important to be able to handle such detailed and sometimes pedantic feedback, without taking it personally.
However, we still have to be pragmatic and ship code.
4. Manual Static Analysis
Forgot to close a bracket, didn’t use that variable you assigned? No worries, we have Steve.
5. Suggesting alternative ways of doing things
Ruby is a fun language to write in, and there are always new tricks to learn.
This blog is powered by the Octopress static site generator, with the repository hosted on GitHub - this blog post also went through the pull request process!
7. Having Fun
Envato is a fun place to work, and pull requests are no exception. It is not uncommon to come across a GIF or two.
8. Continuous Delivery and Scale
PRs and the collaboration, discussion, and validation they allow us are an essential part of our ability to deploy over 10 times a day. Upon deploy that code will be out on the marketplace handling millions of requests a day!