<?xml version="1.0" encoding="UTF-8"?><rss xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:content="http://purl.org/rss/1.0/modules/content/" xmlns:atom="http://www.w3.org/2005/Atom" version="2.0" xmlns:cc="http://cyber.law.harvard.edu/rss/creativeCommonsRssModule.html">
    <channel>
        <title><![CDATA[Stories by Britton Broderick on Medium]]></title>
        <description><![CDATA[Stories by Britton Broderick on Medium]]></description>
        <link>https://medium.com/@brit_broderick?source=rss-269b453fdab6------2</link>
        <image>
            <url>https://cdn-images-1.medium.com/fit/c/150/150/1*hPKZ7dU5kC0F6lB27ru-dQ.jpeg</url>
            <title>Stories by Britton Broderick on Medium</title>
            <link>https://medium.com/@brit_broderick?source=rss-269b453fdab6------2</link>
        </image>
        <generator>Medium</generator>
        <lastBuildDate>Fri, 20 Nov 2026 02:04:24 GMT</lastBuildDate>
        <atom:link href="https://medium.com/@brit_broderick/feed" rel="self" type="application/rss+xml"/>
        <webMaster><![CDATA[yourfriends@medium.com]]></webMaster>
        <atom:link href="http://medium.superfeedr.com/" rel="hub"/>
        <item>
            <title><![CDATA[KPIs for Early Stage CTOs]]></title>
            <link>https://medium.com/@brit_broderick/kpis-for-early-stage-ctos-df76410e354?source=rss-269b453fdab6------2</link>
            <guid isPermaLink="false">https://medium.com/p/df76410e354</guid>
            <category><![CDATA[software-development]]></category>
            <category><![CDATA[software-engineering]]></category>
            <category><![CDATA[cto]]></category>
            <category><![CDATA[kpi]]></category>
            <category><![CDATA[programming]]></category>
            <dc:creator><![CDATA[Britton Broderick]]></dc:creator>
            <pubDate>Sun, 30 Oct 2022 21:01:25 GMT</pubDate>
            <atom:updated>2023-07-16T18:47:45.394Z</atom:updated>
            <content:encoded><![CDATA[<figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/0*9c5Sw8xNQPDRTrbr.jpg" /></figure><p>There are a few metrics that you ought to be interested in as an early stage technology leader, whether you’re in Engineering, Product, or the combination of the two, <strong>Delivery</strong> (borrowed from Jonathan Nolen at Launch Darkly, courtesy of the<a href="https://www.developingleadership.co/episode/episode-17-building-product-delivery-organizations-with-jonathan-nolen-from-launchdarkly"> Developing Leadership Podcast</a>).</p><h3>Individual Pulse Metrics</h3><p>There are some metrics that I find useful for keeping a pulse on individual engineers. But, they are only for starting conversations with them and their team, not for using them as the stick to beat them with.</p><p>These may or may not be available, or they may or may not be the purview of all individual contributors. Use what your organization makes available.</p><ul><li>Technical specifications submitted</li><li>Technical specification reviews submitted</li><li>Commits pushed</li><li>Pull requests submitted</li><li>Code reviews submitted</li></ul><p>None of these will authoritatively tell you whether or not someone is working. They may be working by pairing or mobbing, which may not show up here. Or they may be doing other work you need to make visible to the organization. Finally, they may be gaming these metrics to keep you off their back.</p><p>More importantly, none of these will tell you if individuals are working on the most valuable thing possible.</p><p>Again, these are all things you use to inform and kick-start visibility conversations with your team in the event that you have concerns about individual performance on a team.</p><p>These can be tracked using something like Code Climate’s Velocity product, or using your own hand rolled stat gathering tool interacting with something like GitHub’s CLI.</p><h3>Metrics are for teams (not individuals!)</h3><p>There are some things that are interesting about the metrics of individuals, but just like in sports, whether physical or electronic, putting a team of all-stars together often results in worse performance than those all-stars on their normal respective teams.</p><p>And remember,<a href="https://pubsonline.informs.org/doi/10.1287/orsc.2022.1619"> high performing teams follow power laws</a>. Team performance doesn’t follow a normal distribution. This means that high performing teams are likely to far outpace the average.</p><p>You’re not looking for high performers individually, but how to build them into cohesive teams that hit their stride, complement each other, and push outside the bounds of a normal distribution through continuous learning..</p><h3>Engineering Metrics</h3><p>These are metrics unique to an engineering organization, without the influence of the product organization.</p><h3>DORA Metrics</h3><p>The DORA Metrics are table stakes when considering only the engineering portion of the organization. This isn’t a holistic picture, and I believe that <strong>Delivery</strong>, rolling up to a single individual responsible for both <strong>Product and Engineering</strong>, is the role that makes sense. But if you can only control engineering, you start with this.</p><p>These measures are more about the capability of the team, although I think it’s also important to consider the actuals. What this means concretely I’ll discuss in each section.</p><p>How each of these is tracked will depend on your organization’s toolchain. Unfortunately, there isn’t yet a one size fits all way to track this information.</p><h4>Deployment Frequency</h4><p><em>How often a team successfully releases to production.</em></p><p>This is especially useful in the context of how often your team is actually doing work on the code that will be deployed.</p><p>For example if you’ve got your deployment pipeline setup so you can deploy in a repeatable, automated fashion in less than 10 minutes, but you only actually deploy that code once a month, because that’s the frequency with which it’s necessary to deploy small updates, awesome. Your team is high performing.</p><p>But if you have processes and procedures in place ensuring you can only deploy code to production once per month, you have room for significant improvement.</p><p>This can be tracked by multiple services including most application monitoring services, your CI/CD service, or posting data during the deploy process to a centralized monitoring service.</p><p><strong>Target range is “on-demand”, multiple times per day.</strong></p><h4>Lead Time for Changes</h4><p><em>The amount of time it takes a commit to get into production.</em></p><p>This includes all steps in your process, human or automated, actively being worked, or idly sitting in a queue. In fact, the times where it is idly sitting in a queue are the most interesting from the perspective of this metric. Those flow blockers are often the most serious inhibitors of your engineering organization’s ability to deliver value.</p><p>Whether it’s queued up for manual validation, waiting for code review, or in a merge train waiting for human approval, all of these queued times are waste that should be considered for elimination.</p><p>I have really never encountered a reason for any change to take more than one hour to get to production.</p><p>This can be tracked by tools like Code Climate’s Velocity, or combining deploy metrics from CI/CD servers and Git metrics.</p><p><strong>Target range is less than one hour.</strong></p><h4>Change Failure Rate</h4><p><em>How many times a production deploy resulted in a negatively impacted user experience, divided by the number of times the team deployed to production.</em></p><p>You may notice this pushes you to “gamify” the metric, by going for tons of tiny, frequent deploys. This is a feature, not a bug.</p><p>If you’re deploying constantly, you can more easily pin point when you introduce an issue. It forces your engineers to work in smaller batches which goes into one of the other metrics of small changes capping at around 500 lines of code. It forces you to have high-quality instrumentation in place because otherwise when you’re all those changes out you won’t know when you introduce a breaking change.</p><p>Finally, it forces you into the healthy habit of extensive use of automated testing because you cannot deploy 30 times a day if each time you have to run through a long manual test cycle in order to ensure the safety of your deploy.</p><p>This is one that has to be tracked at least partially manually. You can track much of it in an automated way, depending on if your deploys will automatically rollback when certain metric thresholds are crossed. But it likely also has to be tied back to your issue tracker. You ought to pull the deploy frequency in one of the ways mentioned above, but the count of failures will need to be summed based on a combination of issue tracking and automated rollback metrics.</p><p><strong>Target range is 0 to 15%.</strong></p><h4>Time to Restore Service</h4><p><em>How long it takes an organization to recover from a failure in production.</em></p><p>Where a <em>failure</em> is defined as anything that negatively impacts the user. Notice that the <em>impact</em> of the failure here isn’t relevant.</p><p>Previously known as Mean Time to Recovery (MTTR). This is probably the DORA metric that generates the most controversy, but from my perspective makes sense. It’s concerned, although less so, about “Black Swan” style unexpected and unpredictable events, but rather most interestingly tells you about your organization’s maturity around mean time to discovery, and remediation through rollback.</p><p>If you’ve got beef with that MTTR, you’re likely at either end of the distribution, which can be interesting for informing what you do with this metric.</p><p>If your org is mature, you may not need to track this one. If not, you need to get to the place where most of your incidents are discovered quickly, and recovered from quickly, ideally in an automated fashion. If you’re not sure which bucket your organization falls into, assume it needs to track this.</p><p>Tracking this one is something that I’ve once again only seen done with a combination of automated and manual processes. Given that you should be able to tie a particular commit to a point in time deploy and/or feature flag toggle, and a resolution to a point deploy and/or feature flag toggle you should be able to gather this data as well, tying it all back to an incident report and change failure.</p><p><strong>Target range is less than one hour.</strong></p><h4>Reliability</h4><p>The fifth DORA metric is newer, first released in the 2021 State of DevOps Report. It measures operational performance, and is a measure of modern operational practices. Reliability is the degree to which a team can keep promises and assertions about the software they operate.</p><p>Unfortunately at the time of writing, the DORA team doesn’t define any concrete benchmarks for reliability, but instead gives guidance about sociotechnical practices that lead to better organizational performance against reliability.</p><p>Teams ought to:</p><ul><li>Define reliability in terms of user-facing behavior</li><li>Employ the<a href="https://cloud.google.com/blog/products/devops-sre/sre-fundamentals-sli-vs-slo-vs-sla"> Service Level Indicator (SLI)/Service Level Objective (SLO) metrics</a> framework to prioritize work according to error budgets</li><li>Use automation to reduce manual work and disruptive alerts</li><li>Define protocols and preparedness drills for incident response</li><li>Incorporate reliability principles throughout the software delivery lifecycle (“shift left on reliability”)</li></ul><p>Along with these 5 bullet points, in the 2021 report they explicitly highlight documentation as a key practice, with teams that make documentation and playbook generation a key part of their culture are 2.4 times more likely to meet or exceed reliability targets.</p><p>The DORA folks don’t list a target range for reliability metrics at this point, or even specific reliability metrics, but this is something that should be gathered automatically as part of telemetry data that you build into the process of developing software, and specific to your organization’s needs. Medical device software will have more stringent reliability needs than an attention economy consumer app.</p><h3>Patch Sizes</h3><p>Most patches/pull requests should be under 500 lines of code, based on research put out by SmartBear and Cisco, which mirrors my personal experience.</p><p>I like to be very opinionated and strive to keep most of the changes under 200 lines of code, as I’ve found that is the easiest format for most folks to review.</p><p>It’s important to note here that it’s <em>lines of code</em> all-in in this case. That includes comments, tests, documentation etc. Keeping it constrained in this way helps to keep reviewers focused and attentive.</p><p>Larger PRs tend to be harder to review in the same way, either decreasing the quality of the review, or dramatically increasing the time it takes, and the number of review cycles, as a thorough review of a larger PR means a higher probability of finding mistakes that need correction.</p><p>All of this leads to frustration and results in a higher probability of the code not being reviewed and merged on the same day it was created, reducing your ability to practice continuous integration.</p><h3>Defect Rate</h3><p>This is one that I find useful for existing codebases, because you may deploy to production and then notice a defect that isn’t related to the code that you just pushed.</p><p>I advocate not counting that as a change fail if it isn’t introduced because of the newly deployed code.</p><p>If the newly deployed code uncovers an issue that was previously hidden, or changes the performance characteristics of the system in a negative way, that is a change fail.</p><p>Otherwise, it’s a historical defect. Change fails are defects, but not all defects are change fails.</p><p>The defect rate is measured by the number of defects uncovered, whether in the form of change fails, or legacy defects, <strong>divided by the number of commits</strong>.</p><p>This is one that I have only been able to track via the issue tracker, as that’s where these things surface and are recorded. I think they’re still valuable to retro on, and do an incident report for, using your current software development process as a foil. See if it would be caught with the changes that have been made since its inception.</p><p>The target defect rate would be 0–15%, which ties in with the change fail rate, but could likely be padded slightly in the context of a legacy codebase.</p><h3>Product Metrics</h3><p>These are the metrics that are specific to your domain, and line of business, these could be:</p><ul><li>Conversion rate</li><li>Usage of specific functionality in your application</li><li>Customer acquisition cost (CAC)</li><li>Customer Satisfaction metrics — these are usually lagging, if we can turn them into leading indicators that’s always preferable.</li></ul><p>These are actually the most important metrics that your teams and organizations are responsible for. Everything else is in support of this.</p><p>You want good engineering and delivery metrics in order to ensure the Product needs are being met. Without these dialed in, the greatest delivery team and process doesn’t matter. But a solid process will enable you to do this better than your competition.</p><p>A process leading to faster iterations is critical. Even if you aren’t always doing the right thing, because you’re at bat more often you’ll likely end up outmaneuvering and out performing your competition.</p><h3>Delivery Metrics</h3><p>Delivery metrics are those that are best suited to being measured in a way that crosscuts product and engineering as separate disciplines, if it’s within your power to make that call.</p><h3>Lead Time</h3><p>Time from the idea begins being worked, to the time that it’s in user hands.</p><p>Being worked is defined as the point when Product takes the idea and begins discovery work, to validate it as being worth implementing or not.</p><p>A second lead time that may be valuable would be the delivery lead time, post discovery. After Product has validated that you do in fact want to build some piece of functionality, how long does it take to design that functionality and get in production?</p><p>The best way to reduce your lead time is to avoid queues and handoffs. for example a backlog where you park ideas that Product has done design work for and wait for a dev team to have free capacity. (See the following sections on Queue Times and WIP Limits.)</p><h3>Queue Times</h3><p>If in either the Product or Engineering side of delivery, pieces of work are idle in a queue, spend time analyzing that.</p><p>These are going to be the single biggest points of failure to deliver in your organization, and are going to be the things that build up a false sense of progress and organizational capacity.</p><p>Things that are “started” by Product, and then queued up for when engineering finally gets around to having bandwidth are one of the leading drivers of organizational mistrust, and a lack of sense of progress.</p><p>This will also expose where your process needs improved.</p><p>If you have a heavy manual QA process you could have changes that are code complete and unable to ship because of queue time there. Either because they aren’t at the front of the line, or because the entire queue is blocked by a change that introduced an issue.</p><p>The best way to reduce queue times is to introduce work in progress (WIP) limits, moving you closer to a single piece flow.</p><h3>Work in Progress Limits</h3><p>Work in progress (WIP) limits are critical to maintaining a flow in a team.</p><p>You will always have more work than your team can possibly handle. (And if not, you’ve likely got way too many folks on the team. See Charity Major’s article<a href="https://charity.wtf/2022/10/03/every-achievement-has-a-denominator/"> <em>Every Achievement Has A Denominator</em></a><em>.</em>)</p><p>Given that, you need to prioritize.</p><p>We learn from queuing theory the more work we try to do in parallel, as individuals, or as teams, the longer it takes to get anything and everything done, and the more time it spends waiting in queues, which means by definition it’s not delivering value for the user.</p><p>Kanban as a system isn’t just about the silly board. The board is a useful tool for visualization, but the primary value you can derive from it in software engineering is the fact that it allows a demand based system.</p><p>The team only pulls new additional work as it has capacity to work on it. This gives you real, hard feedback on how much your team can be doing at any given moment. Either you’ve got sufficient capacity to meet the needs of the organization or you don’t.</p><p>This however, can be incredibly difficult to stick to.</p><p>An undisciplined organization, or one where executives outside technology think they can get more done by just making folks work more, will immediately cave at the first sign of organizational pressure.</p><p>You’ll begin a vicious cycle of taking on more work than you have capacity for and fail to show progress or deliver in a timely manner.</p><p>This breaks trust due to broken expectations and creates animosity between “the business that doesn’t understand what it takes to make great technology” and “those engineers that are never accountable and can never make their deadlines”.</p><h3>Inventory Levels</h3><p>Just because single piece flow is ideal, doesn’t mean that you should be running a zero inventory just in time flow. You may have the team composition to support that, but you may not.</p><p>Your organization likely has different cycle times for each step, for example discovery work being done will often take quite a bit longer than much of the engineering work to implement a simple feature. Or the new feature may require significant work so you probably want some level of inventory built up. How much depends on your organization, but if you’re most organizations, you’ve likely been erring on the side of far too much, rather than not enough.</p><p>If you don’t retain some inventory that can result in a bad time for folks downstream in engineering being unable to pull work.</p><p>You can see an example of this in the way a number of auto manufacturers<a href="https://en.wikipedia.org/wiki/Cargo_cult"> cargo-culted</a> the Toyota just in time manufacturing flow and that led them to carrying almost no inventory, which caused them problems with the onset of COVID.</p><h3>Conclusion</h3><p>There’s a lot to consider as an early stage CTO. This isn’t going to be all of it, but hopefully this gets you started on the right foot.</p><p>And remember, <a href="https://pubsonline.informs.org/doi/10.1287/orsc.2022.1619">high performing teams follow power laws</a>. You’re not looking for high performers individually, but how to build them into cohesive teams that hit their stride, and push well outside the bounds of a normal distribution.</p><p>If you feel like there are some key KPIs I’m missing here, reach out. I’d love to discuss. You can reach me at <a href="/service/mailto:brittonbroderick@gmail.com">brittonbroderick@gmail.com</a>.</p><p><em>Originally published at </em><a href="https://brittonbroderick.com/2022/10/30/kpis-for-early-stage-ctos/"><em>https://brittonbroderick.com</em></a><em> on October 30, 2022.</em></p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=df76410e354" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Strong Style Pairing and Mobbing — The Smart Keyboard]]></title>
            <link>https://medium.com/@brit_broderick/strong-style-pairing-and-mobbing-the-smart-keyboard-5e015ced6f71?source=rss-269b453fdab6------2</link>
            <guid isPermaLink="false">https://medium.com/p/5e015ced6f71</guid>
            <category><![CDATA[pair-programming]]></category>
            <category><![CDATA[software-development]]></category>
            <category><![CDATA[software-engineering]]></category>
            <category><![CDATA[mob-programming]]></category>
            <category><![CDATA[programming]]></category>
            <dc:creator><![CDATA[Britton Broderick]]></dc:creator>
            <pubDate>Thu, 15 Sep 2022 00:32:17 GMT</pubDate>
            <atom:updated>2023-07-16T18:44:13.196Z</atom:updated>
            <content:encoded><![CDATA[<h3>Strong Style Pairing and Mobbing — The Smart Keyboard</h3><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/0*EFK0nWniVVZ_5l2T.jpg" /></figure><p>One of the most powerful approaches to pairing or mobbing is “strong-style”.</p><p>To utilize this style, you just need one simple rule:</p><blockquote><em>In order for an idea to go from your head into the computer, it must go through someone else’s hands.</em></blockquote><p>The navigator in a traditional pair (or mob) becomes a smart keyboard. This keyboard is gifted with the ability to questions in order to better understand the problem and solution, or to coach the driver into sharpening their thinking and ability to describe them.</p><p>This is a valuable tool for coaching less experienced individuals. It forces them to understand what seniors are asking them to do when they’re driving. And when they’re navigating it forces them to articulate how want to solve a problem.</p><p>Then they get real time feedback on the quality of their solutions from other members of the team. In the event that the more senior members of the team have ideas they feel strongly about while driving, they can and should give the junior immediate feedback by handing over the keyboard and talking them through implementing it the better way.</p><p>In this way everyone wins, and it’s a much faster feedback loop than traditional code review.</p><p>This approach also strongly discourages disengagement whether mobbing or pairing.</p><p>As a navigator because you know that you’ll be letting the driver down if you don’t give them input so they “have permission” to type the solution.</p><p>As driver you can’t disengage or you’re ignoring your team and nothing gets done.</p><p>If you can’t put your idea to the keyboard without using someone else’s hands it’s much harder to disengage.</p><p><em>Originally published at </em><a href="https://brittonbroderick.com/2022/09/15/strong-style-pairing-and-mobbing-the-smart-keyboard/"><em>https://brittonbroderick.com</em></a><em> on September 15, 2022.</em></p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=5e015ced6f71" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[You’re Here to Solve Problems — Not Write Code]]></title>
            <link>https://medium.com/@brit_broderick/youre-here-to-solve-problems-not-write-code-4d8312076f70?source=rss-269b453fdab6------2</link>
            <guid isPermaLink="false">https://medium.com/p/4d8312076f70</guid>
            <category><![CDATA[software-development]]></category>
            <category><![CDATA[software-engineering]]></category>
            <dc:creator><![CDATA[Britton Broderick]]></dc:creator>
            <pubDate>Sat, 11 Jun 2022 23:41:06 GMT</pubDate>
            <atom:updated>2022-07-25T02:43:27.870Z</atom:updated>
            <content:encoded><![CDATA[<h3>You’re Here to Solve Problems — Not Write Code</h3><p>As a software engineer, you’re here to solve real problems. Not to write code.</p><p>Code is often a useful tool to solve problems, because a lot of things are incredibly tedious to do and easy to automate, or do faster, more accurately and/or reliably with code.</p><p>But it can also be the wrong tool to reach for. Often adding code is the most expensive tool to reach for. It’s expensive to write, and then an even more expensive liability to test, and maintain.</p><p>Or it may be only part of the solution, after you better understand the problem.</p><h3>Maybe reach for something else…</h3><p>If you’ve got a one off task that you’ve never done before, and will likely never do again, that will only take you 15 minutes, it’s probably best to just do that manually.</p><p>Or if you’re trying to solve the problem of ensuring a user fills out a form properly, maybe stop and think about if you’ve already got this data, and can sidestep the problem entirely by pulling the data over from another system.</p><p>Finally, creating a process that automates the maintenance of your bespoke database may be less useful than work migrating to an off the shelf open source solution that would also meet your needs.</p><h3>Understand the problem</h3><p>Writing code before you understand the problem is asking to either:</p><ol><li>Cause yourself or your team a lot of pain as you attempt to extend code based around a problem that you didn’t understand</li><li>Volunteering to have a bunch of your hard work thrown away, whether you’d like to or not because it solves the wrong problem.</li></ol><p>If you start writing code before you understand the problem you will likely end up automating something that shouldn’t be automated, or writing code for something that shouldn’t be solved with code.</p><p>If you can solve the problem by suggesting a different upstream process that’s actually easier to implement, that’s a superior solution, and I want to hear that. Code is a tool to extend abilities and act as a force multiplier. But any number multiplied by zero is still zero.</p><h3>But it doesn’t feel as good</h3><p>I know you want to immediately reach for the code because it feels good. It’s comforting. Familiar. It feels satisfying to create, and more tangible than solving the problem without it.</p><p>But resist the need for that dopamine hit. Figure out how to solve the problem in the simplest way possible first. Then, and only then, write the code, and only if it’s necessary.</p><h3>It’s done!</h3><p>A problem isn’t solved when you intellectually solve it. It’s solved when it’s in the hands of users actually solving their problem.</p><blockquote><em>It’s code complete!</em></blockquote><p>Doesn’t matter if it isn’t deployed.</p><p>Let’s solve some problems.</p><p><em>Originally published at </em><a href="https://brittonbroderick.com/2022/06/11/youre-here-to-solve-problems-not-write-code/"><em>https://brittonbroderick.com</em></a><em> on June 11, 2022.</em></p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=4d8312076f70" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Using Architectural Decision Records]]></title>
            <link>https://medium.com/@brit_broderick/using-architectural-decision-records-142b44baece8?source=rss-269b453fdab6------2</link>
            <guid isPermaLink="false">https://medium.com/p/142b44baece8</guid>
            <category><![CDATA[software-engineering]]></category>
            <category><![CDATA[software-development]]></category>
            <category><![CDATA[documentation]]></category>
            <dc:creator><![CDATA[Britton Broderick]]></dc:creator>
            <pubDate>Sat, 07 May 2022 19:23:04 GMT</pubDate>
            <atom:updated>2022-05-14T03:02:22.470Z</atom:updated>
            <content:encoded><![CDATA[<figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/0*wzkHRkC06nPCgckz.jpg" /></figure><p>An Architectural Decision Record (ADR) is a historical record outlining why decisions were made. They also document tech and team norms as they are adopted.</p><p>They do not serve as documentation for code. That should live in the codebase itself, supported by documentation constructs provided by the language or supporting libraries.</p><p>Engineers introduced to a new codebase will ask why such a poor decision was made about a given feature. When revisiting part of the codebase years later you decide to rip out a piece you can’t see the value in, only to learn that it was critical when prod goes down later that day. You want to talk with the author of part of the codebase about why things are the way they are, only to learn they left the company years ago. Or they’re still around but have no idea why they did it that way, but they feel like it was important.</p><p>An ADR describes this while the information is fresh. You remember the context under which the decision was made, why it was made, because you’re here making it. It isn’t a poor decision or else you’d be making a different decision. When, in the future, circumstances have changed, it allows you to confidently change the decision made. See Chesterton’s Fence.</p><h3>Example</h3><pre># 6. Packaging and distribution in other version control repositories </pre><pre>Date: 2016-02-16</pre><pre>## Status</pre><pre>Accepted</pre><pre>## Context</pre><pre>Users want to install adr-tools with their preferred package manager. For example, Ubuntu users use apt, RedHat users use yum and Mac OS X users use Homebrew.</pre><pre>The developers of adr-tools don&#39;t know how, nor have permissions, to use all these packaging and distribution systems. Therefore packaging and distribution must be done by &quot;downstream&quot; parties.</pre><pre>The developers of the tool should not favour any one particular packaging and distribution solution.</pre><pre>## Decision</pre><pre>The adr-tools project will not contain any packaging or distribution scripts and config.</pre><pre>Packaging and distribution will be managed by other projects in separate version control repositories.</pre><pre>## Consequences</pre><pre>The git repo of this project will be simpler.</pre><pre>Eventually, users will not have to use Git to get the software.</pre><pre>We will have to tag releases in the adr-tools repository so that packaging projects know what can be published and how it should be identified.</pre><pre>We will document how users can install the software in this project&#39;s README file.</pre><p><a href="https://github.com/npryce/adr-tools/blob/master/doc/adr/0006-packaging-and-distribution-in-other-version-control-repositories.md">https://github.com/npryce/adr-tools/blob/master/doc/adr/0006-packaging-and-distribution-in-other-version-control-repositories.md</a></p><h3>Title</h3><p>The title should quickly summarize the decision at hand.</p><p>In year, month, day format, in order to most easily sort. Also avoids confusion as an international standard.</p><h3>Status</h3><p>One of the following:</p><ul><li>Proposed</li><li>Accepted</li><li>Rejected</li><li>Superseded — followed by a link to the superseding ADR.</li></ul><p>Indicates if the decision is being deliberated, has been accepted or rejected, or superseded by a followup decision, based on changing circumstances.</p><h3>Context</h3><p>From there, we have the context under which the decision was made. Users of this tool want to be able to install it in the most natural way on their OS. But currently, and for the foreseeable future, it’s outside the expertise of the team to build and maintain each of these packages. This is a decision that could change, though unlikely. It’s also unlikely that users will stop wanting to install the package via native OS package managers.</p><p>This section should include any constraints the organization is operating under, whether technical, financial, time based, or experience based. It should include any other options that are being considered, and the considerations for each option.</p><p>Describing the context is the primary future value of the ADR. This is what allows you to look back at the decision clearly and understand the information and constraints that were being operated against. This is also what allows you to know if the circumstances have changed enough to warrant changing the decision.</p><h3>Decision</h3><p>It then lists the straightforward decision that limits the scope of responsibility of the repo in a useful way.</p><p>The decision will likely be the shortest section, as it doesn’t detail the why, only what decision has been made, and how to act on it. Reasons for the decision belong in the Context and Consequences sections.</p><h3>Consequences</h3><p>Finally, it enumerates the consequences of the decision, in the short term and long. This includes new work it creates for the team, as well as benefits. This particular ADR doesn’t detail any potential negative consequences of the decision, because the team doesn’t see any. If there were potential negatives, they would be here as well.</p><p>Describing the consequences of the decision allows the future readers to understand how and why a particular judgment call was made, and reflect on if the particular consequences were foreseen with any accuracy, and if not, adjust how they forecast consequences of decisions.</p><h3>Method</h3><ol><li>Create a blank new ADR.</li><li>Set status to Proposed or Accepted, depending on if this has been decided by the team.</li><li>Describe the relevant context surrounding making the decision. This includes business constraints, personnel/skills constraints, environmental reasons, time constraints, cost constraints, or any other information that will be useful in understanding and potentially changing this decision in the future.</li><li>Describe the decision that is being made, and will be implemented.</li><li>Describe the consequences of this decision. Include the implications for the organization in the short and the long term. How can we best address these to mitigate risks, and maximize benefits. Are there any consequences that haven’t been given proper consideration?</li><li>Review the ADR yourself.</li><li>Publish the ADR for review, actively asking for contradicting opinions and ensuring all relevant context is captured.</li></ol><h3>Applying the Method</h3><h4>Step 1</h4><p>ADRs can be created using adr-tools, or simple Markdown templates.</p><h4>Step 2</h4><p>Depending on if the decision has already been made, and this serves as documentation for the decision, or if this is a proposal documenting a decision that is being considered.</p><h4>Step 3</h4><p>Describing the context is the primary future value of the ADR. This is what allows you to look back at the decision clearly and understand the information and constraints that were being operated against. This is also what allows you to know if the circumstances have changed enough to warrant changing the decision.</p><h4>Step 4</h4><p>Details the decision made against the background of the context.</p><h4>Step 5</h4><p>Describing the consequences of the decision allows the future readers to understand how and why a particular judgment call was made, and reflect on if the particular consequences were foreseen with any accuracy, and if not, adjust how they forecast consequences of decisions.</p><h4>Step 6</h4><p>Conducting a review of the document yourself is critical to ensuring you’re a good steward of the time of others that you interact with. This ensures you don’t waste their time with issues that you could have seen and addressed in advance.</p><h4>Step 7</h4><p>Open up the document for feedback from the team on its content and on the decision, if the decision hasn’t been made. Use it to hold a meeting if necessary to reach a decision, and document it.</p><h3>Conclusion</h3><p>Detail the context, the proposed decision, and the consequences. The team can then discuss the proposal and achieve consensus on whether or not to adopt the proposal, or reject it. Either way you keep it around as a record indicating why a given change decision was or was not made, to speed future discussion and work on the same idea.</p><p>This is likely not actually the first step in any given cycle, and depending on where you are in the company and its lifecycle may not be something you get to do for a while. Many individual contributors will create these infrequently, depending on the company culture.</p><p>ADRs are a powerful tool for understanding why decisions were made and reflect on if and when it’s appropriate to change them, without the fear of changing something without understanding why it exists today.</p><p>If you’ve seen success or struggle with implementing ADRs, I’d love to hear about it on Twitter or via email.</p><p><em>Originally published at </em><a href="https://brittonbroderick.com/2022/05/07/using-architectural-decision-records/"><em>https://brittonbroderick.com</em></a><em> on May 7, 2022.</em></p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=142b44baece8" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Tests as Documentation]]></title>
            <link>https://medium.com/@brit_broderick/tests-as-documentation-409d16a5ce85?source=rss-269b453fdab6------2</link>
            <guid isPermaLink="false">https://medium.com/p/409d16a5ce85</guid>
            <category><![CDATA[software-engineering]]></category>
            <category><![CDATA[software-development]]></category>
            <category><![CDATA[documentation]]></category>
            <category><![CDATA[testing]]></category>
            <dc:creator><![CDATA[Britton Broderick]]></dc:creator>
            <pubDate>Sat, 23 Apr 2022 18:20:00 GMT</pubDate>
            <atom:updated>2022-05-14T02:58:51.543Z</atom:updated>
            <content:encoded><![CDATA[<p>Tests ought to exist to document the desired usage and behavior of a given system.</p><p>This allows you to ship confidently.</p><p>If you’re unsure of the desired behavior of a system check for a test.</p><p>If a test doesn’t exist, write the test. Observe the behavior. Then ask if this matches what you’d expect or desire the behavior to be.</p><p>If it matches, awesome. You’re done. Commit the test to answer the question for your future self and other future engineers.</p><p>If it doesn’t match, then determine how it needs to change.</p><p>With this in mind, it’s easy to use the desired behaviors to guide the implementation and code review. It then serves as documentation, and defines the specification for when the work is done.</p><p>Finally, it allows actual refactoring, changing the implementation without changing the behavior.</p><p>None of this is new. It’s all behavior driven development (BDD).</p><p><em>Originally published at </em><a href="https://brittonbroderick.com/2022/04/23/tests-as-documentation/"><em>https://brittonbroderick.com</em></a><em> on April 23, 2022.</em></p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=409d16a5ce85" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Starting Browser Testing for Phoenix LiveView with Wallaby]]></title>
            <link>https://medium.com/@brit_broderick/starting-browser-testing-for-phoenix-liveview-with-wallaby-27222e00d870?source=rss-269b453fdab6------2</link>
            <guid isPermaLink="false">https://medium.com/p/27222e00d870</guid>
            <category><![CDATA[testing]]></category>
            <category><![CDATA[elixir]]></category>
            <category><![CDATA[phoenix-framework]]></category>
            <category><![CDATA[software-development]]></category>
            <category><![CDATA[liveview]]></category>
            <dc:creator><![CDATA[Britton Broderick]]></dc:creator>
            <pubDate>Sun, 20 Mar 2022 13:55:00 GMT</pubDate>
            <atom:updated>2022-05-27T03:10:44.426Z</atom:updated>
            <content:encoded><![CDATA[<p>Browser testing can be a powerful way to build confidence in your codebase, and it’s easy to get started in a Phoenix app with Wallaby.</p><p>I gave a <a href="https://brittonbroderick.com/conference-talks/#automated-browser-testing-for-phoenix-liveview-using-wallabythe-big-elixir-2022">conference talk</a> about this at <a href="https://thebigelixir.com/">The Big Elixir</a> 2022 with a few more examples. If you just want to dive into the code, it can be <a href="https://github.com/britton-jb/testing_live_view_wallaby">found here</a>.</p><h3>What is Wallaby?</h3><p><a href="https://github.com/elixir-wallaby/wallaby">Wallaby</a> is a browser testing tool written in Elixir that allows you to drive a browser, and write browser-based tests all without leaving the Elixir ecosystem. So you have access to all your favorite tools like ExUnit.</p><h3>Setting Up</h3><h4>Install Wallaby</h4><p>Add the dependency to your mix.exs:</p><pre># mix.exs<br>defp deps do<br>  ...<br>  {:wallaby, &quot;~&gt; 0.29.0&quot;, runtime: false, only: :test}<br>end</pre><h4>Install Chromedriver</h4><p>How you install the chromedriver is going to depend on your preferences. On MacOS you can install it with brew but the latest security updates make that a little more painful and less cross-platform friendly in the event that cross-platform matters to you.</p><pre>$ brew install --cask chromedriver &amp;&amp; \ xattr -d com.apple.quarantine /usr/local/Caskroom/chromedriver/$VERSION/chromedriver</pre><p>You can also install the binary directly from <a href="https://sites.google.com/chromium.org/driver/">https://sites.google.com/chromium.org/driver/</a>.</p><p>Finally, the easiest cross-platform option that I’ve found is just installing it via npm.</p><pre>$ npm install chromedriver --save-dev --prefix assets</pre><h4>Update the endpoint</h4><p>You need to update the endpoint.ex to leverage <a href="https://hexdocs.pm/ecto_sql/Ecto.Adapters.SQL.Sandbox.html">Ecto&#39;s SQL sandbox</a>, which allows your concurrent/async tests to be isolated at the database layer.</p><p>You also need to modify the socket connect_info to include :user_agent this means that the user agent information is passed along to the socket. The user agent is how Wallaby links up which isolated sandbox database process should be connected with the particular browser test session.</p><pre># lib/my_app_web/endpoint.ex<br>defmodule MyAppWeb.Endpoint do<br>  use Phoenix.Endpoint, otp_app: :my_app<br>  <br>  if Application.get_env(:my_app, :sql_sandbox) do<br>    plug(Phoenix.Ecto.SQL.Sandbox)<br>  end<br>  <br>  ...<br>  <br>  socket(&quot;/live&quot;, Phoenix.LiveView.Socket,<br>    websocket: [connect_info: [:user_agent, session: @session_options]]<br>  )<br><br>  ...<br>end</pre><h4>Update the test helper</h4><p>We need to ensure Wallaby is started as part of running your tests:</p><pre># test/test_helper.exs<br>{:ok, _} = Application.ensure_all_started(:wallaby)<br>...</pre><h4>Update the test config</h4><p>You now want to configure your application in test to use the Ecto SQL sandbox, and then you need to configure Wallaby.</p><pre># config/test.exs<br>import Config<br>...<br><br>config :my_app, sql_sandbox: true<br><br>config :wallaby,<br>  base_url: MyAppWeb.Endpoint.url(),<br>  otp_app: :my_app,<br>  screenshot_on_failure: true,<br>  chromedriver: [<br>    path: &quot;assets/node_modules/chromedriver/bin/chromedriver&quot;, # point to your chromedriver path<br>    headless: true # change to false if you want to see the browser in action<br>  ]</pre><p>A few of the options that you may want to consider modifying include:</p><ul><li>screenshot_on_failure - this option ensures that the . You can also configure the path to where the screenshots ought to be dumped.</li><li>chromedriver - includes the path to find the chromedriver binary, as well as headless mode, which determines if you&#39;ll see the actual browser bootup and take the actions you&#39;ve given it, or if it will run in the background.</li></ul><h4>Add the on_mount hook</h4><p>If you’re using <a href="https://hexdocs.pm/phoenix_live_view/Phoenix.LiveView.html">Phoenix LiveView</a> you’ll also need to add an on_mount hook, which leverages the mount lifecycle hook to ensure that on each LiveView mount the browser and test instance are correctly wired up together.</p><p>Note that this assumes <strong>Phoenix LiveView version 0.17.7</strong>. Things may have changed for you.</p><p>Below is an example hook implementation:</p><pre># lib/my_app_web/live/hooks/allow_ecto_sandbox.ex<br>defmodule MyAppWeb.Hooks.AllowEctoSandbox do<br>  import Phoenix.LiveView<br><br>  def on_mount(:default, _params, _session, socket) do<br>    allow_ecto_sandbox(socket)<br>    {:cont, socket}<br>  end<br><br>  defp allow_ecto_sandbox(socket) do<br>    if Application.get_env(:testing_live_view_wallaby, :sql_sandbox) do<br>      %{assigns: %{phoenix_ecto_sandbox: metadata}} =<br>        assign_new(socket, :phoenix_ecto_sandbox, fn -&gt;<br>          if connected?(socket), do: get_connect_info(socket, :user_agent)<br>        end)<br><br>      Phoenix.Ecto.SQL.Sandbox.allow(metadata, Ecto.Adapters.SQL.Sandbox)<br>    end<br>  end<br>end</pre><p>You’ll then need to update the router to use this on_mount hook for each of your LiveView sessions with the live_session helper.</p><pre># lib/my_app_web/router.ex<br>defmodule MyAppWeb.Router do<br>  ...<br>  live_session :default, on_mount: TestingLiveViewWallabyWeb.Hooks.AllowEctoSandbox do<br>    ...<br>  end<br>end</pre><h4>Setup a FeatureCase</h4><p>This one is optional, but I’ve found it useful for developer ergonomics when you’re building with Wallaby. It sets up an ExUnit case similar to the generated ConnCase, but geared specifically for Wallaby.</p><pre># test/support/feature_case.ex<br>defmodule MyAppWeb.FeatureCase do<br>  @moduledoc &quot;&quot;&quot;<br>  This module defines the test case to be used by<br>  tests that require setting up a full browser.<br><br>  If the test case interacts with the database,<br>  we enable the SQL sandbox, so changes done to the database<br>  are reverted at the end of every test. If you are using<br>  PostgreSQL, you can even run database tests asynchronously<br>  by setting `use MyAppWeb.FeatureCase, async: true`, although<br>  this option is not recommended for other databases.<br>  &quot;&quot;&quot;<br><br>  use ExUnit.CaseTemplate<br><br>  using do<br>    quote do<br>      use Wallaby.Feature<br><br>      import MyAppWeb.FeatureCase<br>      import Wallaby.Query<br><br>      alias MyAppWeb.Router.Helpers, as: Routes<br><br>      @moduletag :e2e<br><br>      @endpoint MyAppWeb.Endpoint<br><br>      setup _ do<br>        on_exit(fn -&gt; Application.put_env(:wallaby, :js_logger, :stdio) end)<br>      end<br>    end<br>  end<br><br>  def enable_latency_sim(session, latency) do<br>    Application.put_env(:wallaby, :js_logger, nil)<br>    Wallaby.Browser.execute_script(session, &quot;liveSocket.enableLatencySim(#{latency})&quot;)<br>  end<br><br>  def disable_latency_sim(session) do<br>    Wallaby.Browser.execute_script(session, &quot;liveSocket.disableLatencySim()&quot;)<br>  end<br>end</pre><h4>Testing a simple form interaction</h4><p>You can see the <a href="https://github.com/britton-jb/testing_live_view_wallaby/blob/main/test/testing_live_view_wallaby_web/features/question_feature_test.exs">full example on GitHub</a> to enable this test to go green. But here is a snippet:</p><pre>describe &quot;live index when creating a question&quot; do<br>  feature &quot;users should be able to submit the form and create a question&quot;, %{session: session} do<br>    question_text = &quot;How do I test simple things with Wallaby?&quot;<br><br>    session<br>    |&gt; visit(&quot;/questions&quot;)<br>    |&gt; click(link(&quot;New Question&quot;))<br>    |&gt; fill_in(text_field(&quot;Text&quot;), with: question_text)<br>    |&gt; click(button(&quot;Save&quot;))<br>    |&gt; assert_has(css(&quot;.alert&quot;, text: &quot;Question created successfully&quot;))<br>    |&gt; assert_has(css(&quot;#questions &gt; tr &gt; td&quot;, text: question_text))<br>  end<br>end</pre><h4>Simulate Latency</h4><p>Finally, thanks to JavaScript helpers provided by LiveView, we can also simulate high levels of latency in the user’s network:</p><pre>describe &quot;simulating latency&quot; do<br>  feature &quot;should ensure the saving is shown&quot;, %{session: session} do<br>    html =<br>      session<br>      |&gt; visit(&quot;/questions&quot;)<br>      |&gt; click(link(&quot;New Question&quot;))<br>      |&gt; fill_in(text_field(&quot;Text&quot;), with: &quot;Latency isn&#39;t fun, but should be accounted for&quot;)<br>      |&gt; enable_latency_sim(2000)<br>      |&gt; click(button(&quot;Save&quot;))<br>      |&gt; find(css(&quot;#question-form &gt; div &gt; button&quot;))<br>      |&gt; Wallaby.Element.attr(&quot;innerHTML&quot;)<br><br>    assert html == &quot;Saving...&quot;<br>  end<br>end</pre><h3>Conclusion</h3><p>Now you should be able to get started testing your Phoenix application using Wallaby.</p><p>If you’d like to see the whole talk you can <a href="https://brittonbroderick.com/conference-talks/#automated-browser-testing-for-phoenix-liveview-using-wallabythe-big-elixir-2022">check it out here</a>.</p><p><em>Originally published at </em><a href="https://brittonbroderick.com/2022/03/20/starting-browser-testing-for-phoenix-liveview-with-wallaby/"><em>https://brittonbroderick.com</em></a><em> on March 20, 2022.</em></p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=27222e00d870" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Maintaining Momentum as a Software Engineer]]></title>
            <link>https://medium.com/@brit_broderick/maintaining-momentum-as-a-software-engineer-89404321baf?source=rss-269b453fdab6------2</link>
            <guid isPermaLink="false">https://medium.com/p/89404321baf</guid>
            <category><![CDATA[software-development]]></category>
            <category><![CDATA[programming]]></category>
            <category><![CDATA[software-engineering]]></category>
            <dc:creator><![CDATA[Britton Broderick]]></dc:creator>
            <pubDate>Sat, 19 Feb 2022 13:10:00 GMT</pubDate>
            <atom:updated>2022-04-02T00:24:44.327Z</atom:updated>
            <content:encoded><![CDATA[<p>I was chatting with a team member this week, who I’ll call Ash, about the loss of momentum while chasing a quick win.</p><p>They had spent the better part of a day planning out a week’s worth of work. But Ash wanted something more emotionally satisfying to show for the day than the completed specification.</p><p>They should have felt proud to deliver the specification. It gave the team a great point to start the implementation from. But, I understand not feeling productive as an engineer unless you ship code on a given day. It’s how a lot of software engineers fight feelings of inadequacy and imposter syndrome. How they measure their self worth, what they tie their identity to, and how they cope with a <a href="https://brittonbroderick.com/2021/02/28/the-three-essential-feedback-types-for-your-next-1-1/">lack of clear feedback</a>.</p><p>Ash picked up a task to try to score a quick win. The task turned out to be anything but quick. While on the surface the work looked like it should be simple enough, no one had taken the time to look through the code and document in the specification where this code was a dependency for outside systems.</p><p>The “quick win” they had picked up wasn’t urgent. It was a nice-to-have cleanup task for the codebase. It is appreciated, but any sort of negative impact would only be felt in the very distant future.</p><p>Ash wasn’t even excited about this task. Quality suffered, they didn’t try to flesh out more of the details before beginning the work, and forgot to do a thorough self review by the end.</p><p>All of this in the name of momentum.</p><h3>Strategies for maintaining momentum</h3><p>During our one on one, I talked with Ash about what happened. We all crave that feeling of forward motion. Acknowledging that, we walked through a few different strategies they could have used to keep momentum up for the most important priority in the organization.</p><p>Here’s a bit of what I shared with Ash:</p><p>Software engineering is a social activity. It’s about understanding a group’s problem well enough to encode the problem and the solution in a way that can be communicated through time to both the computer and other team members. It almost certainly includes you two months from now.</p><p>If you have an urgent task, but your motivation is waning, you may want to give pair programming a shot. Talking through potential solutions and then implementing one together can help you keep up momentum and spread the domain knowledge. As a bonus, you improve code quality, because the idea has now been socialized with at least one other member of the team. I get tremendous energy from solving problems with a tight knit group. You may too.</p><p>This wasn’t a time sensitive task. And you may not always be able to find others to pair with. If that’s the case, there was another potentially obvious solution staring them in the face. Although hidden in plain sight, the specification they had just crafted suggested 6 potential seams that could be committed and sent up individually. At least four of which were tasks easily completed within an hour or two.</p><p>Depending on your team and the tradeoffs of your software development process, it may be that the 6 commits may have been too fine grain. Or they may have been perfectly adequate.</p><p>The point being there were different opportunities available to get those quick wins and maintain momentum while continuing on the work most valuable for the organization, because they knew how to <a href="https://brittonbroderick.com/2021/04/03/breaking-down-a-piece-of-work/">break down a piece of work</a>. But just because you know how to break down a piece of work doesn’t mean you’ll always see clearly how to proceed to keep momentum going.</p><p>Finally, sometimes you’re just not going to be in a headspace where you can get going. In a case like that, take a break. In his book <em>When: The Scientific Secrets of Perfect Timing</em>, Dan Pink highlights some of the research showing how beneficial taking a break is for cognitive work, different kinds of breaks, and when to use them. In schools studies found that test scores of children increase as if they had spent three additional weeks in school by taking a break before a test in the afternoon.</p><p>So go for a walk. Grab a cup of coffee. Refill your water. Stretch. Take five, and come back to tackle the problem when you’re in a better headspace.</p><p>I’d love to hear about strategies you use to maintain forward momentum. Send me an email at brittonbroderick@gmail.com or a message on Twitter, <a href="https://twitter.com/brit_broderick">@brit_broderick</a></p><p><em>Originally published at </em><a href="https://brittonbroderick.com/2022/02/19/maintaining-momentum-as-a-software-engineer/"><em>https://brittonbroderick.com</em></a><em> on February 19, 2022.</em></p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=89404321baf" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Merge One PR Per Day]]></title>
            <link>https://medium.com/@brit_broderick/merge-one-pr-per-day-2d26420dce9a?source=rss-269b453fdab6------2</link>
            <guid isPermaLink="false">https://medium.com/p/2d26420dce9a</guid>
            <category><![CDATA[software-engineering]]></category>
            <category><![CDATA[software-development]]></category>
            <category><![CDATA[continuous-integration]]></category>
            <category><![CDATA[pull-request]]></category>
            <dc:creator><![CDATA[Britton Broderick]]></dc:creator>
            <pubDate>Sat, 15 Jan 2022 13:00:00 GMT</pubDate>
            <atom:updated>2022-01-19T05:01:34.053Z</atom:updated>
            <content:encoded><![CDATA[<p>When new software engineers join my team they see a goal for each team member:</p><blockquote><em>At least one PR per day merged into the mainline branch.</em></blockquote><p>This goal often creates fear that comes in two forms:</p><ol><li>If I don’t get one PR merged per day I will be fired.</li><li>I must ship an entire completed feature per day.</li></ol><p>I’m not expecting them to ship an entire feature on any given day. And I’m not looking to use this as a stick to beat folks with. But shipping one PR per day requires specific practices that are not obvious to all software engineers.</p><h3>Why bother?</h3><p>If you’re getting one PR merged into the mainline branch every day you’re secretly practicing continuous integration. This comes with a huge number of benefits.</p><p>The biggest is that you avoid what I call <strong>solo developer syndrome</strong>.</p><p>You’ve seen this one before. When Dave on the team goes heads down for weeks. His daily update is consistently “almost done with the thing”. When the time for code review comes, he drops 8,000 lines of deep, unnecessary abstractions, and incoherent class and variable names. The team has no idea what’s going on or where to even start to gather understanding. No one wants to be the one to review it, because who wants to attempt to review that much code? Even when it’s well written. At the same time, Dave insists this meets the business’s needs, and he was supposed to ship it two weeks ago. The worst part is about two weeks after he walks away from the work it becomes completely incomprehensible, even to him. The team has just created a haunted graveyard. No one will touch it, because spooky ghosts lurk there, waiting to break whatever you’re trying to tweak.</p><p>By ensuring your code is integrated, and subject to review from your team frequently, you make it much more difficult to get into this state. In the event that you do push unmaintainable code, the amount you’ve pushed is smaller, so you have less to clarify and unwind before continuing onward. Long term you get more maintainable code, and a better engineer and team experience.</p><p>The long and short of it means that you get faster, more frequent feedback. With a proper system in place you can use this to grow as an individual faster.</p><p>Organizations that practice continuous integration are shown to have better business outcomes based on the <a href="https://services.google.com/fh/files/misc/state-of-devops-2019.pdf">DORA research</a>. These include things like better profitability, productivity, and market share compared to competitors, as well as lower levels of burnout, and higher levels of employee job satisfaction.</p><p>The most minor benefit is avoiding merge conflicts and allowing other folks on the team to take advantage of the changes that you’re making sooner.</p><h3>Steps for individuals</h3><p>If you’re not hitting one PR per day, here are a few practices from my experience that can help you to consistently merge one per day. Every day. This way you can get more reps in faster, and get ahead in your career.</p><p>If you’re like many software developers I’ve worked with, you’re probably not used to sitting and thinking through an implementation before banging out the code.</p><p>I know I still want to sit down and start coding, because it <strong>feels</strong> better. It feels like you’re making progress, even if you’re ultimately painting yourself into a corner.</p><p>But stop. Take a breath. Put away the code. Think about how this problem can be solved.</p><p>I’ve saved myself weeks of work by sitting and thinking through a problem, realizing that if we asked users for one readily available additional piece of information we wouldn’t need an entire complicated and error prone process to programmatically guess it.</p><p>You may be used to writing the entire feature on a branch before you merge it in. This is going to stop you from being able to merge one PR per day, and stop you from learning and iterating faster.</p><p>Part of stopping to think through the problem, allows you to <a href="https://brittonbroderick.com/2021/04/03/breaking-down-a-piece-of-work/">break down a piece of work</a> in a way that you can submit one or more PRs per day. You can find likely seams in your code that are good breakpoints, that can be sent up without breaking production.</p><p>Breaking down your work means you’ll also need to learn how to write more clearly about what the larger issue is, and how this small PR fits into the larger picture.</p><p>Finally, you need to write tests. The tests ensure that you maintain momentum, and don’t have to spend each day verifying that the code you’ve added or modified doesn’t break existing functionality.</p><p>If you’ve clearly broken down the work ahead, you can write the tests first as well, and they form a checklist of what you need to implement in order to call a PR, or a larger feature, complete.</p><h3>One PR per day is a systems goal</h3><p>But if you understand how to break work into smaller chunks, then it’s time to examine systemic issues. These are things you’re likely going to have to discuss with your manager and/or product manager, but a great place to start is with the following list:</p><ol><li>Does the team understand the problem space?</li><li>What about the possible solutions?</li><li>Do you have access to user experience and design input?</li><li>Is the team available to review your code?</li><li>Do they have the necessary context to review it?</li></ol><p>Do you have time to actually write one PR each day? Or do you spend most days in back to back meetings with two 30 minute blocks to write code? (And one of those is lunch.) It’s worth thinking about your day in terms of <a href="https://fs.blog/maker-vs-manager/">maker vs manager schedules</a>, and that you need uninterrupted time to craft your solutions. Unfortunately you will need to talk to your manager to resolve this one. If you just stop showing up to half the meetings on your calendar, you’re going to have a bad time.</p><p>If your organization isn’t used to conducting code reviews, or doesn’t require them, you’re going to need to actively seek reviewers for your code. Even if they’re mandatory, everyone will have a better time if you actively seek out the individuals best suited to review your code, and ask for feedback that they are best suited to give. Find folks that have experience or context in the areas that you’re extending or modifying to ensure that your mental model matches theirs. Find folks that are experts in the language or framework that you’re using, and ask them for pointers there.</p><p>You’re also going to want to ensure you’re returning the favor. Review others’ code when it comes in, and ensure that everyone has a good experience with it. If you piss everyone off,you’re going to make it much harder on yourself to get reviews.</p><p>All of these are things that need to be addressed to ensure you can ship one PR per day. You’re likely going to have limits on how much you can affect them, but addressing each of them to the best of your ability is critical.</p><p>So go forth and merge one PR per day, knowing that this is a goal designed to help you, not to get you fired.</p><p><em>Originally published at </em><a href="https://brittonbroderick.com/2022/01/15/merge-one-pr-per-day/"><em>https://brittonbroderick.com</em></a><em> on January 15, 2022.</em></p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=2d26420dce9a" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Deploy on Friday at 4:30 Until It Stops Hurting]]></title>
            <link>https://medium.com/@brit_broderick/deploy-on-friday-at-4-30-until-it-stops-hurting-3dfabb0edc3a?source=rss-269b453fdab6------2</link>
            <guid isPermaLink="false">https://medium.com/p/3dfabb0edc3a</guid>
            <category><![CDATA[software-development]]></category>
            <category><![CDATA[deployment]]></category>
            <category><![CDATA[software-engineering]]></category>
            <category><![CDATA[devops]]></category>
            <dc:creator><![CDATA[Britton Broderick]]></dc:creator>
            <pubDate>Mon, 29 Nov 2021 03:33:07 GMT</pubDate>
            <atom:updated>2021-12-20T04:27:53.750Z</atom:updated>
            <content:encoded><![CDATA[<p>“Everyone knows, don’t deploy on Friday.”</p><p>This isn’t rocket science, but I still hear way too many teams say that you shouldn’t deploy at 4:30pm on a Friday.</p><p>Or before a long weekend. Or any number of other occasions.</p><p>If this is a statement that your team is regularly making you need to start deploying exclusively at 4:30 PM every day, but especially on Friday, until it no longer scares you, and no longer hurts. Change your process until literally everyone on the team is comfortable deploying anytime.</p><p>As an individual member of the team you may look at this and say:</p><blockquote><em>I’m paid to ship new features, not fix the deployment pipeline.</em></blockquote><p>You’ll be able to ship features faster today, and in the future, if you feel confidence in your pipe.</p><p>If you’re not confident in the deploy process, automate the process.</p><p>If your deploy process takes too long, make the necessary changes to ensure it can be deployed and validated inside 10 minutes.</p><p>If you’re not confident in your changes not breaking things, beef up the test suite, make the change smaller, and use feature flags.</p><p>If you’re not sure if things are going wrong and you just don’t know it, improve error monitoring, observability, and logging, etc.</p><p>If it’s your PR and it’s got an approval, but you’re not sure, don’t merge it. Better yet, ask why you put it up in a state where it could potentially be approved and merged without you feeling comfortable with it.</p><p>If you’ve done all of the above and still aren’t feeling confident, but you can’t figure out how to further de-risk it, don’t approve it during code review, and don’t merge it if approved. Ask your team for ideas.</p><p>Just keep doing it. Eventually you will be in a place where you do things differently enough that you can do this confidently. So you don’t have to stay late, and you don’t have to stress about if this set of changes is going to break things.</p><p>The fear of deploying late on Friday isn’t about Friday. It’s about all of the other things your software development process is lacking. Make the changes so that your team feels confident about deploying the changes they’ve made.</p><p><em>Originally published at </em><a href="https://brittonbroderick.com/2021/11/29/deploy-on-friday-at-4-30-until-it-stops-hurting/"><em>https://brittonbroderick.com</em></a><em> on November 29, 2021.</em></p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=3dfabb0edc3a" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Doing it all is not your job, Team Leader!]]></title>
            <link>https://medium.com/@brit_broderick/doing-it-all-is-not-your-job-team-leader-802b6a01f080?source=rss-269b453fdab6------2</link>
            <guid isPermaLink="false">https://medium.com/p/802b6a01f080</guid>
            <category><![CDATA[software-development]]></category>
            <category><![CDATA[engineering-mangement]]></category>
            <dc:creator><![CDATA[Britton Broderick]]></dc:creator>
            <pubDate>Mon, 22 Nov 2021 03:16:00 GMT</pubDate>
            <atom:updated>2021-11-25T18:09:20.151Z</atom:updated>
            <content:encoded><![CDATA[<p>When discussing the opportunity to step into leadership roles with individuals on and off my team, folks have expressed apprehension, thinking they’d have to wave goodbye to writing code as an individual, and that the age of endless specification of requirements and code review would begin.</p><p><strong>This is not your job.</strong></p><h3>What do you mean?</h3><p>You may be saying, what do you mean this isn’t my job? I’ve been designated team lead? There’s a non-zero chance I’m also the most senior member of my team?</p><p>True, you were designated the team lead, and as such it’s your job to ensure that the team delivers what it needs to for the organization, and to develop the capabilities of the members of the team so that they can continue to meet the needs of the organization.</p><p>Rather than exploring what your job is, here we’re just going to break down why this isn’t your job.</p><h3>Why doing it all isn’t your job</h3><p>Explicitly, it’s not your job as the team lead to do all of the technical specification work, specification review, and code review. In fact, you’re actively hurting the team if you do this. To become Senior, members of the team also need to be given the opportunity to do each of these things and get better at it. If you’re always the first one to put up a code review, the first one to review a specification, or the only one to write a specification, you’re robbing them of the opportunity to grow and improve. Put more bluntly. If you do all of this, they will never be given the opportunity to grow into seniors on the job. This means that your workload will never get lighter, because you’re never allowing your team to become more capable.</p><p>This is likely going to feel a bit painful at first, because other members of the team probably aren’t as skilled at building out a technical specification, or reviewing code. Some things you would have caught may even slip through. This is part of the process. Make another pass through after they do if needed to coach them through what they missed, and how they can do better next time.</p><h3>How to avoid doing it all</h3><p>Understanding why this isn’t your job, and why the following behavior is in fact bad, here are a few strategies to make the transition easier:</p><ul><li>Set limits on the number of code reviews you do, specs you write, and review per day or week. If necessary, explicitly tell the team that you’ve hit your limit for the period, and you need them to step up to the plate.</li><li>Consciously ensure that you’re not the first one to review some pieces of code, or specifications.</li><li>Assign work that needs to be specified to other members of the team. Review it.</li><li>Assign bugs to other members of the team to diagnose. Walk them through why you triaged it with the priority that you did.</li><li>If you’re not comfortable with the level the team executes these tasks, take the time to pair with them on it. Or if you’re unable to pair with them when they’re working on it, review it. Even if it ends up being a bit of a meta-review.</li></ul><p>Doing this will also ensure you continue to have time to write code as an individual contributor. By taking these steps the age of writing code doesn’t have to end yet.</p><p>Agree? Disagree, thinking I’m dangerously wrong? Either way I want to hear about it. <a href="https://twitter.com/brit_broderick">@brit_broderick</a> or <a href="/service/mailto:brittonbroderick@gmail.com">brittonbroderick@gmail.com</a>.</p><p><em>Originally published at </em><a href="https://brittonbroderick.com/2021/11/22/doing-it-all-is-not-your-job-team-leader/"><em>https://brittonbroderick.com</em></a><em> on November 22, 2021.</em></p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=802b6a01f080" width="1" height="1" alt="">]]></content:encoded>
        </item>
    </channel>
</rss>