Forem: Tyler Hawkins

AI Build Traps: Usage, Output, and Outcomes (How perverse incentives around token usage create cobra farms)

Tyler Hawkins — Thu, 26 Mar 2026 04:27:04 +0000

Organizations have long struggled with answering the question: "How do we measure developer productivity?"

In the past, some organizations have taken to measuring lines of code produced per engineer. Others have measured the number of tickets closed. Others measure the number of pull requests (PRs) merged.

And now in the age of AI, we've started measuring token usage.

Proxy metrics

The problem with all of these metrics is that they're not actually measurements of developer productivity — they're proxy metrics. And with any proxy metric, once you start measuring something, that metric becomes the goal. This is especially true if that metric has financial incentives or performance ratings tied to it.

Measuring lines of code? Great, engineers will start writing overly verbose PRs in order to write more lines. Goodbye concise functions and reusable code.

Measuring number of tickets closed? Great, engineers will start creating tickets for everything, and they'll break tasks down into the smallest tickets possible. Now we're more focused on Jira and paperwork than actual work and value provided.

Measuring number of pull requests merged? Great, engineers will focus on creating as many PRs as possible, with the smallest changes they can think of, or with the most trivial updates.

Measuring token usage? Great, engineers will use their AI assistants for everything to use more tokens, regardless of whether or not the output is useful or makes the engineer more efficient.

All of these examples are what are called perverse incentives — incentives that create unintended and oftentimes counterproductive behaviors that work contrary to the desired goal.

Cobra farms

One of the most famous examples of perverse incentives is the story of the cobra problem in India. According to the story, Delhi was overrun with cobras, venomous snakes. The government wanted to get rid of the cobras, so they offered a reward for every dead cobra that someone brought in. Seems reasonable, right? The more dead cobras there are, the less live ones there are.

But can you see the perverse incentive? People were rewarded for dead cobras. How do you get more dead cobras, besides finding more? You raise more cobras yourself and then kill them. So people began breeding cobras themselves so that they could turn them in for the reward.

And then, once the government realized what was happening, the government ended the incentive program. Cobra breeders no longer had any reason to breed more cobras, so they released the rest of what they had into the wild, resulting in even more cobras in the city.

The well-intentioned goal of rewarding people for dead cobras actually resulted in more cobras being present, not fewer.

(For the record, whether or not this story is true or if parts are exaggerated is not entirely certain. But it's a very fun example for a teaching moment!)

AI usage

So now let's get back to AI usage and tokens. Organizations are under more pressure than ever to prove that they're thriving in this brave new world of AI. Engineers are under that same pressure, expected to do more and accomplish more work. That's the promise we've all been sold, that AI will make us more productive.

But how do we measure this increased productivity? Well, we're back to the same problem organizations have always had, even before AI. It's hard to measure productivity, so we come up with a proxy metric, and that proxy metric is now token usage.

Surely if an engineer is using more tokens, that means they're using AI more, so they're more productive in their job and helping the business even more.… Right?

Usage, output, and outcomes

That's where the build trap happens. Organizations go astray when they focus more on output (e.g. pull requests merged, features shipped, projects completed) than on outcomes (e.g. value delivered to customers, user behavior change, pain points resolved).

Maybe token usage is increasing, but does that correspond to an increase in pull requests and actual work done? If token usage increases but the output of the individual stays the same, then we haven't actually accomplished anything. We're just celebrating using more tokens (spending more money) but with no actual increased productivity.

And taking that a step further, let's say that we do see an increase in pull requests merged, which presumably is a good thing. But does that increase in output lead to a corresponding increased benefit in outcomes? Is the product better because of the increased output?

In other words, does the increased code result in a tangible increase in the value that the company provides to its users?

That question is far more difficult to answer, but far more important.

Mediocre organizations measure usage and output and then stop there. Great organizations measure outcomes.

Test-Driven Development for Building User Interfaces

Tyler Hawkins — Mon, 09 Feb 2026 16:00:00 +0000

Test-driven development, or TDD, is a programming paradigm in which you write your tests first and your source code second. TDD is perfect when you’re writing code that has clear inputs and outputs, like pure functions or API endpoints.

But what about when building user interfaces? Can TDD be done for UI development?

You’re about to find out!

In this article we’ll explore a few questions while building a demo UI:

Can we use TDD to build UIs?
If so, how do we do it?
And finally, should we use TDD to build UIs?

Note: This article was inspired by a conference talk I gave in January 2021 at THAT Conference Texas. This article was also written at that time. It’s been five years now, so some practices have changed. (Do most frontend engineers even know what Enzyme is anymore, or did they start out with React Testing Library?) However, I still think this is an interesting thought experiment and worth discussing, hence why I’m finally publishing this in its original form.

Background Motivation

When discussing test-driven development with frontend developers, the conversation usually goes something like this:

“Yeah TDD is great for simple functions or backend work, but it just doesn’t make sense for frontend work. When I’m building my UI, I don’t know what code I’ll end up writing. I have no idea if I’ll end up using a div or a span or a p element here. TDD for UIs just isn’t feasible.”

However, I’d like to argue that using TDD to build UIs isn’t as hard as we may think.

Ideal Conditions for TDD

Ideally, we’d use TDD to write our code when the following two conditions are true:

We have clear project requirements
We have clear inputs and outputs

If those two requirements are not met, it’s difficult or nearly impossible to use TDD. So let’s examine those two requirements in the context of frontend development.

Clear Project Requirements

When you’re developing a new feature, you’re typically given mockups by a UX designer. These mockups show you how the feature should look and how the feature should behave. For example, “when the user clicks this button, a dialog modal appears on the screen.”

Good mockups will clarify various details such as how inputs will look when in a hover or focus state, how empty states will look when content is missing, and how the page layout will change for desktop, laptop, and mobile screen sizes.

As you may have already guessed, the mockups provide the project requirements! We know exactly how our UI should look and behave. If there’s anything unclear in the mockups, engineers should ask clarifying questions with their UX designer or product manager so that the requirements are absolutely clear.

Clear Inputs and Outputs

Now, what about clear inputs and outputs?

Most frontend engineers these days use a UI library or framework like React or Angular. A UI library like React allows you to build reusable components to create small building blocks of functionality that you can piece together to make an app.

Now, what is a component? Well, in React, it’s a function! Components are simply functions of props and state that return a piece of UI. So we have clear inputs and outputs!

Given the same props and state, a component will always render the same thing. Components are deterministic, and as long as they don’t kick off side effects like making an API request, they are pure functions.

Practical Considerations

So, in theory, using TDD to build UIs should work. Both of our ideal conditions are met.

But what about the unknowns? As mentioned above, we still might not know a few things:

Component props and state we’ll use
Names we’ll give our methods and functions
HTML elements we’ll use

But we do know how the UI should look and behave. I’d argue that the unknown implementation details actually don’t matter.

This outdated way of thinking about testing implementation details largely stems from Airbnb’s testing library Enzyme. Enzyme allowed you to dive into the internals of your React components, trigger class component methods, and manually update a component’s props and state.

However, none of those are things that a user can do. A user can only interact with your app through the interface that you provide. For example, the user might click on a button or fill out a form field.

React Testing Library’s core philosophy is that we should write our tests in such a way that we simulate user behavior. By testing what the user can actually do, our tests focus less on implementation details and more on the actual user interface, which leads to less brittle tests and a more reliable test suite.

The key here is that React Testing Library actually facilitates using TDD to build UIs by taking the focus away from the implementation details.

Remember: the unknown implementation details don’t matter. What matters is how the UI looks and behaves.

Demo Time: Building a Request Form

Alright, enough theory. I hope by now I’ve presented a clear case that it should be possible to build a user interface using test-driven development.

But how does this actually look in practice?

To illustrate these concepts in a concrete way, we’ll build a simple UI in React using TDD. Let’s imagine that we need to create a request form that allows visitors on our site to request a demo of our new product. Here are the mockups that we’ll pretend we’ve been given:

Mockup 1: Initial UI

As you can see, the form displays three inputs for a user’s first name, last name, and email address. There is a submit button at the bottom of the form.

If a user tries to submit the form without filling out all three fields, an error message will be displayed next to each invalid input:

Mockup 2: Error messages appear on form submission if fields are left blank

Finally, once the user properly fills out and submits the form, a confirmation screen is shown:

Mockup 3: Confirmation text is shown after the form is successfully submitted

Getting Started

We’ll begin by bootstrapping a brand new app using create-react-app. Once my app was generated, I deleted and re-arranged some of the initial code to get to a good starting point. As you can see, we’ll start with a bare bones app that only returns a header element.

App starting point

You can follow along here on the demo/start branch of my GitHub repo.

Test #1: Sanity Check

Let’s start by creating a RequestForm.test.js file. We’ll write our first test that asserts that our RequestForm component renders without crashing.

import React from "react";
import { render, screen } from "@testing-library/react";
import { RequestForm } from "./RequestForm";

describe("RequestForm", () => {
  it("renders without crashing", () => {
    expect(() => render(<RequestForm />)).not.toThrow();
  });
});

As you might have guessed, this test fails because we don’t actually have a RequestForm.js file or a RequestForm component created yet. And that’s ok, because this is how TDD works — we write our tests first and then our source code.

Our first test fails because the RequestForm.js file does not exist

Let’s now write some code to get this test to pass. We’ll create a RequestForm.js file that exports a RequestForm component. The RequestForm component will simply render a form HTML element.

import React from "react";

export const RequestForm = () => <form />;

Now when we run our tests, they pass!

Our first test passes now

Test #2: First Name Input

Let’s move on to our second test. Let’s assert that our RequestForm component renders an input for the user to enter their first name.

it("renders a first name text input", () => {
  render(<RequestForm />);
  expect(screen.getByLabelText("First Name")).toBeInTheDocument();
});

And now we’ll run our tests, and… this new test fails, as expected, because our RequestForm component doesn’t render any inputs yet. It’s still just an empty form.

Our second test fails because the RequestForm component does not yet render an input for the first name

We can update our RequestForm component to render an input element and an accompanying label element that allows the user to enter their first name.

import React from "react";

export const RequestForm = () => (
  <form>
    <label htmlFor="firstName">First Name</label>
    <input id="firstName" />
  </form>
);

Now when we run our tests, they all pass!

Our second test passes now that the form renders an input for the first name

Here’s what our current app’s UI looks like:

App renders a First Name input

It’s not a very pretty app, but we’ll come back to style it up in a few minutes.

Test #3: Last Name Input

Now let’s write another test that looks just like our test for the “first name” input, but this time let’s assert that there is a “last name” input on the page.

it("renders a last name text input", () => {
  render(<RequestForm />);
  expect(screen.getByLabelText("Last Name")).toBeInTheDocument();
});

We’ll run our tests, and, you guessed it, this new test fails. No surprises there.

Our third test fails because the RequestForm component does not yet render an input for the last name

So, just like before, let’s update our RequestForm component to render another input element and another label element, but this time for the user to enter their last name.

import React from "react";

export const RequestForm = () => (
  <form>
    <label htmlFor="firstName">First Name</label>
    <input id="firstName" />
    <label htmlFor="lastName">Last Name</label>
    <input id="lastName" />
  </form>
);

We’ll run our tests again, and now they all pass. Nice!

Our third test passes now that the form renders an input for the last name

Here’s what our app’s UI looks like now:

App renders a First Name input and a Last Name input

Not very pretty, is it? With all of our tests currently passing, this seems like a great time for a small refactor.

Refactor #1: Rendering Labels and Inputs on Individual Rows

Before we jump into our refactor, I’d like to call out a key principle here. When doing test-driven development, you follow what’s called a “red, green, refactor” cycle.

You start by writing a failing test, so you’re in the red. You then write the source code to make the test pass, which puts you in the green. Once you’re in the green, you can refactor your code all you want. At the end of your refactor, your existing tests must still pass, keeping you in the green.

Red, green, refactor cycle by Nat Pryce

When it comes to UI development, we can consider style changes a refactor.

With that context provided, let’s now style up our app a little. It’d be nice to have our label-input pairs on separate rows. We could also add some breathing room between the label and the input text box.

To do this, we’ll add a div element with a formGroup class wrapped around our label-input pairs. We’ll also create a RequestForm.css file to include some CSS.

Here’s the RequestForm.js file:

import React from "react";
import "./RequestForm.css";

export const RequestForm = () => (
  <form>
    <div className="formGroup">
      <label htmlFor="firstName">First Name</label>
      <input id="firstName" />
    </div>
    <div className="formGroup">
      <label htmlFor="lastName">Last Name</label>
      <input id="lastName" />
    </div>
  </form>
);

And here’s the accompanying RequestForm.css file that we import:

.formGroup {
  margin-bottom: 1rem;
}

.formGroup label {
  padding-right: 1rem;
}

With those changes in place, our UI now looks like this:

App with the label-input pairs on their own rows

Much better! There is still more we can do style our form to make it match our mockups, but we’ll call it good for now.

Now, remember what we had learned about the red, green, refactor cycle? Refactors should happen while we’re in the green, and after we’re done with our refactor we should still be in the green. Let’s run our tests to see how things are looking:

Our tests are still passing after our style refactor

Sweet! Our tests are still passing after our style refactor.

Test #4: Email Address Input

Let’s move on to our next test. We have tests for the “first name” input and the “last name” input, so let’s now write one more test for the “email address” input.

it("renders an email address text input", () => {
  render(<RequestForm />);
  expect(screen.getByLabelText("Email")).toBeInTheDocument();
});

This fails, as expected.

Our fourth test fails because the RequestForm component does not yet render an input for the email address

Just like we did with the “first name” and “last name” inputs, we can add another input element and another label element so that the user can enter their email address.

import React from "react";
import "./RequestForm.css";

export const RequestForm = () => (
  <form>
    <div className="formGroup">
      <label htmlFor="firstName">First Name</label>
      <input id="firstName" />
    </div>
    <div className="formGroup">
      <label htmlFor="lastName">Last Name</label>
      <input id="lastName" />
    </div>
    <div className="formGroup">
      <label htmlFor="email">Email</label>
      <input type="email" id="email" />
    </div>
  </form>
);

With that, our tests will all pass again.

Our fourth test passes now that the form renders an input for the email address

Let’s check out the UI as it stands now:

App renders inputs for first name, last name, and email address

Our inputs are still in rows, but the alignment on the “email” field could look better. It’d appear more uniform if all of the input boxes lined up nicely as if they were in a column. Let’s address this with a second refactor.

Refactor #2: Lining Up the Columns

To better align our inputs, we can add a couple simple CSS rules to our existing styles. We’ll add a width and a display property to our label elements so that our full CSS file looks like this:

.formGroup {
  margin-bottom: 1rem;
}

.formGroup label {
  padding-right: 1rem;
  display: inline-block;
  width: 6rem;
}

Now our UI looks just a little nicer:

App with all form inputs aligned

And, the important part during any refactor: the tests all still pass.

Our tests are still passing after our second style refactor

Test #5: Submit Button

Let’s move on to our next test. This test will assert that a submit button with the text “Request Demo” appears in the form.

As I’m sure you can figure out by now, the test fails of course because we haven’t implemented the submit button yet.

Our fifth test fails because the RequestForm component does not yet render a submit button

We can easily add the submit button to our RequestForm component like so:

import React from "react";
import "./RequestForm.css";

export const RequestForm = () => (
  <form>
    <div className="formGroup">
      <label htmlFor="firstName">First Name</label>
      <input id="firstName" />
    </div>
    <div className="formGroup">
      <label htmlFor="lastName">Last Name</label>
      <input id="lastName" />
    </div>
    <div className="formGroup">
      <label htmlFor="email">Email</label>
      <input type="email" id="email" />
    </div>
    <button type="submit">Request Demo</button>
  </form>
);

Now the tests pass again, putting us back in the green.

Our fifth test passes now that the form renders a submit button

And the app’s UI now shows the “Request Demo” button too:

App renders the three inputs and the submit button

Refactor #3: Centering and Styling the Form

If we look back at our design mockups, we’ll see that our form should be centered on the page and should have a thin black border around it. Since all our tests are passing and the form contents are complete, now seems like a good time to do a third refactor with some more style updates.

In our RequestForm.js file, we’ll add a requestForm class to our form element like so:

<form className="requestForm">{/* the rest of the existing code here */}</form>

Then we’ll add some styles to that class in our RequestForm.css file:

.requestForm {
  border: solid 0.0125rem #000;
  border-radius: 0.25rem;
  padding: 1rem;
  display: inline-block;
  text-align: left;
}

And finally, in our main index.css file that we haven’t touched at all during this exercise, we’ll add text-align: center on the body element. The resulting index.css file looks like this:

html {
  margin: 0;
  padding: 0;
  font-size: 16px;
}

body {
  margin: 0;
  padding: 2rem;
  text-align: center;
  font-size: 100%;
  font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", "Roboto",
    "Oxygen", "Ubuntu", "Cantarell", "Fira Sans", "Droid Sans",
    "Helvetica Neue", sans-serif;
  -webkit-font-smoothing: antialiased;
  -moz-osx-font-smoothing: grayscale;
}

And with that, our form is nice and centered on the page with a simple border:

App renders a nice form centered on the page, matching the design mockups

And, as always, we made sure that our refactors did not break any of our existing tests:

Our tests are still passing after our third style refactor

Test #6: Error Message for Invalid Inputs

Now that we have a nicely styled form on our page, it’s time to start focusing on the behavior of the form. As we can see in our second design mockup, we need error messages to display when the form is submitted if any of the input fields are not filled out.

Let’s first write a test to assert that error messages are shown when the form is submitted with invalid inputs.

At the top of our RequestForm.test.js file we’ll need to import a new method from React Testing Library called fireEvent so that we can click on the submit button as part of our test.

import { render, screen, fireEvent } from "@testing-library/react";

Then we can write our new test:

it("renders an error message for each of the inputs if none of them are filled out and the user submits the form", () => {
  render(<RequestForm />);
  fireEvent.click(screen.getByText("Request Demo"));

  expect(screen.getByText("First Name field is required")).toBeInTheDocument();

  expect(screen.getByText("Last Name field is required")).toBeInTheDocument();

  expect(screen.getByText("Email field is required")).toBeInTheDocument();
});

As you can see, we render the form, click the submit button, and then assert that all three input fields have an accompanying error message shown.

When we run our tests, this new test of course fails.

Our sixth test fails because the RequestForm component does not yet handle the form submission or show error messages

To implement this functionality, we’ll make some fairly significant changes to our RequestForm component. First, we’ll change our uncontrolled inputs to be controlled inputs. In other words, we’ll let React manage each input’s value attribute and onChange handler. Second, we’ll add some error messages that are conditionally rendered when the user submits the form.

These changes result in the RequestForm.js file now looking like this:

import React, { useState } from "react";
import "./RequestForm.css";

export const RequestForm = () => {
  const [firstName, setFirstName] = useState("");
  const [lastName, setLastName] = useState("");
  const [email, setEmail] = useState("");

  const handleChange = (e) => {
    const { name, value } = e.target;

    switch (name) {
      case "firstName":
        setFirstName(value);
        break;
      case "lastName":
        setLastName(value);
        break;
      case "email":
        setEmail(value);
        break;
      default:
        return;
    }
  };

  const [firstNameError, setFirstNameError] = useState("");
  const [lastNameError, setLastNameError] = useState("");
  const [emailError, setEmailError] = useState("");

  const handleSubmit = (e) => {
    e.preventDefault();

    setFirstNameError(firstName ? "" : "First Name field is required");
    setLastNameError(lastName ? "" : "Last Name field is required");
    setEmailError(email ? "" : "Email field is required");
  };

  return (
    <form className="requestForm" onSubmit={handleSubmit}>
      <div className="formGroup">
        <label htmlFor="firstName">First Name</label>
        <input
          name="firstName"
          id="firstName"
          data-testid="firstName"
          value={firstName}
          onChange={handleChange}
        />
      </div>
      {firstNameError && <p>{firstNameError}</p>}

      <div className="formGroup">
        <label htmlFor="lastName">Last Name</label>
        <input
          name="lastName"
          id="lastName"
          data-testid="lastName"
          value={lastName}
          onChange={handleChange}
        />
      </div>
      {lastNameError && <p>{lastNameError}</p>}

      <div className="formGroup">
        <label htmlFor="email">Email</label>
        <input
          type="email"
          name="email"
          id="email"
          data-testid="email"
          value={email}
          onChange={handleChange}
        />
      </div>
      {emailError && <p>{emailError}</p>}

      <button type="submit">Request Demo</button>
    </form>
  );
};

That was a lot to take in! Feel free to pause and take a minute to look through the code above if you need to.

Let’s look at our tests now that we’ve implemented the error message functionality:

Our sixth test passes now that the form handles submission and validation

They all pass! Beautiful! And how about the app’s UI? Here’s what the app looks like now after the user clicks the submit button without filling out any of the form fields:

App displays unformatted error messages if the form is submitted with all empty fields

As you can see, while the form is functional, it could use some style updates. That means it’s time for another refactor!

Refactor #4: Styling the Error Messages

Looking back at our design mockups, we see that the error messages should be in red. The height of the form shouldn’t change when an error message is displayed either.

We can achieve this by adding a new class called errorMessage to our error message content. We will also conditionally add an error class to our formGroup element when the input is in an invalid state.

The resulting RequestForm.js file looks like this:

import React, { useState } from "react";
import "./RequestForm.css";

export const RequestForm = () => {
  const [firstName, setFirstName] = useState("");
  const [lastName, setLastName] = useState("");
  const [email, setEmail] = useState("");

  const handleChange = (e) => {
    const { name, value } = e.target;
    switch (name) {
      case "firstName":
        setFirstName(value);
        break;
      case "lastName":
        setLastName(value);
        break;
      case "email":
        setEmail(value);
        break;
      default:
        return;
    }
  };

  const [firstNameError, setFirstNameError] = useState("");
  const [lastNameError, setLastNameError] = useState("");
  const [emailError, setEmailError] = useState("");

  const handleSubmit = (e) => {
    e.preventDefault();
    setFirstNameError(firstName ? "" : "First Name field is required");
    setLastNameError(lastName ? "" : "Last Name field is required");
    setEmailError(email ? "" : "Email field is required");
  };

  return (
    <form className="requestForm" onSubmit={handleSubmit}>
      <div className={`formGroup${firstNameError ? " error" : ""}`}>
        <label htmlFor="firstName">First Name</label>
        <input
          name="firstName"
          id="firstName"
          data-testid="firstName"
          value={firstName}
          onChange={handleChange}
        />
      </div>
      {firstNameError && <p className="errorMessage">{firstNameError}</p>}

      <div className={`formGroup${lastNameError ? " error" : ""}`}>
        <label htmlFor="lastName">Last Name</label>
        <input
          name="lastName"
          id="lastName"
          data-testid="lastName"
          value={lastName}
          onChange={handleChange}
        />
      </div>
      {lastNameError && <p className="errorMessage">{lastNameError}</p>}

      <div className={`formGroup${emailError ? " error" : ""}`}>
        <label htmlFor="email">Email</label>
        <input
          type="email"
          name="email"
          id="email"
          data-testid="email"
          value={email}
          onChange={handleChange}
        />
      </div>
      {emailError && <p className="errorMessage">{emailError}</p>}

      <button type="submit">Request Demo</button>
    </form>
  );
};

And the resulting RequestForm.css file looks like this:

.formGroup {
  margin-bottom: 2rem;
}

.formGroup.error {
  margin-bottom: 0;
}

.formGroup label {
  padding-right: 1rem;
  display: inline-block;
  width: 6rem;
}
.requestForm {
  border: solid 0.0125rem #000;
  border-radius: 0.25rem;
  padding: 1rem;
  display: inline-block;
  text-align: left;
}

.errorMessage {
  color: red;
  margin-top: 0;
  line-height: 1;
}

Let’s check out our app’s UI after submitting an empty form again:

App displays error messages in red and keeps the form the same height

Much better! The error messages are shown in red, and the form maintains a consistent height regardless of whether or not error messages appear on the screen.

As always, we’ll check our tests as well to make sure we didn’t break anything:

Our tests are still passing after our fourth style refactor

Everything is still passing! Excellent. Another successful refactor.

Test #7: Confirmation Message on Successful Form Submission

With that, we’re ready for our seventh and final test. We now want to assert that the form can be successfully submitted and that a confirmation screen is shown to the user.

We’ll write the following test:

it("replaces the form with a confirmation message when submitted successfully", () => {
  render(<RequestForm />);
  fireEvent.change(screen.getByLabelText("First Name"), {
    target: { value: "Tyler" },
  });
  expect(screen.getByLabelText("First Name").value).toBe("Tyler");

  fireEvent.change(screen.getByLabelText("Last Name"), {
    target: { value: "Hawkins" },
  });
  expect(screen.getByLabelText("Last Name").value).toBe("Hawkins");

  fireEvent.change(screen.getByLabelText("Email"), {
    target: { value: "test@test.com" },
  });
  expect(screen.getByLabelText("Email").value).toBe("test@test.com");

  fireEvent.click(screen.getByText("Request Demo"));
  expect(
    screen.getByText("Thank you! We will be in touch with you shortly.")
  ).toBeInTheDocument();

  expect(screen.queryByLabelText("First Name")).not.toBeInTheDocument();
  expect(screen.queryByLabelText("Last Name")).not.toBeInTheDocument();
  expect(screen.queryByLabelText("Email")).not.toBeInTheDocument();
});

Walking through the test, we first render the form. We then fill out the form, one input at a time, and assert that the value of each input is what we would expect. Then we click the submit button to submit the form. We then assert that the confirmation message is shown on the screen and that the original form no longer appears.

When we run our tests, this test fails. (Shocker, right?)

Our seventh test fails because the RequestForm component does not yet handle the successful form submission

Now we can write our source code to implement the successful form submission functionality. We’ll add the confirmation text that is conditionally rendered when a new submitted piece of state is true. We’ll also break up our single onChange handler into separate onChange handlers just for fun.

The final RequestForm.js file looks like this:

import React, { useState } from "react";
import "./RequestForm.css";

export const RequestForm = () => {
  const [firstName, setFirstName] = useState("");
  const [lastName, setLastName] = useState("");
  const [email, setEmail] = useState("");

  const handleFirstNameChange = (e) => {
    setFirstName(e.target.value);
  };

  const handleLastNameChange = (e) => {
    setLastName(e.target.value);
  };

  const handleEmailChange = (e) => {
    setEmail(e.target.value);
  };

  const [firstNameError, setFirstNameError] = useState("");
  const [lastNameError, setLastNameError] = useState("");
  const [emailError, setEmailError] = useState("");

  const [submitted, setSubmitted] = useState(false);

  const handleSubmit = (e) => {
    e.preventDefault();

    setFirstNameError(firstName ? "" : "First Name field is required");
    setLastNameError(lastName ? "" : "Last Name field is required");
    setEmailError(email ? "" : "Email field is required");

    if (firstName && lastName && email) {
      setSubmitted(true);
    }
  };

  return submitted ? (
    <p>Thank you! We will be in touch with you shortly.</p>
  ) : (
    <form className="requestForm" onSubmit={handleSubmit}>
      <div className={`formGroup${firstNameError ? " error" : ""}`}>
        <label htmlFor="firstName">First Name</label>
        <input
          name="firstName"
          id="firstName"
          data-testid="firstName"
          value={firstName}
          onChange={handleFirstNameChange}
        />
      </div>
      {firstNameError && <p className="errorMessage">{firstNameError}</p>}

      <div className={`formGroup${lastNameError ? " error" : ""}`}>
        <label htmlFor="lastName">Last Name</label>
        <input
          name="lastName"
          id="lastName"
          data-testid="lastName"
          value={lastName}
          onChange={handleLastNameChange}
        />
      </div>
      {lastNameError && <p className="errorMessage">{lastNameError}</p>}

      <div className={`formGroup${emailError ? " error" : ""}`}>
        <label htmlFor="email">Email</label>
        <input
          type="email"
          name="email"
          id="email"
          data-testid="email"
          value={email}
          onChange={handleEmailChange}
        />
      </div>
      {emailError && <p className="errorMessage">{emailError}</p>}

      <button type="submit">Request Demo</button>
    </form>
  );
};

And with that, we now have seven passing tests!

Our seventh test passes now that the form handles successful submission and displaying a confirmation message

We can confirm the behavior manually in our app too by filling out the form fields:

Filling out the form

We’ll click the submit button and… voilà! A simple confirmation message appears on the screen.

App displays a confirmation screen after successful form submission

We did it!

Resulting Code Coverage

We’ve now finished building our “Request Demo” form. We’ve built out all the functionality requested by our product manager and UX designer, and the resulting UI matches the mockups perfectly.

But how did we do on our test coverage? Were the tests we wrote sufficient? We can generate the test coverage report by running yarn test:coverage. The output is below:

100% code coverage. Nice!

Amazing! 100% test coverage. This is one of the major benefits of TDD: all of your code, in theory, should be covered by tests because the only source code you write is code to make your tests pass. And because the tests are derived from product requirements, you can be sure that they are testing the right things.

Conclusion

So, what have we learned? In the beginning of this article, we were determined to answer three questions:

Can we use TDD to build UIs?
If so, how do we do it?
And finally, should we use TDD to build UIs?

So, can we use TDD when building UIs? Yes! We absolutely can!

And how do we do this? By following a process similar to what we’ve outlined by building our demo app. We follow the red, green, refactor cycle and implement style changes during the “refactor” phase.

Now, should we use TDD when building UIs? Maybe. Test-driven development isn’t everyone’s cup of tea. But I strongly believe that all frontend developers should at least try it. Give it a shot and see if it works for you. As we’ve demonstrated, using TDD to build UIs isn’t as difficult as you may think. In fact, you may even find that TDD speeds up your development process while ensuring that you test the right things.

Happy coding!

Four strategies for deciding how to decide (plus two more tips)

Tyler Hawkins — Thu, 22 Jan 2026 16:00:00 +0000

Decision making is hard. Decision making in large organizations is even harder.

Have you ever tried to lead a large change but struggled to get consensus from the group?

Or have you ever been in a meeting where you've debated an idea for what feels like the hundredth time but still haven't reached a decision?

Or have you ever been asked to provide input on a decision, only to be overruled, and then wondered why you were asked in the first place?

All of these frustrating scenarios are the result of one of two things:

Utilizing ineffective decision-making models, or
Failing to properly communicate the decision-making model being used.

Four decision-making models

So, how do we make decisions more effectively?

The book Crucial Conversations offers some excellent advice on decision-making models and outlines four possible strategies:

Command. Decisions are made without involving others.
Consult. Input is gathered from the group and then a subset decides.
Vote. An agreed-upon percentage swings the decision.
Consensus. Everyone comes to an agreement and then supports the final decision.

For large projects where everyone seems to have an opinion, the ideal model is usually Consult, where input is welcome, but someone needs to make the final call. To make this model work, people need to know that this is the decision-making model being used and know who the final decision maker is.

Where we get into trouble is if people think that this is a Vote or Consensus situation. In the instance of a big initiative that involves dozens of stakeholders, it's a bit of a fool's errand to try to achieve actual consensus and make everyone happy or try to implement every person's feedback.

Hard decisions vs. important decisions

Even after choosing a decision-making model and communicating that choice to everyone involved, it's easy to confuse a hard decision with an important decision.

Choosing what to eat for breakfast can be hard, but it's probably not important. Learning that not every hard decision is also an important decision can greatly relieve your anxiety or analysis paralysis and allow you to just pick something, knowing that your choice probably wasn't that important.

Reversible vs. irreversible decisions

Lastly, consider how easy or difficult it will be to change direction after deciding. If the work can easily be undone or changed (a reversible decision), then move forward quickly with what you think the best choice is. No need to overthink things if a wrong choice can be easily corrected.

Irreversible decisions, those that can't be changed (or at least can't be easily changed) should require more thought. Once an irreversible decision is made, it'll be harder to change course in the future.

Conclusion

Understanding these three principles has greatly improved my decision-making skills throughout my career. Remember:

Recognize and communicate the decision-making model being used.
Don't confuse a hard decision with an important one.
Make reversible decisions quickly. Make irreversible decisions with care.

Beyond Code: Communication Skills Every Software Engineer Needs

Tyler Hawkins — Wed, 21 Jan 2026 07:25:27 +0000

Software engineers are not exactly known for their great communication skills. However, despite what you might think, communicating with others is a large part of any software engineering job.

As a software engineer, you likely spend more time communicating than writing code: asking for help, providing help, coordinating projects, submitting code, reviewing code, writing proposals, reviewing proposals, presenting in meetings, having discussions in meetings, submitting bug reports, responding to bug reports, and more.

How well you can communicate will influence how well you’re able to work with others — and how you’re perceived.

Communication is one of those soft skills that will help you progress in your career more than just about anything else, even technical skills. The best software engineers I know are great coders but also excellent at communicating with others.

In my last decade of software engineering, I’ve seen a fair share of both good and bad communication (sometimes it feels like more bad than good). What follows are some tips for how you can communicate more effectively in your day-to-day work.

When creating a pull request

Always write a thorough pull request (PR) description. Include some brief context for what the PR does and why. Add screenshots or videos to show the changes in action. Provide steps for how to test the changes so the reviewer can verify that the code is working as expected.

As the code author, you show competence by being thorough. You also show that you respect your code reviewer’s time by doing those things that will make it easy for them to review your code.

Nothing frustrates me more as a reviewer than being asked to review a PR that has absolutely no context — just a blank PR description or maybe a link to a Jira ticket. What if I don’t know what these changes do? What if I don’t know why these changes are being made? What if I don’t know how to test these changes or where I can even find them in the app? This kind of missing information leads to delays as we go back and forth requesting and gathering more details.

As the code author, you should do as much as possible to reduce the cognitive load on the reviewer. Providing context is just one of many ways you can make your code reviewer fall in love with you.

When reviewing code

Be clear in each comment whether your feedback is an optional “nit” (nitpick) or if it’s blocking feedback. When no explicit distinction is made, it’s sometimes hard for the code author to know if you’re requesting changes, just thinking out loud, or providing alternative approaches just as something to consider for the future.

Be as helpful as you possibly can in your comments. Don’t just say something is “wrong” or needs to be changed. Explain the pitfalls of the current approach and then give a suggested solution if you have one. If the code change is small enough, provide that code snippet in your comment so that the code author can easily apply it. Make it easy for the code author to take your advice.

Time is wasted when both the code author and code reviewer have to spend multiple cycles trying to get clarity on the importance of the requested changes and what an acceptable solution might look like.

Finally, when you’ve requested changes and are finished reviewing, clearly tell the code author that you’re done reviewing for now. Ask them to let you know when the changes have been made and the PR is ready for another review. Time is wasted when one or both of you are sitting around incorrectly thinking that you are waiting on the other person.

When submitting a bug report

Always include steps to reproduce, the expected behavior, the actual behavior you see, and screenshots or videos.

You should strive to make it as easy as possible for someone to understand what issue you’re reporting.

As someone on the receiving end of the bug report, nothing is more frustrating than receiving incomplete information. If all you tell me is “this feature doesn’t work”, I’ll have many followup questions for you: What exactly doesn’t work? Does the app crash? Does it do something but just not what you thought it would do? How are you getting into this state? What are you trying to do? Are there any error messages in the UI or in the console logs?

Gathering missing information that wasn’t included in the bug report leads to more wasted time and more back and forth.

Remember that when you’re submitting a bug report, you’re often looking for help in getting this bug fixed. Be considerate of others and try to be as helpful as you can so that they can help you. Think of what information someone solving the problem might need. When in doubt, providing more information is generally better than providing less information.

When asking for help

Don’t fall prey to the XY problem: asking about your attempted solution rather than your actual problem.

For those not familiar with the XY problem, the scenario usually goes something like this:

User wants to do X.

User doesn’t know how to do X, but thinks they can fumble their way to a solution if they can just manage to do Y.

User doesn’t know how to do Y either.

User asks for help with Y.

Others try to help user with Y, but are confused because Y seems like a strange problem to want to solve.

After much interaction and wasted time, it finally becomes clear that the user really wants help with X, and that Y wasn’t even a suitable solution for X.

Source: The XY Problem

Instead, take a step back and provide context when asking for help. What are you actually trying to solve and why? Then, what have you tried, and what was the result of those explorations?

Without providing the full context for your question, you risk getting help and advice for an attempted solution that won’t actually solve the root of your problem.

When requesting that people do something

Be clear what action is required, by whom, by when.

Meetings can fail for a variety of reasons, particularly if the meeting participants aren’t aligned on what the purpose of the meeting is and what the expected outcome of the meeting should be. If a meeting is coming to a close but it’s unclear what the next steps are, don’t be afraid to be the one who asks “Okay, what are we doing next as a result of this discussion?”

Meetings also become unproductive when notes are taken but the action items are vague. (Or worse, notes aren’t taken at all!) If it’s not clear who owns each action item, the work most likely won’t be done. Instead, assign an owner by writing someone’s name next to each bullet point, and follow up during the next meeting or agreed upon deadline.

Similarly, when sending out announcements over Slack or email, be clear in your message if the information is just an FYI or if action is required.

Conclusion

Everything outlined above is just a small handful of specific scenarios in which you might find yourself. There are sure to be others!

In all your communication, aim for respect and clarity, and try to find ways to reduce the cognitive load for the other person. Strive not just to be understood, but to be so clear that it is impossible to be misunderstood.

Lessons from The Clean Coder

Tyler Hawkins — Wed, 26 Feb 2025 13:39:31 +0000

I read The Clean Coder by Robert C. Martin back in 2022, and I remember feeling like it was chock-full of wisdom.

To avoid confusion, this is not the book Clean Code by the same author. Clean Code focuses mostly on coding itself and hard skills for writing good code. The Clean Coder is a followup book and focuses on soft skills — how we as developers can become true professionals and craftsmen.

Some of the advice in this book is controversial. The piece that stands out most to me is the statement that developers should be spending 60 hours per week on their craft — 40 hours at work and 20 hours learning outside of work. That may not be realistic for many developers, especially those with obligations to their family, community, or elsewhere. The underlying sentiment is useful though, which is that the best developers invest in themselves and are continuously learning. It’s up to you to decide what that looks like in your life.

When I read tech books, I always take notes and highlight passages that resonate with me. It helps me retain the information I found meaningful. I’ve reproduced most of my notes below, and I hope that you’ll find something that resonates with you as well.

Enjoy!

Preface

Managers should not overrule the expert opinions of those they lead, especially when their direct reports have thought about the problem longer, have more context, and have more relevant experience and expertise in the area.

Chapter 1: Professionalism

“You cannot simply keep making the same errors over and over. As you mature in your profession, your error rate should rapidly decrease towards the asymptote of zero. It won’t ever get to zero, but it is your responsibility to get as close as possible to it.”

“It is unprofessional in the extreme to purposely send code that you know to be faulty to QA.”

“Every single line of code that you write should be tested. Period.”

“Why do most developers fear to make continuous changes to their code? They are afraid they’ll break it. Why are they afraid they’ll break it? Because they don’t have tests. It all comes back to the tests.”

“Your career is your responsibility. It is not your employer’s responsibility to make sure you are marketable. It is not your employer’s responsibility to train you, or to send you to conferences, or to buy you books. These things are your responsibility. Woe to the software developer who entrusts his career to his employer.” (He then goes on to say that some employers do provide training or conferences or learning budgets for you, and you should be grateful when they do.)

“You should plan on working 60 hours per week. The first 40 are for your employer. The remaining 20 are for you. During this remaining 20 hours you should be reading, practicing, learning, and otherwise enhancing your career. … Perhaps you think that work should stay at work and that you shouldn’t bring it home. I agree! You should not be working for your employer during those 20 hours. Instead, you should be working on your career. … During that 20 hours you should be doing those things that reinforce that passion. Those 20 hours should be fun!”

At a minimum, every software professional should be familiar with design patterns (gang of four), design principles (SOLID), methods (Waterfall, Agile, Scrum, Kanban), disciplines (TDD, OOP, pair programming, CI/CD), and artifacts (UML, flow charts).

“The best way to learn is to teach.”

“It is the responsibility of every software professional to understand the domain of the solutions they are programming. … It is the worst kind of unprofessional behavior to simply code from a spec without understanding why that spec makes sense to the business. Rather, you should know enough about the domain to be able to recognize and challenge specification errors.”

Chapter 2: Saying No

“Professionals speak truth to power. Professionals have the courage to say no to their managers.”

“A team player is not someone who says yes all the time.”

Stick to your estimates if you have reason to believe they are accurate, even if you are under pressure to commit to finishing at an earlier date. Estimates, targets, and commitments are three different things. Unless you have a radical plan to change how you work, your priorities, or the scope of the work, committing to an earlier deadline than you believe you can finish in is unprofessional.

Chapter 3: Saying Yes

“There are three parts to making a commitment. 1) You say you’ll do it. 2) You mean it. 3) You actually do it.”

“There are very few people who, when they say something, they mean it and then actually get it done. There are some who will say things and mean them, but they never get it done. And there are far more people who promise things and don’t even mean to do them.”

“You can only commit to things that you have full control of. For example, if your goal is to finish a module that also depends on another team, you can’t commit to finish the module with full integration with the other team. But you can commit to specific actions that will bring you to your target.”

“If you can’t make your commitment, the most important thing is to raise a red flag as soon as possible to whoever you committed to.”

“Professionals are not required to say yes to everything that is asked of them. However, they should work hard to find creative ways to make ‘yes’ possible.”

Chapter 4: Coding

Being able to sense your errors and having a fast feedback loop is extremely important.

“Often the customer’s requirements do not actually solve the customer’s problems. It is up to you to see this and negotiate with the customer to ensure that the customer’s true needs are met.”

It’s difficult to write code when you’re worried about something else outside of work, like problems at home or a fight with your spouse. Don’t try to code during these times. Seek instead to resolve the problem so your worries go away. Then you’ll be able to focus again.

“It is incumbent upon you as a professional to reduce your debugging time as close to zero as you can get. Clearly zero is an asymptotic goal, but it is the goal nonetheless.”

“I have solved an inordinate number of problems in the shower. … Sometimes the best way to solve a problem is to go home, eat dinner, watch TV, go to bed, and then wake up the next morning and take a shower.”

When working on a project or task, “regularly measure your progress against your goal, and come up with three fact-based end dates: best case, nominal case, and worst case.”

“Of all the unprofessional behaviors that a programmer can indulge in, perhaps the worst of all is saying you are done when you know you aren’t.”

“You avoid the problem of false delivery by creating an independent definition of ‘done.’”

“Learn how to ask for help. When you are stuck, or befuddled, or just can’t wrap your mind around a problem, ask someone for help. … It is unprofessional to remain stuck when help is easily accessible.”

“Nothing can bring a young software developer to high performance quicker than his own drive, and effective mentoring by his seniors.”

Chapter 5: Test Driven Development

“The bottom line is that TDD works, and everybody needs to get over it.”

Follow the “red, green, refactor” cycle.

“When you have a suite of tests that you trust, then you lose all fear of making changes.”

“Writing your tests first creates a force that drives you to a better decoupled design.”

Chapter 6: Practicing

“The purpose of learning a kata [in martial arts] is not to perform it on stage. The purpose is to train your mind and body how to react in a particular combat situation. The goal is to make the perfected movements automatic and instinctive so that they are there when you need them.”

“[Programming katas are] a good way to drive common problem/solution pairs into your subconscious, so that you simply know how to solve them when facing them in real programming.”

“Practicing is what you do when you aren’t getting paid. You do it so that you will be paid, and paid well.”

Chapter 7: Acceptance Testing

On changing requirements: “The problem is that things appear different on paper than they do in a working system. When the business actually sees what they specified running in a system, they realize that it wasn’t what they wanted at all. Once they see the requirement actually running, they have a better idea of what they really want and it’s usually not what they are seeing.”

“The purpose of acceptance tests is communication, clarity, and precision. By agreeing to them, the developers, stakeholders, and testers all understand what the plan for the system behavior is.”

“Acceptance tests should always be automated. There is a place for manual testing elsewhere in the software lifecycle, but these kinds of tests should never be manual. The reason is simple: cost. … The cost of automating acceptance tests is so small in comparison to the cost of executing manual test plans that it makes no economic sense to write scripts for humans to execute.”

“Typical business analysts write the ‘happy path’ versions of the tests, because those tests describe the features that have business value. QA typically writes the ‘unhappy path’ tests, the boundary conditions, exceptions, and corner cases. This is because QA’s job is to help think about what can go wrong.”

“Acceptance tests are not unit tests. Unit tests are written by programmers for programmers. They are formal design documents that describe the lowest level structure and behavior of the code. The audience is programmers, not business. Acceptance tests are written by the business for the business (even when you, the developer, end up writing them). They are formal requirements documents that specify how the system should behave from the business’ point of view. The audience is the business and the programmers.”

“Unit tests and acceptance tests are documents first, and tests second. Their primary purpose is to formally document the design, structure, and behavior of the system. The fact that they automatically verify the design, structure, and behavior that they specify is wildly useful, but the specification is their true purpose.”

Chapter 8: Testing Strategies

“Professional developers test their code.”

Follow the testing pyramid.

“Unit tests provide as close to 100% coverage as is practical. Generally this number should be somewhere in the 90s. And it should be true coverage as opposed to false tests that execute code without asserting the behavior.”

“Component tests cover roughly half the system. They are directed more towards happy-path situations and very obvious corner, boundary, and alternate-path cases. The vast majority of unhappy-path cases are covered by unit tests and are meaningless at the level of component tests.”

“Integration tests are typically not executed as part of the Continuous Integration suite, because they often have longer runtimes. Instead, these tests are run periodically (nightly, weekly, etc.) as deemed necessary by their authors.”

“System tests cover perhaps 10% of the system. This is because their intent is not to ensure correct system behavior, but correct system construction. The correct behavior of the underlying code and components have already been ascertained by the lower layers of the pyramid.”

“[Manual exploratory tests] are not automated, nor are they scripted. … Creating a written test plan for this kind of testing defeats the purpose.”

Chapter 9: Time Management

“Sometimes a meeting will be about something that interests you, but is not immediately necessary. You will have to choose whether you can afford the time. Be careful — there may be more than enough of these meetings to consume your days.”

“Sometimes you find yourself siting in a meeting that you would have declined had you known more. … Remaining in a meeting that has become a waste of time for you, and to which you can no longer significantly contribute, is unprofessional.”

“Iteration planning meetings are meant to select the backlog items that will be executed in the next iteration. Estimates should already be done for the candidate items. Assessment of business value should already be done. In really good organizations the acceptance/component tests will already be written, or at least sketched out.”

You can only intensely focus for so long. Manage your time wisely so that you are coding during high-focus times and doing more trivial tasks during other times.

“[Professionals] never become so vested in a solution that they can’t abandon it.”

Chapter 10: Estimation

“Business likes to view estimates as commitments. Developers like to view estimates as guesses. The difference is profound.”

“An estimate is not a number. An estimate is a distribution.”

“Professionals draw a clear distinction between estimates and commitments. They do not commit unless they know for certain they will succeed.”

PERT (Program Evaluation and Review Technique): You provide three numbers for your estimate — optimistic, nominal (most likely), and pessimistic.

“Software professionals are very careful to set reasonable expectations despite the pressure to try to go fast.”

“[When estimating tasks as a team,] agreement does not need to be absolute. As long as the estimates are close, it’s good enough. So, for example, a smattering of 3s and 4s is agreement. However if everyone holds up 4 fingers except for one person who holds up 1 finger, then they have something to talk about.”

“The simultaneity of displaying fingers is important. We don’t want people changing their estimates based on what they see other people do.”

“If you break up a large task into many smaller tasks and estimate them independently, the sum of the estimates of the small tasks will be more accurate than a single estimate of the larger task.”

“Errors in estimates tend toward underestimation and not overestimation.”

“Breaking the tasks up is a good way to understand those tasks better and uncover surprises.”

Chapter 11: Pressure

“You know what you believe by observing yourself in a crisis. If in a crisis you follow your disciplines, then you truly believe in those disciplines. On the other hand, if you change your behavior in a crisis, then you don’t truly believe in your normal behavior.”

“Slow down. Think the problem through.”

Chapter 12: Collaboration

“We didn’t become programmers because we like working with people.”

“It is far better to break down all walls of code ownership and have the team own all the code. I prefer teams in which any team member can check out any module and make any changes they think are appropriate. I want the team to own the code, not the individuals.”

“Although all team members have a position to play, all team members should also be able to play another position in a pinch.”

“Perhaps you believe that you work better when you work alone. That may be true, but it doesn’t mean that the team works better when you work alone. … There are times when working alone is the right thing to do. There are times when you simply need to think long and hard about a problem. There are times when the task is so trivial that it would be a waste to have another person working with you. But, in general, it is best to collaborate closely with others and to pair with them a large fraction of the time.”

Chapter 13: Teams and Projects

“It makes no sense to tell a programmer to devote half their time to project A and the rest of their time to project B, especially when the two projects have two different project managers, different business analysts, different programmers, and different testers.”

“It takes time for a team to work out their differences, come to terms with each other, and really gel. It might take six months. It might even take a year. But once it happens, it’s magic. A gelled team will plan together, solve problems together, face issues together, and get things done. Once this happens, it’s ludicrous to break it apart just because a project comes to an end. It’s best to keep that team together and just keep feeding it projects.”

“Teams are harder to build than projects. Therefore, it is better to form persistent teams that move together from one project to the next and can take on more than one project at a time. The goal in forming a team is to give that team enough time to gel, and then keep it together as an engine for getting many projects done.”

Chapter 14: Mentoring, Apprenticeship, and Craftsmanship

“I’e noticed that [software engineers who do really well] have something in common: Nearly all of them taught themselves to program before they entered university and continued to teach themselves despite university.”

“Even the best CS degree programs do not typically prepare the young graduate for what they will find in industry. … What you learn in school and what you find on the job are often very different things.”

“Companies lose huge amounts of money due to the inadequate training of their software developers. Somehow the software development industry has gotten the idea that programmers are programmers, and that once you graduate you can code. Indeed, it is not at all uncommon for companies to hire kids right out of school, form them into ‘teams,’ and ask them to build the most critical systems. It’s insane!”

“A craftsman is someone who works quickly, but without rushing, who provides reasonable estimates and meets commitments. A craftsman knows when to say no, but tries hard to say yes. A craftsman is a professional. Craftsmanship is the mindset held by craftsmen. Craftsmanship is a meme that contains values, disciplines, techniques, attitudes, and answers.”

“School can teach the theory of computer programming. But school does not, and cannot teach the discipline, practice, and skill of being a craftsman. Those things are acquired through years of personal tutelage and mentoring. It is time for those of us in the software industry to face the fact that guiding the next batch of software developers to maturity will fall to us, not to the universities. It’s time for us to adopt a program of apprenticeship, internship, and long-term guidance.”

The Value of Finishing

Tyler Hawkins — Mon, 03 Feb 2025 15:23:14 +0000

“The value of the thing is found in finishing the thing.”

This is the advice I like to give about most software engineering projects. You can keep working on something indefinitely to get it just right, but there’s no value provided until you release it and it’s actually in the hands of customers who can use it.

Until that pull request is merged and the code is deployed to production, it’s not real. It’s just an idea.

Something that is released and that is imperfect is more valuable than a thing that’s unreleased and is completely perfect.

Real world examples

Let’s consider some analogies:

There is no value in assembling half of a piece of furniture. It’s not until the furniture is completely assembled that you can use it.

There is no value in putting your clothes in the washer but not the dryer. It’s not until the clothes are both washed and dried that they’re ready to be worn again.

There is no value in cooking a meal but not eating it. Eating and enjoying the food is the point of making the meal.

There is no value in writing a blog post draft but not hitting the Submit button. You could spend your whole life editing and revising your words, but it’s not until your work is published that other people can read it and benefit from it.

The unfinished task provides no value. In fact, the unfinished task is usually just a mess. It’s finishing the task that provides the value. Getting to the end result is the reason you even started the task.

Lessons for software engineering

So what does this idea mean for software engineers?

It means that you should complete work in small chunks that you can release. Don’t release sloppy or unfinished work, but release things that solve real problems and provide real value, even if they don’t solve every problem yet.

It means you should merge and deploy your code often. Avoid long-running feature branches.

It means you shouldn’t let “perfect” become the enemy of the good. Get the thing out there, even if it doesn’t have the perfect API or the perfect design. Again, don’t cut major corners or create an inferior user experience. But learn what’s good enough, and don’t let perfectionism get in the way.

It means that working on a single task and finishing it is better than working on three tasks simultaneously and finishing none of them. The one finished thing brings value. The three unfinished things don’t bring any value yet, because they’re not done.

Please don’t misunderstand

Don't try to take the lesson too far. I'm not advocating for sloppy work, cutting corners, or lowering your standards. I'm also not saying to focus only on the end result or to ignore the lessons you can learn along the way, especially for projects that ultimately get abandoned. Not every adventure we embark on ends up being a success.

But I am advocating for finishing.

The value of the thing is found in finishing the thing.

Lessons from A Philosophy of Software Design

Tyler Hawkins — Wed, 15 Jan 2025 15:05:00 +0000

I recently finished reading A Philosophy of Software Design by John Ousterhout. If you enjoyed Clean Code or The Pragmatic Programmer, you’ll likely enjoy this one too. It’s very similar to those books, has some overlapping content, and focuses primarily on what separates good software design from bad software design.

Enjoy!

On coding advice

When you disagree with someone’s coding advice (something in this book or in Clean Code), try to understand why you disagree with it.

“Every rule has its exceptions, and every principle has its limits. If you take any design idea to its extreme, you’ll probably end up in a bad place.”

Complexity

“Complexity is more apparent to readers than writers. If you write a piece of code and it seems simple to you, but other people think it is complex, then it is complex. When you find yourself in situations like this, it’s worth probing other developers to find out why the code seems complex to them; there are probably some interesting lessons to learn from the disconnect between your opinion and theirs. Your job as a developer is not just to create code that you can work with easily, but to create code that others can also work with easily.”

Symptoms of complexity

Change amplification: Seemingly simple changes require code modifications in many different places
Cognitive load: How much a developer needs to know in order to complete a task
Unknown unknowns: It’s not obvious which pieces of code must be modified to complete a task

Good design should be obvious.

Modules, interfaces, and implementations

Modules should be deep. Complex implementations should be hidden behind simple interfaces with sensible defaults that work for the most common use cases.

“The best features are the ones you get without even knowing they exist.”

“As a module developer, you should strive to make life as easy as possible for the users of your module, even if it means extra work for you.”

“Reduce the number of places where exceptions must be handled.”

Design approaches

“Designing software is hard, so it’s unlikely that your first thoughts about how to structure a module or system will produce the best design. You’ll end up with a much better result if you consider multiple options for each major design decision.”

“Try to pick approaches that are radically different from each other; you’ll learn more that way. Even if you are certain that there is only one reasonable approach, consider a second design anyway, no matter how bad you think it will be. It will be instructive to think about the weaknesses of that design and contrast them with the features of other designs.”

Comments and documentation

Comments should be used to explain things that can’t be expressed in code, like the rationale for why a certain decision was made.

“The biggest challenge with cross-module documentation is finding a place to put it where it will naturally be discovered by developers.”

Consistency, conventions, and coding styles

“Consistency creates cognitive leverage: once you have learned how something is done in one place, you can use that knowledge to immediately understand other places that use that same approach.”

Document coding conventions and coding style preferences. Automate and enforce what you can, like with ESLint and Prettier. When joining a new company or team, stick to existing conventions that are already in place. Refactoring or re-writing all the code to use a new convention is rarely worth it.

Tactical vs. strategic programming; also Agile

Tactical vs. strategic programming. Don’t just focus on getting a small change working if it makes future changes more difficult.

“One of the risks of agile development is that it can lead to tactical programming. Agile development tends to focus developers on features, not abstractions, and it encourages developers to put off design decisions in order to produce working software as soon as possible. For example, some agile practitioners argue that you shouldn’t implement general-purpose mechanisms right away; implement a minimal special-purpose mechanism to start with, and refactor into something more generic later, once you know that it’s needed. Although these arguments make sense to a degree, they are against an investment approach, and they encourage a more tactical style of programming. This can result in rapid accumulation of complexity.”

Importance of tests

“Tests, particularly unit tests, play an important role in software design because they facilitate refactoring. Without a test suite, it’s dangerous to make major structural changes to a system. There’s no easy way to find bugs, so it’s likely that bugs will go undetected until the new code is deployed, where they are much more expensive to find and fix. As a result, developers avoid refactoring in systems without good test suites; they try and minimize the number of code changes for each new feature or bug fix, which means that complexity accumulates and design mistakes don’t get corrected.

“With a good set of tests, developers can be more confident when refactoring because the test suite will find most bugs that are introduced. This encourages developers to make structural improvements to a system, which results in a better design. Unit tests are particularly valuable: they provide a higher degree of code coverage than system tests, so they are more likely to uncover any bugs.”

Performance improvements

Before making performance changes, measure what you need in order to create benchmarks for the existing performance. Our intuitions of what changes will improve performance are sometimes wrong, having either no meaningful impact or actually making performance worse.

Design code around the critical path. Performance improvements in other places that are not the biggest bottleneck will still result in a bottleneck when you hit that part of the path.

Conclusion and the benefits of good design

“The investments you make in good design will pay off quickly. The modules you defined carefully at the beginning of a project will save you time later as you reuse them over and over. The clear documentation that you wrote six months ago will save you time when you return to the code to add a new feature. The time you spent honing your design skills will also ay for itself: as your skills and experience grow, you will find that you can produce good designs more and more quickly. Good design doesn’t really take that much longer than quick-and-dirty design, once you know how.

“The reward for being a good designer is that you get to spend a larger fraction of your time in the design phase, which is fun. Poor designers spend most of their time chasing bugs in complicated and brittle code. If you improve your design skills, not only will you produce higher quality software more quickly, but the software development process will be more enjoyable.”

Productivity and Organization Tips for Software Engineers

Tyler Hawkins — Mon, 06 Jan 2025 16:00:00 +0000

I’ve been a software engineer for a little over a decade now, and I like to think I’m a pretty organized person. I have a system for everything, and these systems help my mind and my day run more smoothly.

Organization isn’t something that comes naturally to everyone, so today I thought I’d share some of my strategies that help me have a productive and fulfilling work day.

I’ve organized them below sequentially, walking you through how I start my day, things I do throughout my day, and how I end my day.

Start of my day

Startup tasks and message checking

To get oriented each morning, I check several things:

My calendar
My todo list
Slack
Email

This usually takes just 5–10 minutes and helps me get ready for everything going on that day.

If I have an interview to conduct, I’ll block off time on my calendar before the interview to prepare and after the interview to submit my feedback. If I have a 1on1 with my manager, I’ll add an item to my todo list to prepare notes for what I want to talk about.

If I have emails or Slack messages that need my attention, I’ll either respond to them right away or add an item to my todo list. As a rule of thumb, if the message only takes a couple minutes to respond to or take care of, I’ll just do it right away. If it’s something that will take longer, like someone asking me to review a pull request or a tech spec, I’ll add that to my todo list.

Good morning and morning report

Next, I go through a small routine of morning tasks. This involves saying good morning to my teammates over Slack (we’re all remote) and sending out a short morning report of noteworthy things going on this day.

The morning report usually includes our sprint goals, pull requests and tech specs needing review, and any relevant upcoming events or action items. The morning report only takes a couple minutes to write, and it helps keep everyone on the team on the same page.

Accessibility tip of the day

I’m passionate about web accessibility, so each morning I also send out a short “Accessibility Tip of the Day” in Slack. This tip of the day is a short tidbit of info, usually focused on engineering, product, and design. I’ve been doing this for about a year and a half now, and I’ve written 300 tips so far! (You can find them on LinkedIn under the hashtag #accessibilityTipOfTheDay.)

Urgent tasks and unblocking others

At this point I’m usually about a half hour into my day. If there are any tasks that urgently need to be done, and they can be done quickly, I’ll try to knock out several small things in the next half hour. This usually includes short pull request reviews. I always appreciate people quickly reviewing my code, so I try to do the same. This helps unblock other engineers who are waiting on a review, and it helps keep the work moving along.

Throughout the day

One big impactful thing

What the rest of my day looks like will vary based on how many meetings I have or if I have an interview to conduct, but on my todo list I always have one big thing that’s my main goal for the day. If I can get this one thing done, I’ll consider it a successful day. This could be something like completing an important Jira task, writing an RFC, or finishing a blog post draft for our engineering blog. Whatever the task is, it’s usually something that I need 2–3 hours of uninterrupted time to complete.

This “one big thing” strategy has a lot of different names, and you may be familiar with ideas like:

Paul Graham’s essay “Maker’s Schedule, Manager’s Schedule”, where he argues that software engineers (“makers”) need about a half day of uninterrupted time to get any meaningful work done
Brian Tracy’s book Eat That Frog!, where he encourages you to do the hardest thing in your day first
Mihaly Csikszentmihalyi’s book Flow, which describes a “flow” state of intense enjoyment, creativity, and/or productivity in which you lose yourself in what you’re doing
Oliver Burkeman’s 3–3–3 method, in which he advocates for spending three hours on an important task, doing three smaller tasks, and doing three maintenance tasks each day
The rocks and sand in a jar analogy, which teaches that you should focus on the big important things first (If you have large rocks, small rocks, sand, and a jar, the order in which you put the items in the jar matters. If you put the sand and small rocks in the jar first, you’ll find that the large rocks don’t fit. But if you put the large rocks in first, then the small rocks, and next the sand, you’ll find that there’s room for all of them. Prioritize the big important things, and there will be room for the rest.)

Several smaller things

I dislike context switching, so after I’ve finished my one big thing, I’ll do a batch of smaller things all in a row. This could be reviewing more pull requests, writing or improving a wiki, reviewing a tech spec, responding to new messages, completing a shorter Jira task, or reading a short blog post.

Note taking

I learn best through written communication. I’d much rather read something than watch a video or have a meeting, and I’m much better at organizing my thoughts when I write them down.

For just about any task I work on, I open a scratch pad in my Notes app to jot down my thoughts. When working on an engineering task, I might write down bullet points of what the problem is and how I’m planning on solving it. When troubleshooting something, I’ll write down the steps I took and what did or didn’t work. This helps me work through problems and also makes it really easy to send my notes to other engineers if I need help.

This written log usually isn’t something that I ever need to look at again after I’ve finished the task, but it does sometimes come in handy when I encounter a similar problem in the future and want to see how I solved it in the past.

Todo lists

I’ve mentioned my todo list already that I create and review each morning. Throughout the day, if a thought pops into my head for something I should do, I add it to my todo list right away. This allows me to go back to whatever I’m actively working on without needing to worry about remembering this other new thing.

I’ve found that the more information I can get out of my head and written down, the less cognitive load I have, and the less I need to remember.

Strategic timing

You can get a lot more done in a day if you do things in the “right” order. For example, if I know that I have two hours of meetings in the afternoon, I try to get a pull request ready before then. That way, someone can review my code while I’m in meetings, and (hopefully) my pull request will be ready to be merged as soon as I get out of my last meeting.

Similarly, if I can get something up for review in the morning, that leaves time for me to switch to other smaller tasks while I wait for a review (the rocks and sand in a jar analogy).

End of the day

Shutdown routine

I end my work day in much the same way that I start it. Before signing off, I review my calendar for tomorrow, and I add items to tomorrow’s todo list.

Both of these things are a shutdown routine to help clear my mind so I don’t keep thinking about work for the rest of the day. If a work thought does pop into my head during the evening, I’ll quickly write that down on my todo list so I don’t have to worry about trying to remember it tomorrow. This helps reduce the cognitive load, lets me focus on my family, and also ensures that I don’t lose any “aha” moments when a sudden stroke of insight occurs.

Conclusion

I’ve more or less followed this routine for years now, and it’s helped me immensely. I hope something in this piece has resonated with you and will help you too! Thanks for reading.

Heroku for ChatOps: Start and Monitor Deployments from Slack

Tyler Hawkins — Tue, 04 Jun 2024 14:22:23 +0000

In our last two articles, we explored how to configure CI/CD for Heroku using Heroku pipelines. When viewing a pipeline within the Heroku dashboard, you can easily start a deployment or promote your code from one environment to the next with the click of a button. From the dashboard, you can monitor the deployment and view its progress.

This all works really well, assuming that you have Heroku open in your browser. But, what if you wanted to do it all from Slack?

Software engineers use a lot of apps at work. Throughout the day, we are constantly bouncing between Zoom meetings, Jira tasks, Slack conversations, GitHub, email, our calendar, and our IDE. This context switching can be exhausting and also lead to a lot of visual clutter on our monitors.

Sometimes, it’s nice to just live in Slack, and that’s why many tools offer Slack integrations. With these Slack integrations, you can monitor various processes and even use shortcut commands to trigger actions.

Heroku ChatOps, the Heroku Slack integration, allows you to start and monitor deployments directly from Slack. In this article, we’ll explore some of the Slack commands it offers.

Getting Started

If you’d like to follow along throughout this tutorial, you’ll need a Heroku account and a GitHub account. You can create a Heroku account here, and you can create a GitHub account here.

The demo app that we will use with our Heroku pipeline in this article is deployed to Heroku, and the code is hosted on GitHub.

Create Our Heroku Pipeline

We won’t go through the step-by-step process for creating a Heroku pipeline in this article. Refer to these articles for a walkthrough of creating a Heroku pipeline:

You can also read the Heroku docs for Heroku pipelines.

Configuring your Heroku pipeline includes the following steps:

Create a GitHub repo.
Create a Heroku pipeline.
Connect the GitHub repo to the Heroku pipeline.
Add a staging app to the pipeline.
Add a production app to the pipeline.

The other activities that you’ll see in those articles, such as configuring review apps, Heroku CI, or automated deployments are optional. In fact, for the purposes of this demo, I recommend not configuring automated deployments, since we’ll be using some Slack commands to start the deployments.

When you’re done, you should have a Heroku pipeline that looks something like this:

Example Heroku pipeline

Connect to Slack

Now that you have your Heroku pipeline created, it’s time for the fun part: integrating with Slack. You can install the Heroku ChatOps Slack app here.

Clicking that link will prompt you to grant the Heroku ChatOps app permission to access your Slack workspace:

Grant Heroku ChatOps access to your Slack workspace

After that, you can add the Heroku ChatOps app to any Slack channel in your workspace.

Add the Heroku ChatOps app

After adding the app, type /h login and hit Enter. This will prompt you to connect your Heroku and GitHub accounts. You’ll see several Heroku OAuth and GitHub OAuth screens where you confirm connecting these accounts.

(As a personal anecdote, I found that it took me several tries to connect my Heroku account and my GitHub account. It may be due to having several Slack workspaces to choose from, but I’m not sure.)

After connecting your Heroku account and your GitHub account, you’re ready to start using Heroku in Slack.

Connect your Heroku and GitHub accounts

View All Pipelines

To view all deployable pipelines, you can type /h pipelines:

View all pipelines

View Pipeline Info

To see information about any given pipeline, type /h info <PIPELINE_NAME>. (Anything you see in angle brackets throughout this article should be replaced by an actual value. In this case, the value would be the name of a pipeline — for example, “heroku-flow-demo-pipeline”.)

View pipeline info

View Past Releases

To view a history of past releases for any given pipeline, type /h releases <PIPELINE_NAME>.

View past releases

This command defaults to showing you past releases for the production app, so if you want to see the past releases for the staging app, you can type /h releases <PIPELINE_NAME> in <STAGE_NAME>, where <STAGE_NAME> is “staging”.

View past staging releases

Deploy to Staging

Now that we know which pipelines are available, we can see information about any given pipeline along with when the code was last released for that pipeline. We’re ready to trigger a deployment.

Most engineering organizations have a Slack channel (or channels) where they monitor deployments. Imagine being able to start a deployment right from that channel and monitor it as it goes out! That’s exactly what we’ll do next.

To start a deployment to your staging environment, type /h deploy <PIPELINE_NAME> to <STAGE_NAME>, where <STAGE_NAME> is “staging”.

Deploy to staging

After running that command, an initial message is posted to communicate that the app is being deployed. Shortly after, you’ll also see several more messages, this time in a Slack thread on the original message:

Slack messages sent when deploying to staging

If you want to verify what you’re seeing in Slack, you can always check the Heroku pipeline in your Heroku dashboard. You’ll see the same information: The staging app has been deployed!

Staging app shown in the Heroku dashboard

Promote to Production

Now, let’s promote our app to production. Without the Slack commands, we could navigate to our Heroku pipeline, click the “Promote to production” button, and then confirm that action in the modal dialog that appears. However, we’d prefer to stay in Slack.

To promote the app to production from Slack, type /h promote <PIPELINE_NAME>.

Promote to production

Just like with the staging deployment, an initial Slack message will be sent, followed by several other messages as the production deployment goes out:

Slack messages sent when promoting to production

And — voilà — the latest changes to the app are now in production!

Conclusion

Now you can start and monitor Heroku app deployments all from Slack — no need to context switch or move between multiple apps.

For more use cases and advanced setups, you can also check out the docs.

Happy deploying!

Going with the Flow for CI/CD: Heroku Flow with Gitflow

Tyler Hawkins — Wed, 08 May 2024 13:15:18 +0000

In the previous article in this series, we looked at how we could automate deploys to Heroku using Heroku Flow for our CI/CD. That setup had two Heroku apps for staging and production, but only used a single main branch. The staging app was automatically deployed when you committed to the main branch, and the production app was manually deployed by clicking the “Promote to production” button in the Heroku pipeline.

That strategy assumes that you’re doing “trunk-based development”, in which you commit to a single main branch in your code repo.

However, some engineering teams still follow a branching strategy called Gitflow, which involves using a dev branch and a main branch. Feature branches are merged into the dev branch to deploy code to a staging environment, and on a regular cadence the dev branch is merged into the main branch to release the code to the production environment.

In this article, we’ll consider how we can configure Heroku Flow to meet our CI/CD needs when following the Gitflow branching strategy. We’ll use our Heroku Pipeline to deploy our app to our staging environment when we push to the dev branch and deploy our app to our production environment when we push to the main branch.

Ready to go with the flow?

Getting Started

If you’d like to follow along throughout this tutorial, you’ll need a Heroku account and a GitHub account. You can create a Heroku account here, and you can create a GitHub account here.

The demo app shown in this article is deployed to Heroku, and the code is hosted on GitHub.

Running Our App Locally

You can run the app locally by forking the repo in GitHub, installing dependencies, and running the start command. In your terminal, do the following after forking the repo:

$ cd heroku-flow-gitflow-demo
$ npm install
$ npm start

After starting the app, visit http://localhost:5001/ in your browser, and you’ll see the app running locally:

Demo app

Creating Our Heroku Pipeline

Now that we have the app running locally, let’s get it deployed to Heroku so that it can be accessed anywhere, not just on your machine.

We’re going to create a Heroku pipeline that includes two apps: a staging app and a production app.

To create a new Heroku pipeline, navigate to your Heroku dashboard, click the “New” button in the top-right corner of the screen, and then choose “Create new pipeline” from the menu.

Create new pipeline

In the dialog that appears, give your pipeline a name, choose an owner (yourself), and connect your GitHub repo. If this is your first time connecting your GitHub account to Heroku, a second popup will appear in which you can confirm giving Heroku access to GitHub.

After connecting to GitHub, click “Create pipeline” to finish the process.

Configure your pipeline

With that, you’ve created a Heroku pipeline. Nice work!

Newly created pipeline

Creating Our Staging and Production Apps

As we mentioned, we’ll use two environments for our app: a staging environment and a production environment. The staging environment is where code is deployed for acceptance testing and any additional QA. The production environment is where code is released to actual users.

Let’s add a staging app and a production app to our pipeline. Both of these apps will be based on the same GitHub repo.

To add a staging app, click the “Add app” button in the Staging section. Next, click “Create new app” to open a side panel.

Create a new staging app

In the side panel, give your app a name, choose an owner (yourself), and choose a region (I left mine in the United States). Then click “Create app” to confirm your changes.

Configure your staging app

Congrats, you’ve just created a staging app!

Newly created staging app

Now let’s do the same thing, but this time for our production app. When you’re done configuring your production app, you should see both apps in your pipeline:

Heroku pipeline with a staging app and a production app

Configuring Automatic Deploys

We want our app to be deployed to our staging environment any time we commit to our repo’s dev branch. To do this, click the dropdown button for the staging app and choose “Configure automatic deploys” from the menu.

Configure automatic deploys for the staging app

In the dialog that appears, make sure the dev branch is targeted, and check the box to “Wait for CI to pass before deploy.” In a later step, we’ll configure Heroku CI so that we can run tests in a CI pipeline. We don’t want to deploy our app to our staging environment unless CI is passing.

Deploy the dev branch to the staging app after CI passes

Now let’s do the same thing for the production app, but this time choosing to deploy our production app whenever we commit code to the main branch.

Configure automatic deploys for the production app

Deploy the main branch to the production app after CI passes

Enabling Heroku CI

If we’re going to require CI to pass, we had better have something configured for CI! Navigate to the “Tests” tab and then click the “Enable Heroku CI” button.

Enable Heroku CI

Our demo app is built with Node and runs unit tests with Jest. The tests are run through the npm test script. Heroku CI allows you to configure more complicated CI setups using an app.json file, but in our case because the test setup is fairly basic, Heroku CI can figure out which command to run without any additional configuration on our part. Pretty neat!

Enabling Review Apps

For the last part of our pipeline setup, let’s enable review apps. Review apps are temporary apps which get deployed for every pull request (PR) created in GitHub. They’re incredibly helpful when you want your code reviewer to manually review your changes. With a review app in place, the reviewer can simply open the review app rather than having to pull down the code onto their machine to run the app locally.

To enable review apps, click the “Enable Review Apps” button on the pipeline page.

Enable Review Apps

In the dialog that appears, check all three boxes.

The first box enables review apps to be automatically created for each PR.
The second box ensures that the review app isn’t created until CI passes.
The third box sets a time limit on how long a stale review app should exist until it is destroyed. Review apps use Heroku resources just like your regular apps, so you don’t want these temporary apps sitting around unused and costing you or your company more money.

When you’re done with your configuration, click “Enable Review Apps” to finalize your changes.

Configure your review apps

Seeing It All in Action

Alright, you made it! Let’s review what we’ve done so far.

We created a Heroku pipeline.
We created a staging app and a production app for that pipeline.
We enabled automatic deploys from the dev branch to our staging app.
We enabled automatic deploys from the main branch to our production app.
We enabled Heroku CI to run tests for every PR.
We enabled the creation of Heroku review apps for every PR.

Now let’s see it all in action.

Create a feature branch off of your dev branch with any code change you’d like, and then use that to create a PR in GitHub to merge that feature branch into dev. I made a very minor UI change, updating the heading text from “Heroku Flow Gitflow Demo” to “Heroku Flow Gitflow Branching”.

Right after the PR is created, you’ll note that a new “check” gets created in GitHub for the Heroku CI pipeline.

GitHub PR check for the Heroku CI pipeline

You can view the test output back in Heroku on your Tests tab:

CI pipeline test output

After the CI pipeline passes, you’ll note that another piece of info gets appended to your PR in GitHub. The review app is deployed, and GitHub shows a link to the review app. Click the “View deployment” button, and you’ll see a temporary Heroku app with your code changes.

View deployment to see the review app

You can also find a link to the review app in your Heroku pipeline:

Review app found in the Heroku pipeline

Let’s assume that you’ve gotten a code review and that everything looks good. It’s time to merge your PR.

After you’ve merged your PR, look back at the Heroku pipeline. You’ll see that Heroku automatically deployed the staging app since new code was committed to the dev branch.

Staging app was automatically deployed

At this point in the software development lifecycle, there might be some final QA or acceptance testing of the app in the staging environment. Let’s assume that everything still looks good and that you’re ready to release this change to your users in production.

You can create another PR to merge the dev branch into the main branch, or you can do this from your terminal by checking out the main branch and then running git merge dev and git push.

Once you’ve committed these changes to the main branch, look at your Heroku pipeline again, and you’ll see that the production app was automatically deployed.

Production app was automatically deployed

And with that, your changes are now in production for all your users to see. Way to go!

Updated demo app with new changes in production

Conclusion

If you’ve followed along this far, give yourself a pat on the back. Walking through these steps, we’ve configured everything we need for an enterprise-ready CI/CD solution for a team using the Gitflow branching strategy and multiple environments.

It doesn’t matter if you prefer trunk-based development or Gitflow as your branching strategy — Heroku Flow can support either.

Now not only can you host your apps on Heroku, but you can set up all of your CI/CD infrastructure on Heroku’s platform as well.

How I Finally Got All My CI/CD in One Place: Getting my CI/CD act together with Heroku Flow

Tyler Hawkins — Mon, 29 Apr 2024 13:05:32 +0000

The Heroku team has long been an advocate of CI/CD. Their platform integrates with many third-party solutions like GitLab CI/CD or GitHub Actions.

In a previous article, I demonstrated how you can configure your Heroku app with GitLab CI/CD to automatically deploy your app to production. In a follow-up article, I walked you through a slightly more nuanced setup involving both a staging environment and a production environment.

But if you want to go all in on Heroku, you can use a series of solutions called Heroku Flow to configure all your CI/CD without any third parties. Heroku Flow brings together Heroku pipelines, Heroku CI, Heroku review apps, a GitHub integration, and a release phase.

In this article, I’ll show you how to set this up for your own projects.

Getting Started

Before we begin, if you’d like to follow along, you’ll need a Heroku account and a GitHub account. You can create a Heroku account here, and you can create a GitHub account here.

The demo app shown in this article is deployed to Heroku, and the code is hosted on GitHub.

Running Our App Locally

You can run the app locally by forking the repo in GitHub, installing dependencies, and running the start command. In your terminal, do the following after forking the repo:

$ cd heroku-flow-demo
$ npm install
$ npm start

After starting the app, visit http://localhost:5001/ in your browser, and you’ll see the app running locally:

Demo app

Creating Our Heroku Pipeline

Now that we have the app running locally, let’s get it deployed to Heroku so that it can be accessed anywhere, not just on your machine.

We’ll create a Heroku pipeline that includes a staging app and a production app.

To create a new Heroku pipeline, navigate to your Heroku dashboard, click the “New” button in the top-right corner of the screen, and then choose “Create new pipeline” from the menu.

Create new pipeline

After connecting to GitHub, click “Create pipeline” to finish the process.

Configure your pipeline

With that, you’ve created a Heroku pipeline. Well done!

Newly created pipeline

Creating Our Staging and Production Apps

Most engineering organizations use at least two environments: a staging environment and a production environment. The staging environment is where code is deployed for acceptance testing and any additional QA. Code in the staging environment is then promoted to the production environment to be released to actual users.

Let’s add a staging app and a production app to our pipeline. Both of these apps will be based on the same GitHub repo.

To add a staging app, click the “Add app” button in the “Staging” section. Next, click “Create new app” to open a side panel.

Create a new staging app

In the side panel, give your app a name, choose an owner (yourself), and choose a region (I left mine in the United States). Then click “Create app” to confirm your changes.

Configure your staging app

Congrats, you’ve just created a staging app!

Newly created staging app

Now let’s do the same thing, but this time for our production app. When you’re done configuring your production app, you should see both apps in your pipeline:

Heroku pipeline with a staging app and a production app

Configuring Automatic Deploys

We want our app to be deployed to our staging environment any time we commit to our repo’s main branch. To do this, click the dropdown button for the staging app and choose “Configure automatic deploys” from the menu.

Configure automatic deploys

In the dialog that appears, make sure the main branch is targeted, and check the box to “Wait for CI to pass before deploy.” In our next step, we’ll configure Heroku CI so that we can run tests in a CI pipeline. We don’t want to deploy our app to our staging environment unless CI is passing.

Deploy the main branch to the staging app after CI passes

Enabling Heroku CI

If we’re going to require CI to pass, we better have something configured for CI! Navigate to the “Tests” tab and then click the “Enable Heroku CI” button.

Enable Heroku CI

Our demo app is built with Node and runs unit tests with Jest. The tests are run through the npm test script. Heroku CI allows you to configure more complicated CI setups using an app.json file, but in our case, because the test setup is fairly basic, Heroku CI can figure out which command to run without any additional configuration on our part. Pretty neat!

Enabling Review Apps

For the last part of our pipeline setup, let’s enable review apps. Review apps are temporary apps that get deployed for every pull request (PR) created in GitHub. They’re incredibly helpful when you want your code reviewer to review your changes manually. With a review app in place, the reviewer can simply open the review app rather than having to pull down the code onto their machine and run the app locally.

To enable review apps, click the “Enable Review Apps” button on the pipeline page.

Enable Review Apps

In the dialog that appears, check all three boxes.

The first box enables the automatic creation of review apps for each PR.
The second box ensures that CI must pass before the review app can be created.
The third box sets a time limit on how long a stale review app should exist until it is destroyed. Review apps use Heroku resources just like your regular apps, so you don’t want these temporary apps sitting around unused and costing you or your company more money.

When you’re done with your configuration, click “Enable Review Apps” to finalize your changes.

Configure your review apps

Seeing It All in Action

Alright, you made it! Let’s review what we’ve done so far.

We created a Heroku pipeline
We created a staging app and a production app for that pipeline
We enabled automatic deploys for our staging app
We enabled Heroku CI to run tests for every PR
We enabled Heroku review apps to be created for every PR

Now let’s see it all in action.

Create a PR in GitHub with any code change you’d like. I made a very minor UI change, updating the heading text from “Heroku Flow Demo” to “Heroku Flow Rules!”

Right after the PR is created, you’ll note that a new “check” gets created in GitHub for the Heroku CI pipeline.

GitHub PR check for the Heroku CI pipeline

You can view the test output back in Heroku on your “Tests” tab:

CI pipeline test output

After the CI pipeline passes, you’ll note another piece of info gets appended to your PR in GitHub. The review app gets deployed, and GitHub shows a link to the review app. Click the “View deployment” button, and you’ll see a temporary Heroku app with your code changes in it.

View deployment to see the review app

You can also find a link to the review app in your Heroku pipeline:

Review app found in the Heroku pipeline

Let’s assume that you’ve gotten a code review and that everything looks good. It’s time to merge your PR.

After you’ve merged your PR, look back at the Heroku pipeline. You’ll see that the staging app was automatically deployed since new code was committed to the main branch.

Staging app was automatically deployed

Click the “Promote to production” button on the staging app. This will open a dialog for you to confirm your action. Click “Promote” to confirm your changes.

Promote to production

After promoting the code, you’ll see the production app being deployed.

Production app was deployed

And with that, your changes are now in production for all of your users to enjoy. Nice work!

Updated demo app with new changes in production

Conclusion

What a journey we’ve been through! In this short time together, we’ve configured everything we need for an enterprise-ready CI/CD solution.

If you’d like to use a different CI/CD tool like GitLab CI/CD, GitHub Actions — or whatever else you may prefer — Heroku supports that as well.

But if you don’t want to reach for a third-party CI/CD provider, now you can do it all within Heroku with Heroku Flow.

Deploying Heroku Apps to Staging and Production Environments with GitLab CI/CD

Tyler Hawkins — Mon, 25 Mar 2024 12:30:52 +0000

In a previous article, we explored how to automate deployments to Heroku using GitLab CI/CD. That setup deployed the app to its production environment every time we pushed code to the main branch.

In this article, we’ll consider a slightly more nuanced approach: What if we have multiple environments? Most engineering organizations use at least three environments: a local development environment, a staging environment, and a production environment.

Additionally, some engineering teams follow a Gitflow branching strategy, where they have a dev branch and a main branch. This strategy has since fallen out of favor and been replaced by trunk-based development, but it’s not uncommon to find organizations still following this practice.

Today, we will look at how to configure GitLab CI/CD to deploy our app to our staging environment when we push to the dev branch and deploy our app to our production environment when we push to the main branch.

Getting Started

Before we begin, we’ll need two things: a Heroku account and a GitLab account.

Heroku is a great place to host and deploy your apps. As a platform as a service (PaaS), Heroku allows you to focus on building cool things while abstracting away much of the infrastructure complexity. You can create a Heroku account here.

GitLab is a great place to store your code. Beyond just being a source code management tool, GitLab also offers native CI/CD capabilities so you can set up pipelines to test and deploy your code without requiring another third-party tool. You can create a GitLab account here.

The demo app shown in this article uses both GitLab and Heroku. You can find all the code in the GitLab repo here.

Running Our App Locally

You can run the app locally by cloning the repo, installing dependencies, and running the start command. In your terminal, do the following:

$ git clone https://gitlab.com/tylerhawkins1/heroku-gitflow-staging-production-gitlab-cicd-demo.git
$ cd heroku-gitflow-staging-production-gitlab-cicd-demo
$ npm install
$ npm start

After starting the app, visit http://localhost:5001/ in your browser, and you’ll see the app running locally:

Demo Heroku app

Deploying Our App to Heroku

Now that the app is running locally, let’s deploy it to Heroku so that you can access it anywhere, not just on your machine.

Remember that we are going to deploy your app to both a staging environment and a production environment. That means that we’ll have two Heroku apps based on the same GitLab repo.

If you don’t already have the Heroku CLI installed on your machine, you’ll need to install that before moving on.

After installing the Heroku CLI, run the following commands from your terminal to check out the main branch, create a new production Heroku app, deploy it to your production environment, and open it in your browser:

$ git checkout main
$ heroku create heroku-gitlab-ci-cd-production --remote heroku-production
$ git push heroku-production main
$ heroku open --remote heroku-production

With that, you should see the same app, but this time running on a Heroku URL instead of on localhost. Nice work — you’ve deployed your Heroku app to production!

But, we’re not done yet. We also need to configure and deploy your staging app. To do this, run this similar set of commands shown below:

$ git checkout dev
$ heroku create heroku-gitlab-ci-cd-staging --remote heroku-staging
$ git push heroku-staging main
$ heroku open --remote heroku-staging

Now you’ll have the same app deployed again, but this time to a different URL that will serve as your staging environment. Now we have both of your environments configured!

Note the differences and similarities between the commands for the production app and the staging app:

The production app uses the main branch, and the staging app uses the dev branch.
The production app is called heroku-gitlab-ci-cd-production, and the staging app is called heroku-gitlab-ci-cd-staging.
The production app’s git remote is called heroku-production, and the staging app’s git remote is called heroku-staging.
Both the production app and the staging app’s git remotes use a main branch, since Heroku only deploys the app when code is pushed to its main branch.

Keep in mind that this main branch is different from your set of main and dev branches. The main branch that you’re pushing to here is the main branch on your git remote — in this case, Heroku.

So when you’re on your local main branch and run git push heroku-production main, you’re pushing your main branch to the Heroku production app’s main branch. And when you’re on your local dev branch and run git push heroku-staging main, you’re pushing your dev branch to the Heroku staging app’s main branch.

Making Changes to Our App

Now that we have our Heroku app up and running, what if we want to make some changes? Following a rough approximation of the Gitflow branching strategy, we could do the following:

Check out the dev branch
Make changes to the code
Add, commit, and push those changes to the dev branch
Deploy those changes to the staging Heroku app by running git push heroku-staging main
Check out the main branch
Merge the dev branch into the main branch
Deploy those changes to the production Heroku app by running git push heroku-production main

(If we were truly following Gitflow, we’d have created a feature branch to merge into dev, and a release branch to merge into main, but we’ve omitted those steps to keep things simple.)

Now, wouldn’t it be nice if we could automate the deployment to either of our environments instead of having to deploy them manually all the time?

This is where GitLab CI/CD comes into play.

Continuous Integration / Continuous Deployment

Continuous integration (CI) is all about committing often and keeping the build in a good state at all times. Typically you would verify that the build is in a good state by running checks in a CI pipeline. These checks might include linters, unit tests, and/or end-to-end tests.

Continuous deployment (CD) is all about deploying frequently. If the checks in the CI pipeline pass, then the build gets deployed. If the checks in the CI pipeline fail, then the build does not get deployed.

With GitLab CI/CD, we can configure our CI pipeline to do exactly this — run our tests and then deploy our app to Heroku if the tests all pass. Most importantly for our setup, we can configure rules within our CI pipeline to specify where the app should be deployed.

Configuring GitLab CI/CD

We can create a CI pipeline in GitLab programmatically using a .gitlab-ci.yml file. Our file looks like this:

image: node:20.10.0

cache:
  paths:
    - node_modules/

before_script:
  - node -v
  - npm install

stages:
  - test
  - deploy

unit-test-job:
  stage: test
  script:
    - npm test

deploy-job:
  stage: deploy
  variables:
    HEROKU_APP_NAME: $HEROKU_APP_NAME_PRODUCTION
  rules:
    - if: $CI_COMMIT_REF_NAME == $CI_DEFAULT_BRANCH
      variables:
        HEROKU_APP_NAME: $HEROKU_APP_NAME_PRODUCTION
    - if: $CI_COMMIT_REF_NAME =~ /dev/
      variables:
        HEROKU_APP_NAME: $HEROKU_APP_NAME_STAGING
  script:
    - apt-get update -yq
    - apt-get install -y ruby-dev
    - gem install dpl
    - dpl --provider=heroku --app=$HEROKU_APP_NAME --api-key=$HEROKU_API_KEY

GitLab CI pipelines consist of stages and jobs. Each stage can contain one or more jobs. In our pipeline, we have two stages: test and deploy. In the test stage, we run our unit tests in the unit-test-job. In the deploy stage, we deploy our app to Heroku in the deploy-job.

We can only progress to the next stage if all the jobs in the previous stage pass. That means if the unit tests fail, then the app won’t be deployed, which is a good thing! We wouldn’t want to deploy our app if it was in a bad state.

You’ll note that the deploy stage has a rules section with some conditional logic in place. This is where we specify to which environment our app should be deployed. If we’re on the main branch, then we deploy our production app. If we’re on the dev branch, then we deploy our staging app.

You’ll also note that the deploy stage references several variables called $HEROKU_APP_NAME_PRODUCTION, $HEROKU_APP_NAME_STAGING, and $HEROKU_API_KEY. These are stored as CI/CD variables within GitLab.

If you’re setting this up in your own GitLab account, you’ll need to first find your API key in your Heroku account. Within your Heroku account settings, you should see a section for your API key. If you haven’t generated an API key yet, generate one now.

Heroku API key

Next, in your GitLab project, click on Settings > CI/CD > Variables. Expand that section and add three new variables:

The value for $HEROKU_API_KEY will be the API key from your Heroku account.
The value for $HEROKU_APP_NAME_PRODUCTION will be the name of your production Heroku app. My production app’s name is heroku-gitlab-ci-cd-production, but since Heroku app names are universally unique, yours will be something different.
The value for $HEROKU_APP_NAME_STAGING will be the name of your staging Heroku app. My staging app’s name is heroku-gitlab-ci-cd-staging. Again, since Heroku app names are universally unique, yours will be something different.

GitLab CI/CD variables

With that, your GitLab CI pipeline is ready to go! Let’s test it out.

Deploying Our Heroku App to the Staging Environment

Let’s check out the dev branch and make a change to the code in our app. I made a simple change to the heading text and added several new lines to the text in the UI. You can make a similar change in your code.

Now add, commit, and push that change to the dev branch. This will start the GitLab CI pipeline. You can view the pipeline within GitLab and see the progress in real time.

GitLab CI pipeline build for the dev branch

If everything goes well, you should see that both the test and deploy stages have passed. Now, go check out your hosted Heroku app at the staging environment URL. The GitLab CI pipeline took care of deploying the app for you, so you’ll now see your changes live in the staging environment!

Demo Heroku app with updated copy

With a staging environment set up, you now have a great place to manually test your code in a hosted environment. This is also a perfect spot for having QA testers or product managers verify changes before they go to production.

Now, check out your production app URL. You’ll note that it’s still showing the old UI without the most recent changes. This is because the GitLab CI pipeline only deployed the changes to the staging environment, not the production environment.

We’ve verified that the code looks good in our staging environment, so let’s promote it to our production environment.

Deploying Our Heroku App to the Production Environment

Let’s check out the main branch and then merge the dev branch into your main branch. You could do this through a pull request or by running git merge dev and then git push.

This will start the GitLab CI pipeline once again, but this time it will be preparing to deploy your production app.

GitLab CI pipeline build for the main branch

You can also view all the pipeline runs on the Pipelines page in GitLab to see the various builds for your dev and main branches:

All GitLab CI pipeline builds

Once the pipeline finishes, visit the URL for your production Heroku app. You should now see your changes also deployed in production. Great work!

Conclusion

A good CI pipeline allows you to ship new features quickly and confidently without manually managing the deployment process. Having multiple environments configured for local development, staging, and production gives you more control over where and when code is released.

Heroku and GitLab CI/CD allow you to automate all of this to make your DevOps processes a breeze!