Getting the best out of Github with Remote work & PRs

Github is the best platform for remote work nowadays. I'm not saying that because my company(ilegra) is a Github partner but because I deeply believe that. I always liked Github, in fact, way before my company become a partner. Anyone can use Github anyway, however just dropping code in Github won't do the trick, there are patterns and practices you can follow to the best out of Github. PR's(Pull Requests) can be great or can be a nightmare depending on how you do. I use Github since 2009(Yes, +10 years), today I want to share the trick and patterns I use working with Github with my teams in remote projects. There is no right or wrong, this is what works for me, I'm not saying this is the only way, but here we go on what I'm doing so far. This is not the first post I do about Code Reviews, this is more towards remote work but you won't check these posts out:

1. Lessons Learned and Experiences doing Code Review.
2. Business Review: The Gateway to Automation
3. Code Reviews & Design Sessions
4. Promote The Culture

GitOps and The Future but not today :-)

GitOPS is the best way we can deliver software with Kubernetes nowadays. I deeply believe in automation, however, automation and infrastructure are not the focus of this post. I will cover the remote communication and working practices which I consider key in order to make your team more efficient. 

Branch Model: Forget Git Flow

First of all, FORGET about GitFlow it sucks. A very simple reason is: It's too complex, you need tooling and really, you don't need it. I Always was a huge fan of Trunk based development or like the old-cool-kids used to call: Continuous Delivery Model, Currently, I believe GitHubFlow is the best model so far. Why? Because is simple, powerful, no extra tool needed. So I always use the GitHubFlow branch model in my projects. I know GitFlow is pretty popular with mobile guys however I still deeply believe it is too much complexity for little benefit. So just go GitHubFlow.

PR House Rules == Kanban W.I.P Limits

It's important to have PR(Pull Requests) not PR(Public Relationship) rules :D. First of all and more importantly you need to LIMIT the number of files in a PR. I like to do PR with 10 files limit, this is great for many reasons, first of all, because merge +150 files suck in many levels, second that big PRs also take more time to merge and potentially introduce more risk. Lean is all about improving the flow and reduces batch size when we limit PR in 10 files we are reducing batch sizes and making the system more reliability by carefully review the changes that get it.

10 Files are not written in stone, it could be 15 easily as long as it is not 1 or 30 files. I like 10 files because you need to consider that the engineer will need to create testes, several levels of tests like unit, integration, stress, chaos and so on and on. Also, you will ask changes, based on your changes you will end up with more than 10 files which are totally fine.

I also require folks to write some simple text descriptions of the PR. I review PRs in order so let's say we have PRs #1 #2 #3 #4 #5, I will review PR #1, them #2 and so on and on. However, IF PR #2 is good to go and PR #1 requires changes I would merge PR #2 and wait for PR #1 changes. So you should not block PRs even is there is an order(Your changes should be able to be INDEPENDENT, thats totally possible if you do your branching right).

Review Best Practices == Comunication Patterns

Comunication is key in order to make remote work out. Often engineers dont do enough context about what they are doing and about what they want from the reviewer. Even with Github notifications and BOTs some times it is not clear is the engine is done or not. So Clear explicit communication is always a good thing todo.
Open a PR

Here is a simple text template you can use to OPEN a PR. You basically mention your REVIEWER and describe what are you delivering. I like to have a simple progress bar like this is task 1/3 of the user story ID #12344 or this is story 1/3 or this is item 10/20. It's always good to know where we are in sense of the big picture. Secondly is important to highlight what's there, so what the review should expect.

Finish a Code Change

When we ask changes to an Engineer and the engineer is done, there is another important piece of comunication here, so here is a template. So you mention your reviewer and you like you did all the changes you were asked for let's say for example 3/3 changes done and you also list the changes you made, this is important because it forces the engineer to review what he did. Often it could happen to the reviewer had to REPEAT several times the same thing, which sucks and is a waste of time. So this way you make the engineering life easier and the reviewer's life easier and avoid REPEATING thigs.

Design Sessions / Docs + Slack Comunication Patterns

In order to get more of our PRs, you need to have Designs. Design is the missing discipline in software engineering. Agle never mentions much of it. Design is not an out make UML diagram for all classes of the system but to capture the essence and important aspects of the solution. What practices help you do a better design:
 1. Think before you code. Also, do a Design Session - Validation your assumptions.
 2. Make a class diagram of the most important parts of the solution
 3. Have a Strategy for Main Guideline
 4. Capture the ideas on a Design Deck or in a Design Doc.
 5. When you submit a PR link the design with it.

Remote works often mean have lots of tasks in async fashion, Which means you won't remember every decision and have a CONTEXT + Design DOC helps a lot. Also is important to use SLACK in order to let the reviewer know he was work todo. For my projects, my teams always follow a very simple pattern by doing: @Reviwer #LINK_TO_THE_GITHUB_PR the same happens when a code change is done. Why do that if Github has notifications? Well because is one last place to look. :D

Lessons Learned 

So here are the hard-core lessons learned over the years doing code reviewers and PRs reviews with Github. So here we go:

   1. Code review is not the BOTTLENECK, DESIGN is. Find ways to get the design right FIRST; You need to make sure you are following the RIGHT design otherwise code changes will be HUGE.

   2. Limit your Files(10 is ideal to me): There are plenty of reasons, faster reviews, faster merges, fewer risks, smaller merges and progress/visibility.

   3. Comunication is Key: Use consistent patterns to describe whats is done, when the changes are ready and be 100% clear and direct on the reviewer about what you want.

   4. Don't be lazy, Don't lose Track: Some folks like to CLOSE PRs and Open new PRs with changes I dont like it. Why? because I loose track of changes and context of the discussion, therefore, I dont think is a good idea to do it.

  5. GitHubFlow For The Winners: Use Github flow and create a PR branch based on your FORK, this is the simplest and effectively when to deal with code changes.  It's not a crime to create more branches if you are faster than your reviewer. Git makes easy to deal with branches.

6.  Do Retrospectives: Often retrospectives can easily be about people, which is fine, however, you need to make sure you talk about tech work as well. It's important to talk about your tech practices otherwise you won't improve it and will have always the same issues.

7. A Call or Context, Pick the Second: If everything you do needs a call, your remote work won't be productive at all, this means we are lacking alignment and design. Talking with people does not mean bad things because how are you improve the comunication with less comunication right? Right, thats correct we need to improve comunication however we not necessarily need to do it with a conf call, because a conf call is often blocking and many calls in a day kill productivity. As you have good software engineer designs(this is not UX) you can do more Slack chats and contextual discussions on github, if the questions are cleary, objective and full of context, pick context overcall because Context is king, you won't block and suck people time with calls, other people can read and might have the same issues/thoughts so you are killing several birds with one stone.

To be clear on item #7 I'm not saying you should not do conf calls, sometimes is what you really  need, however, what I'm saying is: Too many calls are a SMELL that means something is wrong like A) We are with a bad or no DESIGN, B) We dont know what we are doing C) We are not studying enough D) We are missing context or all of them.

I hope you like it, thats it for today.

Diego Pacheco 

Popular posts from this blog

Podman in Linux

Java Agents

Manage Work not People