DEV Community: Michael Uloth

Undoing a Merge to Your Main Git Branch

Michael Uloth — Wed, 20 Dec 2023 00:00:00 +0000

You merge your PR only to discover you accidentally missed a bug and now prod is broken. Gah! Is there a quick way to undo that merge?

Yes! What you need to do is “revert” your PR. Here’s how to do that using the GitHub UI.

Reverting a PR

In the browser, go to your merged PR
Click the “Revert” button near the bottom of the page to automatically create a new revert- branch that reverses your changes
When prompted, open a PR for that revert- branch
Merge the PR

That’s it. 😀 Crisis averted. Your main branch is back how it was before you merged your feature.

Restoring your original feature branch

If you want to debug and re-open an improved version of your original PR, here’s what you need to do:

Click the “Revert” button at the bottom of the reversion PR you just merged to create a new revert-revert- branch that includes the same changes as your original feature branch (by reverting the changes that reverted them)
Pull that revert-revert- branch locally (don’t open a PR yet) and make any changes you like to this new copy of your feature branch (not your old one!)
When ready, push your changes and open a new PR for the revert-revert- branch that contains the repaired version of your feature
Merge when ready

Reverting a commit

So far, these steps have assumed the change that broke prod came from a PR. But what if you committed directly to main?

That’s a simpler fix. You’ll just need to revert that bad commit (no PR required):

git checkout main
git log # find the hash of your bad commit ("q" to exit)
git revert HASH
git log # admire your new "Revert X" commit (optional)
git push

Or using Lazygit:

Go to the Branches panel and check out main
Go to the Commits panel and highlight the bad commit
Press t to revert your commit (you’ll see a new commit appear reversing your bad one)
Press P to push the new commit to your remote branch

Try, try again

These steps have helped me out of multiple “oh 💩” moments at work. I hope they help you too!

Reverting your reversion may seem a bit strange the first time you try it, but hopefully it will make sense as you think about it. 🙂

Switching Configs in Neovim

Michael Uloth — Thu, 07 Sep 2023 00:00:00 +0000

Learning how to configure Neovim can be overwhelming. One way to get started is to install a few pre-built configurations (like LazyVim, NvChad, AstroNvim, LunarVim or the official Neovim Kickstart) and see what you like.

Most installation instructions will tell you to replace everything in your ~/.config/nvim directory with the new configuration. But once you do, you lose the ability to launch Neovim with your previous config.

With that approach, you can only have one Neovim config installed at a time.

But what if you want to compare two configs? Or maintain different configs for different purposes (e.g. one for work and one for personal projects)?

Install each config in its own directory

To be able to use more than one config, you'll need to make a couple changes to your setup:

Instead of installing a new configuration in ~/.config/nvim, install it in a custom ~/.config subdirectory
Each time you open Neovim, specify which config you want by setting the NVIM_APPNAME environment variable in your launch command

For example, assuming you've installed LazyVim in ~/.config/nvim-lazyvim, you'd launch it with this command:

$ NVIM_APPNAME=nvim-lazyvim nvim

Neovim uses NVIM_APPNAME to determine which config directory to load. If you don't include it (or set it to an invalid value), Neovim will use the default config in ~/.config/nvim.

Switching configs using `alias`, `select` or `fzf`

Lets assume your ~/.config directory includes these subdirectories:

~/.config
├── nvim-astrovim
│ └── init.lua
├── nvim-kickstart
│ ├── init.lua
│ └── lua
│ ├── custom
│ └── kickstart
├── nvim-lazyvim
│ ├── init.lua
│ └── lua
│ ├── config
│ └── plugins
├── nvim-lunarvim
│ └── config.lua
└── nvim-nvchad
│ ├── init.lua
│ └── lua
│ ├── core
│ ├── custom
│ └── plugins
└── nvim

To quickly open Neovim using each config, you could create an alias for each launch command:

alias v='nvim' # default Neovim config
alias vz='NVIM_APPNAME=nvim-lazyvim nvim' # LazyVim
alias vc='NVIM_APPNAME=nvim-nvchad nvim' # NvChad
alias vk='NVIM_APPNAME=nvim-kickstart nvim' # Kickstart
alias va='NVIM_APPNAME=nvim-astrovim nvim' # AstroVim
alias vl='NVIM_APPNAME=nvim-lunarvim nvim' # LunarVim

Or use select to list your configs so you can choose one:

vv() {
  select config in lazyvim kickstart nvchad astrovim lunarvim
  do NVIM_APPNAME=nvim-$config nvim; break; done
}

Which would produce a menu like this:

Or you could get fancy and use a fuzzy finder like fzf to do the same thing:

vv() {
  # Assumes all configs exist in directories named ~/.config/nvim-*
  local config=$(fd --max-depth 1 --glob 'nvim-*' ~/.config | fzf --prompt="Neovim Configs > " --height=~50% --layout=reverse --border --exit-0)

  # If I exit fzf without selecting a config, don't open Neovim
  [[ -z $config ]] && echo "No config selected" && return

  # Open Neovim with the selected config
  NVIM_APPNAME=$(basename $config) nvim
}

Here's what that fzf menu would look like:

Conclusion

Configuring Neovim can be daunting, but being able to install a few configs and compare them is a great way to gather inspiration for your own custom config.

Good luck!

Adding a Pull Request Template to Your GitHub Repo

Michael Uloth — Thu, 15 Dec 2022 00:00:00 +0000

If you spend time wondering what to write in the blank “Description” field every time you open a pull request, adding a PR template to your repo will speed you up.

By pre-filling that “Description” field with a few quick prompts to answer, you’ll always know what to write and your reviewers will always get the info they need.

How to add a PR template

Create a folder called .github at the root of your repo
Create a file called .github/pull_request_template.md
Use GitHub’s Markdown syntax to add any prompts you think will be useful to that file

That’s it! Each time you open a pull request, the description section will now be pre-filled with your template.

What to include in your template?

Feel free to add any prompts you like! I prefer to keep it simple:

## ✅ What

<!-- A brief description of the changes in this PR. -->

## 🤔 Why

<!-- A brief description of the reason for these changes. -->

## 👩‍🔬 How to validate

<!-- Step-by-step instructions for how reviewers can verify these changes work as expected. -->

## 🔖 Related links

- [Jira task](<!-- link -->)
- [Slack thread](<!-- link -->)

(The comments are only visible while editing.)

Don’t overdo it

Whatever you do, don’t make your PR template too long. If you notice your team generally skips certain prompts, don’t hesitate to remove them.

Only include prompts that actually save everyone time. If your reviewers consistently ask which ticket your PRs relate to, adding a ticket link prompt to the template is probably a good idea. But adding 50 well-intentioned checkboxes will only cause your team to skip the template entirely.

So, keep it short. 😊

Dramatically Reducing Video File Size Using FFmpeg

Michael Uloth — Thu, 10 Nov 2022 00:00:00 +0000

Sometimes you want to upload a video, but you can’t because its file size is too large. When that happens, you can use ffmpeg to shrink the video size with one command.

Steps to shrink a video file

If you’re on a Mac and haven’t already, install Homebrew:
Install ffmpeg using Homebrew (or download ffmpeg for your OS):
Run ffmpeg on your file:

That’s it — I was able to shrink a 10-minute macOS screencast from 1.4 GB to 148 MB just by running that command and waiting 6 minutes.

Where to go from here

This approach works best when your final video quality doesn’t need to be very high.

If you’re creating high-resolution content, you’ll want to dive deeper into ffmpeg’s configuration options or use a tool like Handbrake to help you select the quality you need.

The translateZ trick

Michael Uloth — Thu, 01 Sep 2022 00:00:00 +0000

CSS filters are great

CSS filters are super cool. They can take something that looks like this…

…and make it look like this:

Love it. Effects like these are the fun part of writing CSS.

And blur() is just one of many fun filter options. The rest are listed here.

CSS filters become especially useful when you need to animate items on and off the page, or in and out of the foreground. For example, you may want to blur an item more and more as it animates off the page. Or when a user opens a modal, you may want to gradually blur the page behind it to direct the user’s attention to the modal content.

Safari woes

Unfortunately, once you start animating the CSS filter property, you’re going to notice your animation is awfully choppy in Safari.

I ran into this issue at work a couple years ago while animating CSS filters. And I recently heard Scott Tolinski lament on Twitter and the Syntax podcast that he was excited about using CSS filters but was forced to abandon them because of this Safari rendering issue.

But there’s a fix! That’s why I’m writing this post, if only to help Scotty. 😎

The fix

To fix the issue in Safari, take this…

.thing {
  filter: blur(4px);
  transition: filter 0.3s ease-in-out;
}

…and change it to this:

.thing {
  filter: blur(4px);
  transition: filter 0.3s ease-in-out;
  transform: translateZ(0); /* the fix */
}

That’s it. Your animations will run smoothly in Safari now.

How does translateZ help?

The basic reason translateZ(ANY_VALUE) makes the animations run smoothly is that it tells Safari to render the animation using the GPU instead of the CPU.

Without translateZ (or a similar hint), Safari will try to animate your filter using the CPU, which isn’t nearly as able to render complicated graphics. For graphics-intensive tasks like animating a filter effect, the GPU will always do a much better job.

Help us out, Safari

Chrome and other non-Safari browsers automatically hardware-accelerate animations like this by engaging the GPU, but Safari still requires you to add specific properties like translateZ to get the same result.

Hopefully the Safari team will fix that soon so Scott can animate all the cool CSS features he likes without resorting workarounds like this one.

Until then, translateZ is your friend.

What is a Factory Function?

Michael Uloth — Sun, 27 Feb 2022 00:00:00 +0000

I hadn’t heard of the factory function technique until I read What is a Factory Function? by Kyle Shevlin:

A factory function is a function that returns a new object. The key feature of a factory is that its only job is to pump out those items, just like an actual factory.

The place I use factories most often is when I want to return an object with methods but use closures to create private methods and values. Even better, I never have to even think about the this keyword.

In other words, you can write them instead of classes!

I found a good use case for this technique today while adding extra properties and helper methods to blocks I’d fetched from the Notion API, so I wanted to give Kyle a shout-out for the timely assist.

Check out Kyle’s blog for lots of other interesting coding tips.

Writing Great Alt Text

Michael Uloth — Thu, 17 Feb 2022 00:00:00 +0000

I agree with Jake Archibald's argument in Writing great alt text: Emotion matters that when we write image alt text, we should aim to evoke the same emotions as the image visuals do. Otherwise, screen reader users miss out.

If an image makes you laugh or cry, ideally the alt text will do the same:

The relevant parts of an image aren't limited to the cold hard facts. Images can make you feel a particular way, and that's something that should be made available to a screen reader user.

It isn't just a head-shot of me. I'm doing a thing. I'm peering from behind a plant and pulling a bit of a silly face. There's humour expressed in the image. I'm not saying that it's going to win any comedy awards, but the image expresses a particular tone, and that matters. So, it should go in the alt: “Head-shot of me, a pale white guy, wearing glasses, grinning slightly, and partially hiding behind a plant”.

Let the creative writing begin!

Levels of Abstraction in Testing

Michael Uloth — Tue, 15 Feb 2022 00:00:00 +0000

Sam Selikoff's Levels of abstraction in testing does a nice job demonstrating how to make unit tests easier to read by abstracting the low level setup steps at the beginning of each test into a well-named function.

After that change, the everything in the tests reads at a single level of abstraction (namely, how would a user interact with this component?) rather than alternating between what the computer is doing and what the user is doing. The result is easier to understand.

Basically, you just want to act as if you’re sitting next to the person who is using the system you’re testing…just imagine how you’d explain to them what behaviour you’re testing and then write your tests using similar words.

I think this advice would apply just as well to non-test code. If you notice a code block mixes levels of abstraction, try extracting the lower level bits so the resulting code reads as a continuous train of thought from a single point of view.

Check out Sam's complete video:

How ecobee Uses Slack to Report Data Entry Errors to Content Editors

Michael Uloth — Mon, 31 May 2021 00:00:00 +0000

This post originally appeared on the ecobee engineering blog.

My team at ecobee spent months debugging build failures on the staging site for ecobee.com until we finally discovered a way to solve them with automated Slack notifications.

Production vs. staging

ecobee.com is an e-commerce website, which we populate with content from Contentful and Shopify.

Our designers and writers create new pages by building and assembling “blocks” of content in Contentful. As they work, they can preview their changes on a staging version of our site.

Here’s the live version of ecobee.com:

And here’s the staging version of ecobee.com:

The staging version looks very similar to the live version because, well, that’s the point. It’s generated using the exact same codebase as the live site and all the content for both versions of the site come from Contentful.

If you aren't familiar, here’s what Contentful looks like:

This example is the “Page” entry that creates the homepage for ecobee.com. It’s basically a series of fields: some are required; some are not.

If you mark a field as required, Contentful will confirm that field is populated before it lets you publish the entry. (The same applies to other field validations like max length, number vs. text, etc.) And because the live site only consumes published entries, we know all the fields have been validated (e.g. no required fields are empty), and the data the website receives will match what we expect.

So far, so good.

However, the staging site is a little different: it connects to the same production Contentful data as the live site, but also includes any draft entries that have not yet been published.

That’s by design, so that editors can preview their in-progress changes on staging as they go.

But those draft entries have one major problem: their fields have not been validated.

Broken staging builds

The challenge we faced was that we kept seeing errors like this:

This the deploy log for a build of our staging website on Netlify. And over and over, we encountered errors saying Cannot read property X of null or Cannot read property X of undefined, which indicated that our codebase trusted a value existed (because its Contentful field was required) and tried to use it, but failed because that value was unexpectedly empty.

So, why didn’t Contentful make sure those required fields were populated?

Draft entries cannot be trusted

The basic reason is that unpublished draft entries (which staging consumes) are not validated by Contentful because Contentful only applies validations when an entry is published.

So, while our production builds were stable (since the live site only consumes validated, published entries), our staging builds were constantly exposed to the risk that a field coming from a draft entry could contain invalid data (or no data at all).

This issue was minor when our team only had one or two content editors. But as our team grew to include half a dozen or more editors working separately and constantly triggering new builds, incomplete data began to be hit staging on a daily basis.

Debugging in the dark

When one of these errors occurred, the staging website would stop updating, and one or more devs would have to put aside their work and jump into the build logs to locate an error like the one shown above.

Next came the hard part: trying to figure out which field in Contentful was responsible for the problem.

For example, all the error in the screenshot above says is that the Link component was passed an empty href. It doesn’t say which field in Contentful that empty value came from.

Trying to track down those empty fields was no fun. Each hunt took up a lot of time and involved a lot of head scratching and rooting through Contentful, searching for the root of each problem. Work ground to a halt for editors and developers while we hunted, sometimes for up to an hour.

We were to determined to free ourselves from these thankless debugging sessions.

Custom null checks everywhere

To do that, we started adding defensive null checks all over our codebase.

Even though we didn’t have to worry about the existence of required values in production, for the sake of our editors having a working preview site to look at, we realized we needed to treat required fields as unreliable and start guarding against their lack of existence.

So, we started adding things like this all over our codebase that intercepted empty values and identified exactly which Contentful field to fix:

const ReviewsResolver = ({
  data: { productReference, header, name = '' },
}: BlockResolverProps<ReviewsDataType>) => {
  const logError = useLogError()

  if (!productReference) {
    logError(
      `The Reviews entry named "${name}" cannot be displayed because its required field "Product reference" is empty.`,
    )

    return null
  }

  return <Reviews product={productReference} />
}

Slack to the rescue

We also created a helper, called logError, to decide whether each error message should appear just in the console or also be posted to Slack:

// If this is prod, report the issue and break the build
if (context === 'PRODUCTION') {
  const prodImpact = 'The live site will not update until this issue is resolved.'

  const prodMessage = formatMessage(`🚨 PRODUCTION ERROR 🚨\n\n${message}\n\n${prodImpact}`)

  postToSlack(prodMessage).then(() => {
    throw new Error(prodMessage)
  })
}

// If this is staging, report the issue and continue the build
if (context === 'STAGING') {
  const stagingImpact = 'The staging site will continue to update while this issue gets resolved.'

  const stagingMessage = formatMessage(`⚠️ STAGING ERROR ⚠️\n\n${message}\n\n${stagingImpact}`)

  postToSlack(stagingMessage)
  console.error(stagingMessage)

  return
}

// In all other environments, just log the issue and continue the build
console.error(formatMessage(`\n\n⚠️ ${message}\n\n`))

So, we ask, “Are we on the production site? Or staging? Or just in development?”, and based on the answer we decide if we should to stop the build (production only) and/or post the error to Slack (production and staging only). In all environments, we also log the error to the console.

We then created a dedicated Slack channel and invited all our editors to it, created a Slack bot, and used the Slack Web API to automatically post these Slack messages for us:

import type { WebClient } from '@slack/web-api'

import { isTest } from '../../src/utils/getEnv'

const isSSR = typeof window === 'undefined'

async function postToSlack(text: string, channel = '#dotcom-cms-errors') {
  // Only post during a build that isn't part of a test run
  if (!isSSR || isTest || !global.slackClient) {
    return
  }

  try {
    await global.slackClient.chat.postMessage({ channel, text })
  } catch (error) {
    console.error(`\n[postToSlack]: ${error}\n`)
  }
}

Now, whenever a build error occurs and is caused by a Contentful data entry problem we know about, the message goes straight to that editor-focused channel so they can can hop into Contentful and fix the issue without dev assistance:

An endless process

But, we weren’t done.

We started noticing that after we had fixed the 10 or so errors we had seen over and over, there were 10 or so new ones that we hadn’t previously seen because they never had a chance to appear because the other errors were happening first.

It slowly dawned on us that with our current approach of inserting custom null checks and error messages in individual components, this problem would never end. We’d have to null check every single value we considered required and continue doing that whenever we wrote new code.

That was not going to be scalable for us in the future.

Automated validation step

So, we came up with a better idea.

To avoid having to spread null checks all over our codebase and worry about this forever, early in our build we now query all of the data from Contentful that our website will use along with the rules for every field, and then compare the two.

We take each field and its rules and pass it to a function that asks if it’s invalid. For example, for requiredness, we check if the field’s rules say it’s required and if its value is empty. If both are true at the same time, the field is invalid:

function isEmptyRequiredField(fieldRules: ContentFields, fieldValue: unknown) {
  const isRequired = 'required' in fieldRules && !!fieldRules.required

  // We don't want to check falsiness here, since that would flag fields intentionally set to 0
  const isEmpty = fieldValue == null

  return isRequired && isEmpty
}

function detectFieldInvalidity(
  rules: ContentTypeIdsAndFields,
  contentTypeId: string,
  fieldName: string,
  fieldValue: unknown,
): string | null {
  const fieldRules = getFieldRules(rules, contentTypeId, fieldName)

  if (isEmptyRequiredField(fieldRules, fieldValue)) {
    return 'is required but empty'
  }

  if (isInvalidRichTextField(fieldValue)) {
    return 'contains invalid HTML'
  }

  return null
}

Then, we have a single place where we call our logError helper as many times as necessary:

const isInvalidReason = detectFieldInvalidity(rules, contentTypeId, fieldName, entry[fieldName])

if (isInvalidReason) {
  const contentTypeName = startCase(contentTypeId)

  const entryName = entry?.name || entry?.title || ''

  const contentTypeAndEntryName = entryName
    ? `The Contentful ${contentTypeName} entry named "${entryName}"`
    : `An unnamed Contentful ${contentTypeName} entry with entry ID "${entry.contentful_id}"`

  const locale = entry?.node_locale
    ? (String(entry.node_locale).toLowerCase() as 'en-us' | 'en-ca')
    : undefined

  const message = `${contentTypeAndEntryName} cannot be displayed because its field "${fieldName}" ${isInvalidReason}.\n\nPlease update this field and publish your changes.`

  logError(message, locale, entry.contentful_id)
}

The updated version of these Slack error notifications looks like this:

The updated template tells editors the name of the broken Contentful entry, which field in the entry has the problem, what the problem is, how to fix it, a link to the entry, and context about the environment where the build error occurred.

Happy editors and developers

We've been living with this solution for the past few months and our editors and developers are both much happier!

There are no more confusing debugging sessions. Whenever a staging build breaks, the solution is posted to Slack a second later and an editor can fix it themselves within a minute.

This has eliminated an annoying source context switching and restored hours of developer and editor productivity each week.

Please share your ideas!

So, that’s how the "dotcom" team at ecobee is currently tackling the challenge of using the same codebase for production and staging but sending that codebase different data in each environment.

If you’ve encountered this issue before and have tips or best practices that might help us, please let us know! We realize this is likely a common problem for sites with a content management system, so we’d love to hear how you approached solving this issue.

The filter(Boolean) trick

Michael Uloth — Tue, 02 Jun 2020 13:06:08 +0000

Here’s a trick I often find helpful.

Bad array. Very, very bad.

You have an array of whatever:

const array = [{ stuff }, { moreStuff }, ...]

But hiding in that array are some unusable null or undefined values:

const array = [{ good }, null, { great }, undefined]

Those empty values might be a sneaky little gift from your API. Or you may have left them there yourself while validating the original data. Either way, you’ve got a problem.

Looping over null data

If you try to perform actions on every item in the array, you’ll run into errors when you hit those null and undefined items:

const newArray = array.map(item => {
  // Of course this will work, wheeee...
  const assumption = item.thing
})

// Oh noooo...
🚨 Cannot read property "thing" of undefined. 🚨
🚨 Cannot read property "thing" of null. 🚨

Illegal! Now you’re a criminal. Before you interact with an item, you need to make sure it exists.

Null checks?

You could confirm each item exists by performing a null check before you use it:

const newArray = array.map(item => {
  // Life has made me cautious.
  if (!item) {
    return item // Just forget it
  }

  // If we get this far, item exists.
  const assumption = item.thing
})

Buuut, now your code is getting cluttered. And worse, those dangerous empty values will be passed along to newArray. So when newArray is used, another round of suspicious null checks will be needed.

The truth and only the truth

Want something better?

Here’s my favourite way to quickly remove all empty items from an array:

const array = [{ good }, null, { great }, undefined]

const truthyArray = array.filter(Boolean)
// truthyArray = [{ good }, { great }]

The filter(Boolean) step does the following:

Passes each item in the array to the Boolean() object
The Boolean() object coerces each item to true or false depending on whether it’s truthy or falsy
If the item is truthy, we keep it

Where did item go?

I love how concise filter(Boolean) is, but it might look strange that we aren’t explicitly passing item to Boolean.

The main thing to know is that, in JavaScript, this:

array.filter(item => Boolean(item))

is exactly the same as this:

array.filter(Boolean)

The second version is just written in a “tacit” or “point-free” style. We don’t name each item and pass it into Boolean, but JavaScript understands that Boolean takes one argument, so it takes the argument filter() exposes and passes it to Boolean for you.

If you find the first version easier to understand, use it! Writing readable code is more important than using fancy tricks.

Safer mapping

With our new tool, we can remove the null checks from above and chain a filtering step instead:

const newArray = array.filter(Boolean).map(item => {
  // Item is always truthy!
  const assumption = item.thing
})

Now, our map can focus on what it’s trying to do, and we’ve removed the empty values from our pipeline forever.

Hope that helps!

Glossary

Falsy values: false, 0, -0, 0n, "", null, undefined, NaN
Truthy values: anything not in the falsy list

Using GraphQL with Gatsby

Michael Uloth — Mon, 03 Jun 2019 00:00:00 +0000

This is the tenth video in our beginner series exploring GatsbyJS and how to use it to easily build performant apps and websites.

In this video, we explore how GraphQL works and practice using it with Gatsby to query our content.

Check out the video below or view the entire playlist on YouTube.

Enjoy! 🎉📺

Adding Content to a Gatsby Project

Michael Uloth — Mon, 27 May 2019 00:00:00 +0000

This is the ninth video in our beginner series exploring GatsbyJS and how to use it to easily build performant apps and websites.

In this video, we explore a few ways we can add content to a Gatsby project and discuss the advantages and disadvantages of each approach.