General

Git Strategies for Working on Teams

Sep 1, 2022

4 min read

Background

Every team I’ve worked on has had different expectations and rules around git. Some had strict guidelines that created developer experience issues. Others had rules that were so loose that there was no consistency on the team.

These are my thoughts on what I’ve discovered to be a healthy balance between the strict and loose rules on teams. I hope to make suggestions for your team, and process that don’t sound dogmatic, and eventually help.

Always Branch and Pull Request to Main

This may seem like a no brainer to some, but no one should ever be interacting on your repo’s main branch directly. All changes to upstream main should be handled via pull requests (PR) with the exception of the initial repository commit. This will make all the suggestions throughout the article function properly. But it should also make it so your main branch will remain healthy assuming you have CI/CD working on PR. It also enables peer review on work which is a good habit. I still PR on my personal projects to make so I understand a set of changes in context as well.

Merges to main via Squash and Merge

All git hosting services have a “Squash and Merge” button on PRs which is an alias for:

git checkout main
git merge --squash <branch>
git commit

This takes all the commits on the specified branch and reduces them into a single atomic commit that gets inserted into the main branch. This is great for a few reasons:

Keeps your git history clean
1. omits merge commits
2. keeps merge historically fully sequential
Creates a single commit describing a bulk of changes but still makes the history of those changes available via a link to the original PR for full context
Helps using bisect strategies to identify when a change was introduced, and reference the PR in which that change was introduced

The following is an example output of the squash and merge strategy:

Individual Branching

I have two rules I suggest for individual branches:

conform to some naming convention the team sets
use a non-destructive strategy for commits and updates once a review has occurred

Rule 1 exists for a variety of reasons but primarily to avoid naming collisions. Rule 2, on the other hand, exists for a reviewer’s sake. All net new changes should be done via commits once a review has be initiated. Otherwise, it’s hard for a reviewer to track what they’ve already looked at versus what’s changed. Be nice to your reviewers. Once that PR is open, you may not use --amend or rebase on existing commits moving forward.

Otherwise, how you keep your branch up-to-date with the main branch is entirely your choice. Merge is typically the easiest if there are conflicts, especially when trying to resolve, and is usually best for novice developers. Rebase is great if you don’t have any merge conflicts or merge commits, and lets you get all the latest changes in the main brach. At the end of the day, do what is best for you.

The squash and merge strategy makes it so your branch can be whatever you want it to be. Do you commit every 5 minutes? Fine! Have 15 merge commits from main? That’s also fine! All these actions tell a story but squash and merge to main keeps that history on your branch, and PR and does not impact upstream main.

Long Running Epic Branches

All my rules above are great for single changes applied directly to main. However, some teams work on long running epic branches to avoid introducing changes to main that are not ready for release. The best way to avoid long running epic branches is feature flags, but some teams aren’t able to use these for one reason or another.

That’s ok! For this situation, I recommend the following:

Create a base integration branch that is kept up with main using the merge strategy
Create individual branches off the integration branch and follow my instructions on individual branching from above
Squash merge branches back into the integration
Squash merge the integration back into main when ready

I’ve been on teams that try to do fancy rebase --onto strategies with the integration branch, and then the following individual branches. At the end of the day, this creates a lot of unnecessary git work for teams, and wastes time that is better spent working on features, bugs, and tech debt. This is because branches have to be updated in a particular way, and sometimes the conflicts that arise lead to lost changes and duplicated effort and work. Simplify your process and simplify your teams’ lives.

Conclusion

This only covers a few of the most common situations, but these general rules should help for teams and individuals in the way that is best for them while keeping the upstream main branch healthy and easier to debug when critical issues are identified.

I hope this helps you and your team on your next project and allows more time for technical debt and other important work that may have been lost to git related issues.

This Dot is a consultancy dedicated to guiding companies through their modernization and digital transformation journeys. Specializing in replatforming, modernizing, and launching new initiatives, we stand out by taking true ownership of your engineering projects.

We love helping teams with projects that have missed their deadlines or helping keep your strategic digital initiatives on course. Check out our case studies and our clients that trust us with their engineering.

Dustin Goodman

Engineering Manager with a passion for web and application development. Speaker and writer on work experiences and software development. Dog dad and musician fueled by coffee.

@dustinsgoodman @dustinsgoodman

Ensuring Accurate Workflow Status in GitHub for Enhanced Visibility

Introduction In the world of software development, GitHub workflows are crucial for automating CI/CD processes. However, a key challenge emerges when these workflows report a 'success' despite underlying issues, like failed tests. This is especially common in scenarios involving tests (e.g., Cypress) and notifications (e.g., Slack) within the same workflow. This blog post aims to highlight the importance of accurate GitHub workflow statuses for better visibility and team response, and how to ensure your workflows reflect the true outcome of their runs. The Problem with Misleading Workflow Statuses Consider a scenario in a GitHub workflow where end-to-end tests are run using Cypress. ` If these tests fail, but the workflow proceeds to a subsequent step, like sending a notification via Slack, which completes successfully, the entire workflow might still show a green checkmark. This misleading success status suggests everything is functioning as intended, when in fact, there could be significant underlying issues. The core issue is the determination of workflow success. Even if critical steps like testing fail, later steps without errors can override this, resulting in a false sense of security. This not only delays bug detection but can also lead to faulty code advancing in the CI/CD pipeline. It's crucial for the overall workflow status to accurately reflect failures in critical steps to ensure prompt and appropriate responses to issues. Crafting a Solution and Best Practices Ensuring Accurate Status Reporting To address the issue of misleading workflow statuses, it’s essential to configure your GitHub Actions properly. The goal is to ensure that the workflow accurately reflects the success or failure of critical tasks, such as running tests, regardless of the success of subsequent steps. Adjusting the Workflow Conditional Notifications: First, set up notifications to execute conditionally based on the outcome of critical steps. This ensures you're alerted of the workflow status without altering the overall result. For example, sending a Slack message if a Cypress test fails: ` Explicit Failure Handling: After configuring conditional notifications, explicitly handle failure scenarios. If a critical step like a Cypress test fails, force the workflow to exit with a failure status. This step is crucial to ensure that the overall workflow reflects the true status: ` Best Practices: Clear Step Separation: Clearly separate and label each step in your workflow for easier readability and troubleshooting. Regular Reviews: Periodically review your workflows to ensure they are aligned with the latest project requirements and best practices. Document Workflow Logic: Maintain documentation for your workflows, especially for complex ones, to aid in understanding and future modifications. By first setting up conditional notifications and then enforcing explicit failure handling, you maintain both alertness to issues and accuracy in workflow status. This approach ensures that failures in critical steps like tests are not overshadowed by subsequent successful steps, keeping the reported status of your workflow true to its actual state. Conclusion Accurate GitHub workflow statuses are vital for a transparent and efficient CI/CD process. By implementing conditional notifications and explicit failure handling, we ensure that our workflows truthfully represent the success or failure of critical tasks. This not only fosters better issue awareness and response but also upholds the integrity of our development practices. Embrace these steps as part of your commitment to maintaining clear and reliable automation processes in your projects. Happy coding!...

Mar 22, 2024

3 mins

GitHubGit

Git Bisect: the Time Traveling Bug Finder

I think it’s safe to say that most of us have been in a situation where we pull down some changes from main and something breaks unexpectedly, or a bug got introduced in a recent deployment. It might not take long to narrow down which commit caused the issue if there’s only a couple of new commits, but if you’re a dozen or more commits behind, it can be a daunting task to determine which one caused it. But can’t I just check each commit until I find the culprit? You could just check each commit individually without any special tools until you find the one that caused the issue, but that can be a very slow process. This is not ideal and is analogous to the reason why linear search isn’t as effective as binary search. As the title suggests, there is a tool that Git provides called “bisect”. What this command does is checks out various commit refs in the tree of the branch you’re currently working in and allows you to mark commits as, “good”, “bad”, or “skip” (invalid / broken build). It does away with the need of having to check each commit individually as it is able to infer if commits are good or bad based on which other commits you have already marked. Git Bisect in Action Let’s imagine a hypothetical scenario where some bug was reported for the software we’re working on. Starting a git bisect session usually looks like the following example. ` In this case, the commit hash in this example comes from a commit that I already know works. In the case where you pull down changes, and only then does something break, you can use whatever commit you were at prior before you pulled them down. If it’s an older bug, then you could check an older tag or two to see if it exists there. Next is the part where we search for the offending commit. Every time you mark a commit, bisect will then navigate to another commit in-between your good and bad starting points using a specialized binary search algorithm. ` This is the general workflow you will follow when bisecting for its most basic use case, and these commands will be repeated until there are no more revisions left to review. Bisect will try to predict how many steps are left, and let you know every time you mark a commit. Once you are done, you will be checked into the commit that introduced the regression. This assumes that you marked everything accurately! After you are done bisecting, you can quickly return to where you started by running git bisect reset. How Git Bisect Works Firstly, bisect makes the reasonable assumption that any commits after a bad commit remain bad, and any commits before a good commit remain good. It then continues to narrow down which commit is the cause by asking you to check the middlemost commit, along with some added bias when navigating around invalid commits. Though, that’s not vitally important to understand as a user of the command. The following graphic shows how bisect moves throughout your branch’s history. Bisect becomes incredibly useful when dealing with repositories with a lot of history, or when tracking down the cause of a bug that’s been in a codebase for a long time. It makes it possible to mule over hundreds of commits in fewer than a dozen steps! That’s a lot better than going through commits one-by-one or at random. Limitations It is worth mentioning that bisect isn’t as useful in cases where commits are very large because they incorporate several different changes all bundled together (e.g. squash merges). In an ideal world, each commit in the main branch’s history can be built, and they will implement or fix one thing and one thing only. But in reality, this isn’t always the case. The skip command is available to help with this scenario, but even with that, it’s possible that a change that caused the bug is in one of those skipped commits; therefore, relying solely on the diff of the determined commit to find the root cause of a bug may be misleading. Conclusion Git bisect is a very useful tool that can dramatically decrease the amount of time it takes to identify the cause of a regression. I would also recommend reading the official documentation on git bisect as it’s actually quite informative! There are a lot of good examples in here that demonstrate how you can use the command to its full potential....

Sep 7, 2022

4 mins

GitJavaScript

Getting the most out of your project management tool

Getting the most out of your project management tool There are several project management tools on the market that all aim to help your team gain productivity. Each tool has guiding principles and philosophies for managing projects and structuring your team. These stratagems may only sometimes apply to your team, or your team may evolve and discover new priorities they want to track. In this post, we’ll cover the concepts you should consider when understanding how your team operates and how project management tooling principles can impact your teams. Once you have a tool, we’ll share how you can set it up to align with your team through an example of how we achieved results. Understanding how your team operates Does your team run an agile workflow? Are you a waterfall organization? Do you ascribe to Kanban methodologies? Do you take pieces of each of these processes and merge them to allow your teams to organize and operate in a meaningful way? I discuss this topic in more depth in our Engineering Leadership podcast, but these methodologies need to align with the metrics you care about. As organizational leaders, you need to share what you’re tracking with your teams. These typically include Objectives and Key Results (OKRs) or Key Performance Insights (KPIs) curated for your team’s functional area. Your project management tool could inform some of the metrics you select. For instance, DevOps teams may care about DORA, or customer success teams may need to track the time to resolve customer-facing issues. Development teams may leverage these tools to coordinate the work on efforts to avoid duplication of effort, while others may invest in velocity metrics to inform product teams of capacity. Regardless of what metrics you’re gathering, validating that your tool can provide these metrics is essential. Tooling Principles I’ve used various project management software, including Jira, Linear, GitHub Projects, Pivotal Tracker, Asana, and Trello. Each tool is structured slightly differently and has different best practices and approaches. For example, Jira attempts to be the all-in-one tool for organizations giving extreme flexibility in how you set and configure projects. On the other hand, you have tools like Linear that are strongly opinionated and have clear guidance on how to use the tool. When selecting a tool, it’s essential to understand its operating principles and how they relate to your team’s operating habits. This isn’t to say these tools cannot be adjusted to work for your use cases and needs, but some will be easier to adapt than others for specific situations. It’s important to select tools not only for their user-friendliness but also for their adaptability to your organization’s needs. In some cases, this may lead to your team utilizing multiple tools. Given any budget constraints, this may not be ideal, so as organizational leaders, it is vital to have those discussions with our peers to determine what would benefit our team the most. If a single tool cannot solve all your needs, try to limit each department to a single tool. Given their functional area and KPIs, you can likely manage this situation easily through monthly and quarterly reporting shared with your organization. If your department is using different tools, you will probably need to set up external reporting means to aggregate those sources of truth or find a way to connect these apps. Some of these tools have integrations that allow you to sync them, but I’ve found those setups to be clunky and create more overhead for simple reporting facets you need. Regardless of your decision, you must configure these tools for your organization’s success. Setting up your tool for success With our operation practices determined and the tool that makes sense for our team based on principles and experience found, it is time to set up the tool for your team’s success. I will share my setup based on how my team operates to demonstrate what this could look like for you. As a consultancy, my team tends to operate in a waterfall model, as clients have us coming in for specific projects with defined scopes. However, we demonstrate progress to clients on a weekly or biweekly basis. This means we need a tool to help us plan out several months of work and milestones while allowing us to manage it weekly. Our clients aren’t typically interested in micro-details for these projects but care about the macro level of deliverables against milestones. Given these parameters, our team leverages GitHub Projects for our project management. We like it as the tickets stay close to the code, and we can use GitHub’s built-in functionality to manage most of our needs. This prevents our team from learning multiple tools and allows us to build custom workflows quickly using GitHub Actions as needed. This is an example of a project we ran. I’ve omitted details for privacy reasons, but we ran weekly iterations on this project. We also tracked priority and sized issues to help us understand what deliverables we could demonstrate each week. This helped our team organize around how much we knew we could complete each iteration and allowed team members to pull in additional work each week, given we prioritized other issues and their size. If they needed another issue on a Friday before the iteration ended, they could pull the next issue assigned to them from the next iteration or backlog, allowing for a continuous flow of work week-over-week. If an iteration was not completed, it gave us the information we needed to understand why the work may not be complete and allowed us to plan better for the next iteration. This workflow allows our team to focus on the client's needs and operate in a way they have ownership over the work as each team member commits to the work they agree to before it’s brought into an iteration. If we needed milestones, we could also assign those to tasks and track them, leveraging other GitHub built-in features. These are generally the types of things you should look for when setting up a tool for your team. Conclusion Project management tools are not just for project managers to dictate work to teams. When aligned with how teams operate and their goals, these tools can help your teams achieve at a higher level. Creating processes that don’t align with your team’s daily function to gather non-priority metrics through tools creates resistance and challenges leading to non-performing teams. Suppose your team is struggling because deliverables are not aligning with business goals and metrics. In that case, this is an excellent opportunity to check your processes and team operations and realign them if you discover they are out of sync. At This Dot, no single process works for all teams and organizations. We work with our teams and clients to determine what processes align with their objectives and goals. The process described above works great for our team but may not work for your team. However, the principles outlined above can aid you in finding the process that works best for your team. If you need help finding your process, contact us to help your team find their groove....

Jan 17, 2024

6 mins

Project Management

6 Steps to AI Adoption: Building with AI APIs

Tracy Lee, Jerome Hardaway, and Rob Ocel continue their six part series on the six steps for AI adoption. In this episode they discuss AI API integration and better building with AI models. One key takeaway was the importance of choosing the right tools for specific tasks. Jerome emphasized the significance of using content moderation APIs for filtering inappropriate content as an example. These tools help developers improve user experiences by ensuring content accuracy and appropriateness. However, Jerome also warned against blindly relying on AI tools and encouraged programmers to assess their benefits and limitations before implementation. The discussion also touched on how AI impacts coding abilities and problem-solving. AI-powered tools can boost developer productivity by automating repetitive tasks and offering helpful suggestions. Yet, it's important to strike a balance and not become overly dependent on AI, which could hinder critical thinking and problem-solving skills crucial for programmers. One challenge discussed was the difficulty of working with poorly documented APIs, which makes it hard for developers to understand and utilize AI tools effectively. While AI has the potential to enhance productivity and user experiences, it's important for developers to choose the right tools and avoid over-reliance. By carefully evaluating AI tools and investing in clear documentation, developers can leverage AI effectively to improve their coding abilities and problem-solving skills. Download this episode here!...

Apr 15, 2024

2 mins

AIArtificial Intelligence

Git Strategies for Working on Teams

Background

Always Branch and Pull Request to Main

Merges to main via Squash and Merge

Individual Branching

Long Running Epic Branches

Conclusion

Dustin Goodman

You might also like

Ensuring Accurate Workflow Status in GitHub for Enhanced Visibility

Git Bisect: the Time Traveling Bug Finder

Getting the most out of your project management tool

6 Steps to AI Adoption: Building with AI APIs

You might also like

Ensuring Accurate Workflow Status in GitHub for Enhanced Visibility

Git Bisect: the Time Traveling Bug Finder

Getting the most out of your project management tool

6 Steps to AI Adoption: Building with AI APIs