DEV Community: 🍉 Esteban Vargas

Just LGTM on Pull Request comments? You’re failing as a dev

🍉 Esteban Vargas — Mon, 25 Sep 2023 20:31:30 +0000

The simplest change possible should produce a better debate than LGTM

Looks Good To Me. LGTM 👍 You’ve seen this on a pull request that you’ve authored, and perhaps you’ve sent this as a comment yourself.‍

No matter how technically simple a change is (e.g. a one-line of code diff that simply changes a string) there should be at least some minimal discussion about that change. Does the text change look good to you? Why does it look good to you? Why do you think that text will convert better? What text has converted better before? Even something as simple as a text change can open up a whole debate about user value generation via code (code doesn’t have intrinsic value). There’s always something more thoughtful than lgtm to say. “I tested with this set of steps and lgtm”.‍

However, there’s another bad example at the other extreme. We’ve heard horror stories at big companies where a simple text change has taken up to 6 months. This isn’t what you should do either. Just briefly explain why it looks good or bad to you.‍

The LGTM Paradox

Developers spend 30% of their time doing code review but 65% of pull requests get rubber stamped with LGTM. There’s a paradox here.‍

It seems like developers thoughtfully review code, but they are not teaching others about their process which leads to information osmosis problems across the team.‍

The problem with rubber stamping with LGTM

Code review is a learning opportunity for everyone. In companies with the best engineering cultures everyone does code review. Juniors, engineering leaders, and even non-technical stakeholders such as product managers and product designers who bring a more holistic view to the process.‍

Not doing code review is detrimental to developer velocity in the long term. Let’s expand on this.‍

First, the risk of not deploying code that satisfies the user’s requirements to production exists. Whether this is because some app flow broke with wrong code, or because there’s some implementation that’s technically correct but not what the user wants, or because a potential security vulnerability is being introduced. If you are not thoughtfully reviewing code and just saying lgtm you are exposing your codebase, product, and company to this failure mode.‍

Second, you are not learning about the codebase. If a code refactor happens on a pull request, this is something that should bring up a lot of questions to you: Is everything still working as expected? Does it bring unexpected breaking changes? Is this refactor necessary, or is it over-engineering the codebase? To be able to keep adding features with this new approach, what should the method be?‍

Finally, if you just post lgtm on a pull request you are failing to mentor other developers. You are not teaching people about how something specific on the codebase works, nor about the organization’s coding standard and style, nor about what produces value to the user.‍

The PR comment/approval ratio metric as a solution

We strongly recommend engineering leaders tracking this metric.‍

A developer hasn’t approved PRs? The dev isn’t doing code review, that’s bad, and that should trigger a conversation. A developer has a lot of PR approvals but no comments? The dev is rubber stamping with lgtm. That’s also bad, and should also trigger a conversation. A developer is posting a lot of thoughtful comments on PRs, and also doing PR approvals? This dev should be rewarded.‍

Engineering leaders should track this metric to avoid rubber stamping pull requests with lgtm but as any other metric, it can be gamed. We recommend measuring it, and stating on a strategy document that it is measured, but not being very vocal about its measurement.‍

Quick solutions to the problem

There are certain low hanging fruits to check for when reviewing a PR that can easily start a conversation. The low hanging fruits to look for, which can easily replace that dreaded lgtm comment are:

Is the code commented?
Are variable and function names self-descriptive?
Is there unnecessary code logging?
Are data types in place? (This depends a lot on the programming language).
Can the code be refactored into smaller functions?‍

The solutions to an engineering culture that rubber stamps

Exceptional engineering leaders give psychological safety to their team.

‍There is no such thing as a stupid question, and there is no fear of questioning a certain technical approach. It all starts by having this cultural DNA of respect on your engineering leadership team.‍

Devs also rubber stamp with lgtm other people’s pull requests because they are pressured by a deadline to ship certain code themselves, which goes against carefully and thoroughly reviewing other people’s code. Just know that deadlines are arbitrary anyway (especially when doing innovation), and that there’s always a tradeoff between speed, cost, and quality where you can only choose 2 out of the 3 at max.‍

We also built a GitHub app that automatically traces code context for pull requests and posts such context on a comment.

The GitHub For Code Review UI Needs Serious Innovation

🍉 Esteban Vargas — Mon, 18 Sep 2023 15:34:32 +0000

A heads up: We love GitHub

People frequently mess up using GitHub for code review, because GitHub is a platform that lacks the necessary tools to achieve such a goal without any pain.‍

Reviewing pull requests is a very sensitive part of an engineering team’s workflow. That’s why developers will spend more hours than desired using GitHub for code review, even if the platform becomes perfect. However, if a developer is going to spend 30–50% of her time on GitHub for code review, it would be very nice if GitHub took to a whole new level their code review feature. We’ll explain this in-depth in this article.‍

A heads up (we know you’re thinking about this): We don’t hate GitHub. In fact, we love GitHub and have built products on top of it! It’s also the platform where we host our open-source repos. It’s because we have used GitHub so much that we feel free to have this opinion.‍

GitHub for code review will explain syntax, but does it help?

Let’s start by saying that they announced GitHub Copilot X will explain syntax in the different file diffs. Which is sort of useful, but… Is it just a little improvement? Yes. Is it a game-changer? No.‍

Using GitHub for code review is much more than checking for syntactic errors. In fact, if we go a step back, this isn’t a problem at all because linters on people’s IDEs exist. Linters will help you identify if an import is being done incorrectly, or if a variable is incorrectly typed, among many other things.‍

Let’s look at the example their landing page provides.‍

Taken from GitHub Copilot X’s landing page

We don’t have access to the code of the example per se, but the example tells us which files have been modified, what imports have been added, and what methods and constructors have been added.‍

All of these pieces of information can be easily inferred by the developer by looking at the file diffs. If you’re reading the code, we’ll presume you are a developer that knows the language.‍

Will it satisfy the business requirements? Is the code orthogonal and clean? What about any security vulnerabilities being introduced? What about the code not being efficient enough, perhaps? Testing instructions?‍

This is where the true opportunities for improvement of the GitHub for code review UI exist. We’ll make a few suggestions.‍

Improve diffing

Let’s be honest. When a file has a lot of line changes and has the “Load diff” text, it tends to get ignored in the GitHub for code review process. What people tend to incorrectly do is skim through the file diffs. Hopefully they might run the program in the new remote branch as well. But it’s not like people look at every green line in detail, and it’s not because developers are negligent people, it’s because it’s an overwhelming UI.‍

We understand that requesting full file diffs is wishful thinking. It has a huge technical challenge that may not be so obvious. People expect line coloring, language specific syntax highlighting, linkable trees, and start/end lines among other requirements. GitHub has to parse multiple files and patches in the same diff because diffs are generated per PR, not per file. Therefore it’s hard to think about a lightweight solution to this problem, to ultimately present it in some beautiful HTML/CSS.‍

But if someone finds a technically feasible way of doing it, those of us who use GitHub for code review will be grateful.‍

Reorganize discussions

The comments per file diff, to have as resolved/unresolved conversations is a little bit uncomfortable.‍

Has it ever happened to you using GitHub for code review that you send a PR, a teammate leaves a comment on a diff, you fix the objection, and then the reviewer doesn’t resolve the conversation and it feels vague to you whether the reviewer feels the new approach is correct or not?‍

This could be solved if there was a unique discussion thread on a sidebar. One that’s more visible, and makes resolving/unresolving conversations easier. The conversations tab on the code review UI (the main code review UI) works. However, comments sink in the sea of commits. It would be even better to have something like it but oriented towards resolving and unresolving conversations on the files changed tab.‍

GIFs

A smaller request, but imagine how expressive would the GitHub for code review process be if we could joyfully react to the approval of that PR that has been stale for months with something like this, as we do on Slack.

Taken from giphy

Pre-approve Pull Requests that satisfy the business requirements

This also sounds just like a wish, but hear us out.

‍A lot of PRs stay unmerged, in debate after debate, after weeks or even months not because of the technical complexity of the change (we’ve heard about horror stories of text changes staying stale for 6 months because of this), but because of the business impact debate: “Will this change increase engagement, revenue, etc?”‍

We thought that it would be really cool to build a tool that understands the business logic of the codebase and the changes being introduced to determine if the PR will or will not meet the user’s requirements. Then, pre-approve the PR based on that. Like a copilot for PRs, with business logic at its core.‍

That’s why we built an open-source passive docs search engine to contextualize your team’s pull requests. Index information from Slack, Notion, GitHub, Jira, and an ever-growing list of integrations. Then paste the most relevant information tied to that pull request on a comment, and finally use that indexed information to compare its intent with the actual intent of the pull request (its title) to label it as “🍉Safe to Merge” if those two intents are similar enough.‍

It looks like this.‍

Our tool concluded that PR #297 will satisfy the business requirements

Enjoy an enhanced GitHub for code review process!

How to ruin your life trying to do gitflow

🍉 Esteban Vargas — Wed, 13 Sep 2023 20:37:00 +0000

Gitflow is the best way to develop

Let’s be honest, gitflow is the best way to develop. You have the most recent accepted version and create a workspace where nobody will bother you and then expose it and (hopefully) get it accepted. Beautiful.

But it has a dark side.

When the gitflow bus leaves you behind, e.g. someone merges before you, your branch is behind. If those changes touch the same files you’ll find a distressing message in your terminal or the GitHub UI.

Now, your changes and the most current version are in a fight and it’s your responsibility to make both get along. That is gitflow.

You will take your git pull --force command and start fixing merge conflicts. If you pull with git pull --rebase you will see every piece of code clash against you and will have to pick which pieces to keep for every conflicting commit, which honestly is good because you get a sense of what changed. Ah, beautiful conflict read and awesome HEAD text. Use an IDE or GUI for this, that’s a thing not mentioned in gitflow. Save some hair, avoid the command line.

This traumatic experience can range from a couple minutes to a few hours as you toil all the files and contextualize yourself with how other people solve problems. The stakes are high as the other developer already was accepted. Hell, maybe you went “LGTM! 👍” on their PR. Their gitflow was pure and beautiful.

When you are done with this patience testing, you continue your task, hoping that no one else will get across the finish line before you do.

As you code, your “feature/amazing-new-thing” branch becomes crowded and full of commits. You know what’s in there, in the end you wrote it, but no one else does. It is a silo.

And then, you’re done.

Now it’s time to push and write to the Pull Request template your team decided on. Type, checkbox, add image and now you’re awaiting scrutiny, your part of gitflow is done. In an organized team, the time to be reviewed should be short. People should start their workday by checking their repos, especially if you have CODEOWNERS in them. If not, we recommend you add the GitHub Bot on Slack to save some time being pushy. Let’s agree to call it “Slack pushed gitflow”

Eventually, you’ll get comments or stamps (remember “LGTM! 👍”?) and will have to respond to them. If the administrator did their job right, you will be required to resolve conversations before merging. Your tests will have passed. The deploy system will have run and approved your build, automatic gitflow beats using people. Everything seems to be going great.

And disaster strikes.

Gitflow's dark side

You hear that beautiful sound of an incoming call from the Team Lead. Something has gone awry. You panic a bit, run to get a decent sweater, shuffle for your headphones and pick up.

“Hey! Saw your PR”, she starts. It’s on you now, don’t panic, you did a good job.
Without stuttering you make small talk and ask what’s up.
“Oh, a small thing, we are now using [insert thing] now, it got posted to Slack and I changed the ticket in Linear”. Right, you missed that one. Merging “feature/amazing-new-thing” to “main” was the only thing in your mind, gitflow style. You were wrong to allow yourself into the flow zone by turning off all notifications.

Well, now you gotta change that part before clicking the satisfactory green “MERGE” button, but there should be another way. It’s been about a day fighting this while you should be tanning while hiking or grabbing hot pot with the squad.

And there is!

A solution to gitflow's flaw

We built Watermelon to tackle these issues. We know that gitflow is great but sometimes gets in the way. You want to deploy PRs with business value. Your manager wants every developer with the best velocity they can give. You got the huge screen, clicky split keyboard, sound blocking headphones and expensive laptop but the software you use is not enough. While juggling Ticketing Systems, Internal Messaging, Git Platforms and Documentation you are left out of your IDE, whether it be VSCode or the IntelliJ family. Several terminals plaster your screen dropping red every few saves. Your standing desk with a walking treadmill is not enough to keep stress from your teammates at bay.

Watermelon is a Github App that gives you an AI summary of the work done on a PR so it’s a breeze to review, while bringing in any relevant links, so jumping the hoops is a click away.
Watermelon is also an IDE tool that allows you to contextually get the same results while you work so nothing gets lost in a sea of distractions. Try both now while keeping up with gitflow, for free!

GitHub Actions: Revolutionizing Workflows or a Fad?

🍉 Esteban Vargas — Wed, 09 Aug 2023 17:08:08 +0000

In the fast-paced world of software development, automation plays a pivotal role in streamlining workflows and boosting productivity. GitHub Actions Checkout, a powerful feature provided by GitHub, has gained considerable attention. As developers worldwide adopt this functionality, the question arises: Is GitHub Actions Checkout truly revolutionizing workflows, or is it just another passing trend? In this blog post, we'll delve into the depths of GitHub Actions Checkout, Watermelon Context GitHub application, and its impact on the development process.

Understanding GitHub Actions Checkout & Streamlining Workflows with Watermelon

GitHub Actions Checkout is a feature that allows developers to automate the process of checking out code repositories within their workflows. By leveraging this functionality, developers can seamlessly integrate version-controlled code into their continuous integration and deployment (CI/CD) pipelines. This automation aims to simplify development practices and accelerate software delivery.

One of the primary claims of GitHub Actions Checkout is its potential to revolutionize development workflows. By enabling swift and automated code checkouts, developers can save time and effort during the development cycle. Moreover, it fosters a more collaborative environment, as multiple team members can work on different branches simultaneously, confident in the consistency of the codebase.

The Watermelon Context application, a powerful GitHub Application that enriches your workflows by providing valuable insights from pull request comments. By seamlessly integrating Watermelon Context into your workflows alongside GitHub Actions Checkout, you can extract meaningful information, automate actions, and improve collaboration within your development process.

Watermelon Context acts as a bridge between pull request comments and automated workflows, enabling you to extract contextual information, such as reviewers, labels, and custom data, from comments. This information empowers you to trigger specific actions, automate repetitive tasks, and enhance the efficiency of your GitHub workflows. With Watermelon Context, code review becomes more efficient, allowing developers to receive real-time feedback and contextual information within pull requests. This enhanced collaboration fosters quicker issue identification and smoother code integration, resulting in faster development cycles and higher code quality, giving your team a competitive edge in the software development world. Embrace the power of Watermelon Context and GitHub Actions Checkout to revolutionize the way your team collaborates on GitHub.

Passing Trend or Long-term Solution?

GitHub Actions Checkout is a powerful and versatile feature that is far from being a passing trend. Its seamless integration with GitHub's ecosystem, widespread community adoption, and proven stability reinforce its position as a long-term solution for modern software development workflows. Developers benefit from its compatibility with various languages and frameworks, enabling streamlined code checkouts and accelerating development speed. With GitHub's continuous support and backward compatibility commitment, developers can rely on GitHub Actions Checkout for critical tasks in their CI/CD pipelines without concerns about obsolescence. Moreover, its ability to empower collaboration, simplify development processes, and remain cost-effective and scalable makes it a valuable tool for teams of all sizes. As part of the evolving GitHub Actions ecosystem, GitHub Actions Checkout continues to adapt to the changing needs of developers, positioning it as a reliable and enduring component for the future of software development.

Installing Watermelon Context GitHub Application

You can install the Watermelon Context GitHub Application effortlessly with the one-click feature available here. This convenient "One click install" feature allows you to add the Watermelon Context GitHub Application to your repository seamlessly. By integrating, you gain access to a robust context object that offers valuable information like commit details, repository insights, and event specifics.

Utilizing Watermelon Context

Once the Watermelon Context GitHub Application is installed, you can harness its capabilities to obtain benefits such as:

Tackling DORA metrics bottlenecks generated by stale pull requests (lead time for changes)
Helping your team send pull requests with business value, by contextualizing devs with what has produced value for the user previously and what hasn't
Passively build a documentation system ‍

Conclusion

GitHub Actions Checkout, as a feature designed to streamline code checkouts in development workflows, has certainly made a substantial impact in the software development community. Its seamless integration and versatility make it an attractive option for developers seeking efficient automation solutions. Whether GitHub Actions Checkout is merely a passing trend or a revolutionary feature with lasting significance is a subject of ongoing discussion.

By utilizing the Watermelon Context app, developers can better understand the practical implications of GitHub Actions Checkout in real-world projects, contributing valuable insights to this ongoing debate. As the software development landscape continues to evolve, embracing automation tools like GitHub Actions Checkout can pave the way for a more efficient and collaborative future.

🍉Install the GitHub Watermelon application

👋 Join the official Watermelon Discord community

Your Pull Request Template Example Might Hurt Efficiency

🍉 Esteban Vargas — Tue, 08 Aug 2023 22:55:00 +0000

A few years ago, GitHub introduced pull request templates to help streamline the software development process as a team. They are files that allow developers to write a pull request description with a pre-defined structure that will help their teammates get a better understanding of what they did.

They are very useful because they help contextualize the code review process. After all, it’s a very time consuming process for devs, and a very hard one for non-technical stakeholders who bring a more holistic opinion about the code that will potentially get merged into production.

The absence of a pull request description is very painful, picture this: You are cooking a complicated but exquisite meal with your friends. One of your friends, confident of his culinary abilities, hands you a pan with a simmering concoction.He claims it’s the secret ingredient to the dish. You taste it and you’re left perplexed. You ask him about the recipe, and you receive a dreaded “I can’t give you the recipe” message. You see a bunch of ingredients, with no labels or explanations, and you’re left lost.

This is the same kind of frustration that a developer feels when he sees a “No description” message in a pull request.

Pull request templates solve this problem by enforcing developers to contextualize the code review process. However, having an overly complicated pull request template will reduce developer velocity.

Unpacking a Standard Pull Request Template Example

What’s the ideal pull request template example? Let’s take a look at two examples and boil it down to a few fundamental principles.

This is the canonical pull request template example (a shorter version of the one we have on our repo). In our opinion this is the minimum threshold of information that a pull request description should include.

<!-- Please include a summary of the change and which issue is fixed. Please also include relevant motivation and context. List any dependencies that are required for this change. -->
## Type of change
<!--  Please delete options that are not relevant or write your own. -->
- [ ] Bug fix (non-breaking change which fixes an issue)  
- [ ] New feature (non-breaking change which adds functionality)  
- [ ] Breaking change (fix or feature that would cause existing functionality to not work as expected)  
- [ ] Documentation update  
- [ ] Chore: cleanup/renaming, etc  
- [ ] RFC

Despite the fact that this pull request example forces the author to write a description and check a box that states which type of change this proposed change inserts to the codebase, we could do much better.

Let’s explore the idea of adding more information to a pull request template.

The Hidden Costs of Complexity

A context-rich but very complex pull request template example impacts the productivity of the team negatively.

In this final pull request template example we add a lot of steps, and they’re all there for a very good reason.

## Summary

<!-- Provide a concise summary "Why are the changes needed"? 
Include any relevant links, such as Jira tickets, Slack discussions, 
or design documents. -->

## Changes Made

<!-- Describe the specific changes that have been made in this pull 
request. Provide details on the approach taken to address the problem 
and any notable implementation details. -->

## Type of change
<!--  Please delete options that are not relevant or write your own. -->
- [ ] Bug fix (non-breaking change which fixes an issue)  
- [ ] New feature (non-breaking change which adds functionality)  
- [ ] Breaking change (fix or feature that would cause existing functionality to not work as expected)  
- [ ] Documentation update  
- [ ] Chore: cleanup/renaming, etc  
- [ ] RFC 

## Checklist

- [ ] I have added comments to code in hard-to-understand areas
- [ ] I have made corresponding changes to the documentation
- [ ] My changes generate no new warnings
- [ ] I have added tests that prove my fix is effective or that my feature works
- [ ] Any dependent changes have been merged and published in downstream modules

<!-- Optional Sections -->
<details>
<summary><strong>Expand for optional sections</strong></summary>

## Screenshots 
<!-- If the changes are visual, including screenshots or GIFs can 
help reviewers understand them more easily. -->

## Related issues
<!-- A link to any related issues or bugs that the pull request 
addresses, connecting the code's context with the problem it 
solves. -->

## Testing instructions
<!-- Instructions on how to test the changes made in the pull 
request, helping reviewers validate the code. -->

## Special notes for your reviewer
<!-- If there are any specific instructions or considerations you 
want to highlight for the reviewer, include them in this section. -->

</details>
<!-- End of Optional Sections -->

However, this pull request template example is complex. Filing every section will take away precious time from your developers.

Advocating for Minimalism

The best template is the simplest one. The simplest one that doesn’t leave critical information out.

Is there a way to get the amount of context from the second pull request template example, with the time investment of the first pull request template example?

Transitioning from Complexity to Simplicity

Let’s go back to the last pull request template example. Every single element there is in place for a very good reason but it will be very time consuming for the developers in your team to do this every single time they send a pull request.

Screenshots might sound like a very trivial thing to do. But most of the time what you actually need is a video (perhaps renaming this section is an opportunity of improvement for such pull request template example). A video showing the application flow(s) being affected by the pull request. Which not only involves a context switch but also setting up the screen recording in a way that will make the pull request author explain what was changed. You also eventually end up linking to Figma.

Testing instructions might also be underrated. “I’ll write one or two sentences and that will be enough to instruct the reviewer”. It’s more than that. What’s the edge case to test? Is there one in the first place? How can you execute a non-obvious step in the process? Is there a certain username you need to try this with? What about screen sizes? As much as you have a well-placed TDD process, no one dares (and no one should) merge a pull request without a manual testing process.

The related issues section is very interesting. Out of the new sections introduced in this pull request template example it is the most useful one. It is the largest context provider. It gives information about previous approaches that have both succeeded and failed, what provides value to a user and what doesn’t, and how has the business logic been historically affected. This information can live not only in pull requests but also in Slack message threads, in project management tickets in systems such as Jira and Linear; and also in documentation systems such as Notion and Confluence. Most frequently, you either end up in a Zoom call (less than ideal, this is the biggest reducer of developer velocity of all) or linking to a piece of documentation, or discussion.

Our GitHub application can help your team automating the retrieval of these related pieces of information.

Conclusion

Pull Request templates are necessary but if you overcomplicate them you will reduce your team’s developer velocity. Keep it as simple as possible. We suggest using the first pull request template example or Watermelon’s pull request template example, and enrich such pull requests with our GitHub application.

How to Properly Use GitHub For Code Review

🍉 Esteban Vargas — Wed, 05 Jul 2023 16:28:33 +0000

_This was originally published here_

Why is a proper code review process so important?

Developers spend 30% of their time doing code review. This makes PR review the main bottleneck for DORA metrics. However this bottleneck is a necessary evil, because fixing errors in production is even more costly both for the productivity of developers and their team morale.

In this blog post, we will explore the best practices for using GitHub for code review.

Have a proper branching model

By default this should be Gitflow or GitHub Flow, which we have compared in a previous blog post.

The general idea here is to be thorough about how your team is using GitHub for code review. Regardless of whether you’re going to have a develop branch between the main branch and the branches where work is done locally, a proper branching model for properly using GitHub for code review must:

Create your own branches and have them follow the whole cycle of a branch (creation, activation, merge, and deletion, which is an optional step).

Following a proper branch naming convention. This means describing if a branch is a feature, bugfix, hotfix, or enhancement. Ideally followed by the project management ticket associated to it followed by an imperative phrase (eg: “fix sidebar navigation”). A few examples in one of our repositories below.

‍

PRs should be self-sufficient tasks

A common failure mode is to make gigantic PRs. This is very common at FAANG companies, and that’s why they use a unique approach called stacked PRs. While we think this is a very interesting approach to fix this particular failure in the GitHub for code review process, it’s a solution to a problem that shouldn’t exist in the first place.

‍
By default, Pull Requests should be self-sufficent tasks. Using a solution to stack PRs while using GitHub for code review as you already normally do, is a huge behavioral change. You have to learn a new git system, and you have to learn an alternative to Gitflow/GitHub Flow. You can prevent this by enforcing everyone on the team to be strict about making small PRs, that are tied to small project management tickets.

Run git fetch

The functionality provided by GitHub for code review extends beyond the scope of what git does on your local machine.

Run git fetch to synchronize the latest changes in remote branches to your local branches. This way, when you run git checkout , you will have everything correctly set.

Connect PR Review with Slack

Another reason why developers spend 30% of their time in GitHub for code review is that they are so focused on the task they are working on, that they forget to review the code their peers created PRs for.

Luckily, they have a bot specifically designed to improve the GitHub for code review experience.

We’ve seen other practices such as manually creating a channel per Pull Request (and then deleting such channel once the PR is closed) being implemented. It might be a bit of an overkill and hard to thoroughly stick to every single time, but it also produces great results.

Automate code quality analysis

To improve your team’s experience using GitHub for code review, you should automate code quality analysis.

‍
Static code quality analysis tools such as SonarCloud, Code Climate, and DeepSource are great for this. They help you make sure that the code in your PR isn’t introducing technical debt or potential security vulnerabilities.

However, as important as it is in the GitHub for code review process, using static code quality analysis tools isn’t enough to make sure that Pull Requests will satisfy business requirements.

Write awesome pull request descriptions

Ensuring PRs are created with the correct branching model and size is basic. Updating local branches with remote changes is something that is forgotten a little bit more often but still paramount for properly using GitHub for code review. Keeping PRs visible to everyone and automating the more mechanical stuff such as checking for potential security vulnerabilities is going the extra mile, and it helps a lot.

You are sub-utilizing GitHub for code review if you are not writing awesome pull request descriptions. Beyond using a great PR template (which is outside the scope of this blog post), the content of the description section of your PR template should include:

What is the business objective trying to be achieved with this pull request?
Approaches tried, why is this the correct technical approach? Linking to related PRs is useful for this
If your team is using an agile methodology (like most other teams in the world today), link to the project management system ticket related to the task this PR is addressing.
Link to relevant documentation
Has there been any relevant conversation about this PR or the business logic it’s changing? A Slack message thread or a Zoom transcript perhaps?
‍
Our GitHub Application helps you automate the process of writing awesome pull request descriptions according to this criteria.

GitFlow and GitHub Flow Compared: Which one is better?

🍉 Esteban Vargas — Mon, 26 Jun 2023 22:20:00 +0000

_This was originally posted here_

Gitflow Overview

Gitflow is, by far, the most popular branching model and possibly the one that has endured the test of time the most. Introduced by Vincent Driessen in 2010, its fundamental idea is that you should isolate your work into different types of git branches.

Other branching strategies, such as the centralized workflow (for those teams that come from SVN), and the forking workflow (for open-source projects) exist. Git, as a version control system, only details basic branching operations, and it remains controversial as to which approach is the best. Beyond those basic branching operations, it's a matter of opinion.

In this article we will compare Gitflow with its newer approach, GitHub Flow.

The gitflow branching model consists of merging 3 types of temporary branches to a develop branch, which should later get merged to a main branch
‍

Common criticisms of gitflow

Complexity: Having two long-lived branches and three types of temporary branches (feature, release and hotfix) increases the required effort needed to take something to production. Your team has to merge to develop and then to main. This might be a smaller problem for your team, but still, they can forget.

No rebasing concept: With the branching complexity of gitflow, you will need to track branches visually, which for the most part gets rid of the concept of rebasing. Rebasing is a complex topic but it’s still important for the conversation because

More merge conflicts: It’s simple, the number of branches that you have to merge correlates with the number of merge conflicts that you will have. In theory this isn’t something that you should worry about because git is designed to deal with this. But in practice, it will consume a significant portion of your time.

Again, this branching model was conceived in 2010 and even the author of such recognizes that it hasn’t survived the test of time. In an update Vincent Driessen recommends “a much simpler workflow (like GitHub Flow), and suggests that there is no panacea.

Gitflow and GitHub flow compared

The main points of GitHub Flow are:

Anything in the main branch is deployable.
To work on something new, create a descriptively named branch off of main.
Commit changes to this new branch.
When you need feedback or help, or you think the branch is ready for merging, open a pull request.
After someone else has reviewed and signed off on the feature, you can merge it into main.
Once it is merged and pushed to main, you can and should deploy immediately.
‍
Pretty much the same as the traditional gitflow but without the develop branch in the middle.

About pushing directly to the main branch

Purists will say that this is a bad practice, and that you should be adamant about using gitflow.

While it is true that a solid automated testing framework (or extra diligence) is required because any bug merged into main will go straight into production, we recommend GitHub flow as an approach for certain scenarios. Automated testing frameworks are very well developed today and there are lot of ways to catch bugs before they go into production.

While a tradeoff exists indeed, it’s much more what certain kinds of teams get.

Better suited for continuous delivery
Branch management becomes easier. Less merge conflicts to deal with.
Encourages teams to release quickly
Since there is less overhead, technical debt can be more easily ammortized ‍ ## It’s mainly about product maturity As a framework of thought to choose a branching model, we suggest thinking about the product’s lifecycle.

If the product is pre-Product-Market-Fit (measured by retention and expansion of use, NPS, Sean Ellis test, etc), your team needs to test as much assumptions as possible and as quickly as possible. At this stage you are testing what sticks and what not, therefore accidentally pushing a bug to production isn’t as critical. We recommend GitHub flow at this stage.

If the product is post-Product-Market-Fit, the scenario drastically changes. Your product is either mission critical for a company or something that consumers use everyday. At this stage you don’t have the luxury of pushing bugs to production. We recommend gitflow at this stage.

Regardless of your decision, still have an open mind.

Enriching pull requests with business logic

Regardless of whether you choose gitflow or GitHub flow as your branching model, code review consumes 30% of a developer’s time. A lot PRs stay stale not because of the technical complexity of the change introduced, but because of the debate that it produces around its impact on business metrics.

You can enrich your team’s gitflow or github flow process with business context. Watermelon’s GitHub Application does this by indexing the most relevant information from git, project management, messaging, and ticketing systems for a new pull request; and commenting it with such information. This will help you reduce ping-pong communication in your gitflow or GitHub flow code review process.

Key Factors Influencing Coding Velocity: A Comprehensive Analysis for Managers

🍉 Esteban Vargas — Wed, 21 Jun 2023 17:44:00 +0000

This blog post was originally written here

Efficient coding velocity is crucial for the success of software development projects. As a manager, understanding the factors that influence coding velocity and how to optimize them is essential. In this article, we will explore key elements that impact coding velocity. By examining these factors and providing practical insights, managers can effectively enhance coding velocity in their teams. Additionally, we will introduce Watermelon, a powerful tool designed to enhance productivity and collaboration throughout the development process.

‍

Clear Communication and Coordination

Effective communication and coordination are vital for maintaining a high coding velocity. Watermelon facilitates clear communication channels and promotes collaboration among team members. By utilizing features like real-time messaging and project forums, managers can foster effective communication and ensure that everyone is on the same page. Watermelon's centralized platform allows team members to access project updates, share information, and seek clarification, eliminating potential bottlenecks that can hinder coding velocity.

‍

Minimizing Unexpected and Unplanned Situations

Unforeseen circumstances and disruptions can significantly impact coding velocity. Managers must proactively identify potential risks, develop mitigation strategies, and establish contingency plans to minimize their impact on development timelines.

‍

By implementing thorough risk management practices, managers can anticipate and address potential challenges. Watermelon helps managers proactively identify and mitigate risks by providing comprehensive project tracking and monitoring capabilities. By utilizing Watermelon's risk management features, managers can promptly address potential challenges, ensuring that unexpected situations do not derail the development process.

‍

Efficient Planning and Work Breakdown

Thorough planning and effective task breakdown are key to optimizing coding velocity. By defining project milestones, identifying dependencies, and allocating resources efficiently, managers can streamline the development process and maximize productivity.

‍

When planning a project, managers should invest sufficient time in creating a detailed roadmap, breaking down tasks into smaller, manageable units, and setting realistic deadlines. This level of planning provides clarity and direction, enabling team members to focus on their specific responsibilities. By promoting efficient work breakdown and task allocation, managers can ensure that the team operates smoothly, minimizing confusion and delays that may hinder coding velocity.

‍

Streamlined Approval Processes

Obtaining approvals is an integral part of the development lifecycle but can sometimes hinder coding velocity. However, inefficient approval processes can significantly slow down coding velocity. Managers should aim to streamline these processes to maintain a seamless workflow.

‍

To achieve this, managers can leverage tools like Watermelon, which provide streamlined approval workflows. Watermelon streamlines the approval process by providing a centralized platform for stakeholders to review and provide feedback promptly. With Watermelon's streamlined approval workflows, managers can ensure that approval processes are efficient and do not cause unnecessary delays. By incorporating Watermelon into the approval workflow, teams can maintain their coding velocity while receiving timely approvals.

Conclusion

Coding velocity is influenced by various factors that require careful consideration from managers. By emphasizing clear communication and coordination, minimizing unexpected situations, implementing efficient planning and work breakdown, and streamlining approval processes, managers can optimize coding velocity within their teams. The utilisation of tools like Watermelon further enhances productivity and collaboration. By prioritizing these key factors, managers can drive their teams towards higher coding velocity, ultimately leading to the successful and timely delivery of high-quality software products.

‍

Resources and Further Reading

Watermelon GitHub Plugin for Visual Studio Code
More on improving the Code Review Process
More on Watermelon for Slack

6 steps to do better code reviews

🍉 Esteban Vargas — Mon, 21 Nov 2022 09:08:46 +0000

TLDR ‍

Make everyone do code reviews, even junior folks
Check for code readability
Make sure the pull request is creating passive documentation
Test performance
Check for potential security risks
Check testability

Disclaimer: This guide is for post Product-Market-Fit companies. If your company is pre-PMF, you should be optimizing for speed of iteration above anything else. If you’re pre-PMF your headcount should also be as small as possible, therefore a lot of the guidelines here don’t apply. Adapt according to your needs.

We’ve all seen something like this happen before.

We don’t blame you. There’s always pressure from management to ship stuff as quickly as possible, to ultimately allow the product to generate more revenue or traction. In fact that’s our end goal as developers.

However, having a culture of precarious or null code reviews leads to the accrual of technical debt.

‍

What is a code review?

A code review is the process of vetting code by another developer. A developer sends new code to be integrated to the main branch, and asks a teammate to review it.

The main goal of code reviews is to maintain a high code quality on the codebase. A second programmer can possibly identify issues in the logic, the readability, the modularity, the dependencies or the functionality of a programmer’s code.

Having a well established code review process also helps educate your team. It helps developers learn from each other.

So what’s the best way to make code review work?

‍

Make everyone do code reviews

Even the most junior developer should be reviewing the technical lead’s pull requests.

You might think this is counterintuitive. Wouldn’t this allow for a lot of pitfalls? Yes, but that actually leads to a benefit. A developer with a minor seniority will not necessarily understand everything about the code context, might not anticipate all the potential failures, and generally speaking will not catch as many errors as a senior developer.

This however, forces the senior developer to explain his code changes better.

There are 2 techniques to distribute how pull request reviews are distributed. GitHub, for example, provides the option to automatically assign a PR reviewer using both.

Round-robin focuses on distributing the number of reviews equally, regardless of the number of outstanding pull requests they have.

The load balancing algorithm focuses on distributing pull request reviews based on the number of outstanding pull requests each team member has. This algorithm tries to ensure that everyone reviews the same amount of pull requests in any 30 day period.

You can take a look at GitHub’s documentation to learn how to set this up for your team.

Both methods are completely valid, and which one to choose from depends on the specific characteristics of your team. We suggest round-robin if the seniority level of your devs is homogenous, and load balance if it’s heterogeneous.

‍

Check for readability

Code must be readable to be maintainable. Code must be maintainable to be useful for a software development team. Here’s a checklist for code readability.

Are packages in order? Sometimes packages release new versions and they come with breaking changes. However, as Benjamin Silva suggests, embracing huge changes when they come is part of the deal. Spend a few days refactoring when big version releases come, and that way you will always have your packages up to date.
Does the code adhere to your organization’s standards? The standards are very specific to each team and can be around naming conventions, linting, or generally speaking some kind of series of rules that people on the team agreed on.
Are the variable and function names descriptive? Use intention revealing names, beware of names which vary in small ways, use pronounceable names, and use searchable names (eg: don’t name array indexes i and j, name them something descriptive like numberOfTasks).
Can the code’s functions be broken up into smaller ones? It’s worth refactoring the code to achieve this. Does the code need comments? A priori, yes. ‍

Does the pull request include useful passive documentation?

Title: Does the title give me information about the change? A good practice is to include the (Jira, Linear, Notion, ClickUp, or whatever ticketing system you use) ticket code on the title to link these 2 pieces of information. Another good practice in pull request naming is starting their title with an imperative present tense verb (eg: “move the module…, “create the function…”, “debug the feature…”)‍
Description: Is the author explaining the problem? The intended solution? Is there a testing plan outlined? Does the description include a screenshot or a video?‍
Is the type of change outlined in the description? Including this piece of information gives better searchability to your team. If you want to take a look at a pull request template, take a look at the one we have in our open-source repository.

‍

Test performance

How strict this should be depends 100% on the stage of the organization that owns the codebase. The testability requirements for a corporate, that has a well established revenue generating product, with millions of users; are different from the ones of an early stage startup that has the existential need of finding Product-Market-Fit, else they’ll run out of money. The former needs to optimize for strictness, while the latter needs to optimize for speed of iteration.

When you want to optimize for strictness, here’s what needs to be tested.

Check for unnecessary code logging: Logging in the wrong place can significantly deteriorate performance and expose information that should remain private.
Check data types: Based on the expected values, database types can be optimized for performance. For example in SQL, if the data varies in length, it can be more efficient to use varchar than char. If a column is going to store values between 1 and 5, use tinyint instead of int. Can performance be improved by adding or removing indexing? Depending on the context, this can be the case. Indexing doesn’t magically guarantee faster retrieval times. For example, if you break the First Normal Form property, indexing will make the performance decrease in some cases.
Can you server-side render fetched data? Generally speaking, it is faster to make all the requests on a server than it’s to make extra browser-to-server round-trips for them. Server-side rendering is not always applicable, but when it’s, it should be there.
Can queries return less data? At scale, returning too much data on a query will reduce performance.

Check for potential security failures

Check for over-informative error prompts: Be informative, but not too informative. Sometimes these messages can give an attacker the information they need to break in. -** Check for exposed environment secrets:** Encourage good secret management practices in your organization. Once an environment secret is exposed on a remote branch, it will always be on the internet. It must be changed immediately.
Make sure authorization and authentication are handled correctly: Always use https. Consider having different API keys for different roles and permission levels. ‍

Testability

Are the tests passing? Whether they’re unit tests, end-to-end, or both… Make sure they are passing. If an already existing user flow changed, update the tests accordingly.‍

Originally published at https://www.watermelontools.com.

What is passive code documentation? Why is it hard to scale? What to do about it?

🍉 Esteban Vargas — Thu, 03 Nov 2022 11:51:48 +0000

This blog post was originally posted here

TLDR

Passive code documentation is crucial for capturing code context that your devs have in their head
We have systems that reward writing passive documentation, such as GitHub and Jira
But, we have needs for better findability of passive documentation as a product and a codebase grows
We created a VS Code extension to tackle this problem

What is passive code documentation?

According to Silona Bonewald (former Director of InnerSource Commons), “Passive documentation is the record of the documentation we create every day while communicating openly.”‍

For example, adding a description to a Pull Request is a form of passive documentation. Adding a Jira ticket identifier to the title of a Pull Request is another form of such. Linking already existing sources of technical information, is creating passive documentation.‍

As the majority of software development happens remotely, the only way to share information across different people is through great documentation. Documentation can be broken up into 3 categories:‍

Wikis and READMEs

The most traditional approach. Wikis are usually in a CMS system, and READMEs are a standard for open-source projects.‍

Regardless of the format, this means having documentation in the home page of a project. This page has information about the product’s usage and code. How do I install? What dependencies do I need? How is the project scaffolded?‍

Code comments

Also traditional, but more granular. They describe how a function or line of code works.‍

Tools like JS Doc have an interesting approach to automate this, this form of documentation tends to be the most precarious or null one. Writing such has a huge friction.‍

Passive Documentation

You are already writing code context on different company information systems. On places like GitHub, Jira, and Slack. Having different kinds of discussions on these systems that help developers contextualize themselves about a codebase.‍

For instance, this is how passive documentation is written on a GitHub Pull request.‍

A code contributor reports something that needs to be changed

He or someone else sends a Pull Request. This contains a detailed description of the change, as well as file diffs.

Someone else reviews the PR. Detects an error, requests a change, or simply approves. There’s now a discussion thread that gives code context to other developers.
‍

Passive Documentation is crucial for capturing code context that your devs have in their head

It’s very important to break knowledge silos to share information in a distributed team.‍

A well-maintained, popular open-source repository has this well thought out. People distributed across the world, collaborating on a piece of open-source software has been working since the early 2000s, when the first distributed version control systems came out. Companies can learn a lot about the open-source community.‍

In the open-source community, complex pieces of software are written and maintained by hundreds of people who don’t know each other, across time zones. It works like a charm, but not in the corporate world.‍

The corporate world has processes, and bureaucracy. Negotiations between parts need to happen to make changes, even if they’re small. There’s red tape. Obviously, we’re talking about an organization whose goal is to generate a profit and not just value for free, but undoubtedly people want to optimize for their own benefit. They want a promotion, they want to become irreplaceable.‍

This old meme explains it well.

Famous meme depicting Microsoft’s organizational structure before Satya Nadella
‍

Departments (or people) start to compete internally between them, and that creates knowledge silos. They start blaming each other for bugs.

Passive documentation is the solution to this problem. If people don’t want to actively document for the public good, you can reward writing passive documentation. For example, if people don’t want to write and maintain a wiki, a README, and structured code comments; you can create a gitflow process that will reward people for writing code contexts on Pull Requests.

We have systems that reward writing passive documentation
Generally speaking, the modern collaboration stack has various tools that reward writing passive documentation. Different systems provide different pieces of context‍

Version Control Software (GitHub, Bitbucket, GitLab)

File diffs
Technical motivations for a change
Technical discussions around a change‍

Ticketing systems (Jira, ClickUp, Notion)

Mockups with breaking and desired behavior
Business logic motivations for a change
Business logic discussions around a change‍

Internal messaging systems (Slack, Microsoft Teams)

Code snippets
Unstructured discussions around those snippets. Both on technical aspects and business logic
Screenshots that don’t make it to version control or ticketing systems (eg: the debugging process).‍

We have needs for better findability of passive documentation
As a product and its codebase grow, finding its passive documentation becomes harder.‍

You get more units to search. More repositories, more commits, more pull requests, more tickets, and more conversation threads. Also, as time goes on labor rotates in a company. The person who wrote an important module in the codebase left, with a bunch of code context on his head.‍

We need better tools to prepare companies for change. Change on their codebase, on their business logic, and on their workforce.‍

Git blame is a useful starting point, but not enough. Git blame can give you authors and commit messages, which is useful, but we can do better than that.‍

‍At Watermelon, we’ve created a VS Code extension to help you find passive documentation with ease.

The Cool Git: 5 Not so Well Known Tricks

🍉 Esteban Vargas — Wed, 16 Mar 2022 16:03:50 +0000

This post was originally written on Watermelon's blog

Git clone, git commit, git push. That’s part of the bread and butter of any developer nowadays.

But why stop there? Git is a much more powerful software and it would be boring to only do such. Here are 5 not so well known tricks that have saved me hours in my life as a software developer.

Let’s look at the 5 tricks using Watermelon’s repo as an example.

git reflog

‍
Run this when you screwed everything and need a time machine

This is the one I use the most. A lot of times you want to go back in time to when stuff worked. Sometimes you accidentally delete stuff, or merge bad code. Reflog fixes this.

You will see the list of all things you’ve done across branches. With reset, you will be able to go back to that moment.

git reflog
# git reflog will show you everything you have done across branches

# 843e14a (HEAD -> dev, origin/feature/pr-titles, feature/pr-titles) HEAD@{0}: reset: moving to HEAD@{3}
# ff22923 (origin/dev, origin/HEAD) HEAD@{1}: reset: moving to HEAD@{3}
# ff22923 (origin/dev, origin/HEAD) HEAD@{2}: reset: moving to HEAD@{2}
# 6068d94 HEAD@{3}: reset: moving to HEAD@{2}
# 843e14a (HEAD -> dev, origin/feature/pr-titles, feature/pr-titles) HEAD@{4}: reset: moving to HEAD@{2}
# ff22923 (origin/dev, origin/HEAD) HEAD@{5}: pull origin dev: Fast-forward
# 6068d94 HEAD@{6}: checkout: moving from feature/pr-titles to dev
# 843e14a (HEAD -> dev, origin/feature/pr-titles, feature/pr-titles) HEAD@{7}: commit: Fix merge conflicts from PR #24
# 6068d94 HEAD@{8}: checkout: moving from dev to feature/pr-titles
# 6068d94 HEAD@{9}: checkout: moving from chore/fix-closing-string to dev
# d452489 (origin/chore/betterSidebarSVG, chore/fix-closing-string) HEAD@{10}: pull origin chore/betterSidebarSVG: Fast-forward
# bbc4cc8 (origin/chore/fix-closing-string) HEAD@{11}: pull origin chore/fix-closing-string: Fast-forward
# 6068d94 HEAD@{12}: checkout: moving from dev to chore/fix-closing-string
# 6068d94 HEAD@{13}: clone: from https://github.com/watermelontools/wm-extension.git

git reset HEAD@{index}
# Let's say you type git reset HEAD@{7}
# git will take you back to the point in time before we fixed the conflicts in PR#24

# Unstaged changes after reset:
# M images/wmbw.svg
# M media/main.js
# M package.json
# M src/extension.ts

git log

‍
Run this when when you want to see how a file has changed throughout time

This one is basically a movie rewind. I run this when I want to understand how a file has changed. It might be that I want to understand how those changes are intertwined with changes in some other file of the repo. It might also be that I want to understand who has made certain changes in a given lapse of time.

We are passing these flags to get a list of commit hashes and authors grouped with their respective code diffs.

git log --stat -p --follow -- src/extension.ts
# The command will show what we have done to this file, detailing the commit hash, the author, and the files changed. 
# The list goes on but for simplicity we're showing 2 changes

#commit a170d0b8424cde5c718b46fe552ef16296f1a91f
# Author: Juan <juands1903@gmail.com>
# Date:   Mon Mar 14 22:12:16 2022 -0500
# 
#     Merge branch dev into UX/AddCommunityLink
# ---
#  src/extension.ts | 8 --------
#  1 file changed, 8 deletions(-)

# commit bbc4cc859957964d51486fe3778ca5317cd0ee7a (origin/chore/fix-closing-string)
# Author: estebandalelr <estebandalelr@gmail.com>
# Date:   Mon Mar 14 16:55:15 2022 -0600
# 
#     Fix closing string, add kbd to instructions
# ---
#  src/extension.ts | 4 ++--
#  1 file changed, 2 insertions(+), 2 deletions(-)

git pull –-rebase

‍
Run this when you don’t have many local changes and those don’t deserve to be in a new branch

When learning gitflow you are taught to branch and merge. This makes a lot of sense because you usually don’t push frequently and you accumulate a bunch of changes on the remote branch before pushing.

However, if you’re only making small changes within a short time lapse, this command will help you keep the commit history organized. Using it is pretty straightforward.

git pull --rebase

git cherry-pick

‍
Run this when you accidentally committed changes to a wrong branch

Let’s say that I have a branch called dev and another one called git/cherry-pick. Let’s say that I added a file commited_by_mistake.js to the dev branch and accidentally committed it. This command will help us move such commits to git/cherry-pick.

# Run git checkout {correct-branch}
git checkout git/cherry-pick

# [git/cherry-pick 97d1731] Add wrong commit
#  Date: Tue Mar 15 16:28:34 2022 -0500
#  1 file changed, 2 insertions(+)
#  create mode 100644 wrong_commit.js

git checkout dev
# Switched to branch 'dev'
# Your branch is ahead of 'origin/dev' by 1 commit.
#  (use "git push" to publish your local commits)

git reset HEAD~ --hard
# HEAD is now at 6f7e0aa Merge pull request #35 from watermelontools/feature/pr-titles

git blame

‍
Run this when you want to get the historical context of your code

I use git blame when I want to know who wrote changes in a range of lines of code. This allows me to later ping that person on Slack and ask very specific questions. It’s also very simple to use. Just tell the command which file and range of lines you want to get that context from.


# Run git blame -L {startLine},{endLine} {filePath}
git blame -L 8,12 src/extension.ts

# cc2f380e (estebandalelr 2022-03-09 14:00:02 -0600  8) const path = require("path");
# cc2f380e (estebandalelr 2022-03-09 14:00:02 -0600  9) const { EOL } = require("os");
# 52ccc1ed (estebandalelr 2022-03-09 13:53:22 -0600 10) // selection ranges should be a global var
# 52ccc1ed (estebandalelr 2022-03-09 13:53:22 -0600 11) let startLine = 0;
# 52ccc1ed (estebandalelr 2022-03-09 13:53:22 -0600 12) let endLine = 0;

In fact, Watermelon is a UI for git blame with superpowers. Highlight a piece of code, and within the VS Code UI we tell you who made those changes. We also give you the relevant PR comments around that snippet of code.

Go ahead and download our VS Code extension, and please star us on GitHub to give visibility to the project so that we can continue developing it.