Yesterday, I decided to make some "quick" changes to the OpenSauced docs site. Now, I know that "quick changes" is essentially a bad word in tech. Anytime you say it, it will indeed not be quick. I wrote up a quick issue that described reorganizing a couple of things and adding a quick intro page. I made the changes, wrote the page, pushed my changes, and made the Pull Request (PR), only to see that I failed. Ugh. It was quick, but it wasn't right. Not really having the time to dig into it, I left my PR open and determined to get back to it the next day. Understanding why a project is failing may look different depending on how it is set up. For us, we're going to look at implementation errors, compliance issues, check the deploy log.

Checking Locally

The first step to make sure your PR hasn't broken anything is to run the project locally and visually check the pages of the changes you've made. Initially, I had forgotten to include a set of --- at the top of my markdown file. This is necessary to separate the frontmatter that gives directions to how to display the documentation from the words we want displayed on the page.

This is what the file should look like at the top.

---
id: opensauced-intro
title: 'What is OpenSauced?'
sidebar_label: 'What is OpenSauced?'
keywords:
  - OpenSauced
---

# OpenSauced: Your Open Source Partner

OpenSauced is a platform dedicated to nurturing and expanding your open source community, while recognizing every contributor's impact.

Notice that the sidebar_label is 'What is OpenSauced?' Now, let's take a look at how this rendered when I was missing the ---:

There are two things that should clue us into the mistake I made here:

1. The sidebar doesn't use the title we designated.
2. We see all the frontmatter at the top, and we shouldn't.

I added the --- back in and it fixed the first problem.

But even though we ran things locally and double-checked our work visually, made the updates, and pushed them live, we're still seeing errors.

On to the next check: Compliance.

Compliance

At OpenSauced, we make sure that each PR follows compliance checks run by a GitHub Action. This compliance action helps us to maintain the quality and organization of contributions to the repository by ensuring that pull requests follow semantic naming conventions and adhere to contribution guidelines.

For example, we use conventional commits, which requires a specific naming convention. This means that each PR title should be preceded by a type and colon. For example, feat: Add User Login. If you don't follow the conventions, this part of the PR will fail and will be indicated.

Once I made sure that my compliance checks had passed, I moved on to the Netlify deploy logs.

Netlify Deploy Logs

Even from the list view, we can tell that something isn't working with this PR.

When I scroll to the bottom of my PR, I can see more information about where my PR has failed. In this case, we can see the red early.

From there, we can click the details for more information.

Now, let's click the link in "Please check the logs."

Next, we'll see this screen:

We're almost to the information we need. We're failing at the building stage, so open that tab to see the error messages.

Finally! Now, we just need to spend a little time looking through the messages. I'm going to give you a second to look at the error message and see if you can figure it out.

🤔

🤔

🤔

🤔

🤔

If you said that the links are broken, then you're right! When I reorganized the documentation, I forgot that I also needed to update the links to the new sections. A couple of changes to this, and we're ready to go.

Some of these are things that you might already know, but maybe you've never gone through the process of checking deploy logs or aren't sure how to approach fixing a broken PR. Here's the thing, it used to make me super uncomfortable to see all that red and to feel like I did something wrong. I made some mistakes here, but nothing that isn't fixable. And getting used to the process of not getting it right the first time is an important skill in tech. You refine your process and you get more efficient. So, next time you see that red ❌, don't panic. Think of it as an opportunity to learn and a reminder for what you can do next time.