Getting the best out of Github with Remote work & PRs
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.
Cheers,
Diego Pacheco
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.
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.
Cheers,
Diego Pacheco
