Navigating GitHub Actions

To navigate to the actions tab, click on the 'Actions' tab circled near the top of the page.

1. This is the box that contains all of the Actions workflows that have been run, will be run, or are running for a particular repository. There are four different workflows that Adafruit CircuitPython libraries use. Workflows are a series of tests run to determine if a PR, commit, or release is up to the desired standards and is correctly working. Unless you're releasing libraries, you'll only need to worry about the 'Build CI' workflow.
2. This icon tells you the status of the workflow. A green check means it has run successfully. A red X means it has failed, and an orange circle means it is either waiting to run or currently running.
3. This menu allows you to filter by Workflow. The first three workflows are run upon release, and mostly deal with packaging and deploying the newest version of the library. The fourth one is run when a commit or PR is made and checks formatting and documentation.
4. You can click on the bolded title to the left of number 4 to see the readout from the workflow.

When your PR fails

As soon as you open a PR, you should see a box with an orange border. It will tell you the status of you PR. While the workflow is running, it will say "Some checks haven't completed yet."

The Actions CI often takes around a minute to run, but depending on the amount of workflows currently being run, and the size of the repository, it could be longer or shorter. Below, you can see that the PR is currently failing actions. To find out what specific test it is failing, you can click on one of four places. First, you can click on the red X to the left of the commit hash. Second, you can click on the red X to the left of the GitHub logo in the orange box. You can also click on details, on the same line as the previous but all the way to the right. Finally, you can click on the 'Actions' tab at the top of the page. This works but it isn't ideal as you'll have to navigate to the test for your PR.

Now that you're on the Actions page for that specific commit, you can find out what test is causing it to fail. There are three tests a PR will fail on: black formatting (check formatting), PyLint, and Build Docs. In this case, the Black formatting check is failing.

Fixing a Black formatting failure is actually very easy. Check out the Black page in this guide for info on running Black. Then commit and push your changes.

Now that we've ran Black, and committed and pushed those changes, we can check back in with the PR. It's still failing, so we can navigate to the Actions page again.

It looks like the Black formatting check is now passing, but Pylint isn't. You can find out how to use Pylint in the Pylint page in this guide.

Now, run Pylint in the your repository's base directory. Make the changes it says to make and re-run Pylint until it says that your code is rated a 10/10. Then, commit and push those changes.

The PR is still failing, so we should check the Actions workflow output again.

The good news is that the Pylint check is no longer failing. However, it appears that sphinx is failing. Click on the 'Build Docs' dropdown to see that test's output. It looks like I inadvertently removed some necessary colons. 

By going into the docs directory, and building sphinx documentation like in the Sharing Docs on ReadTheDocs page in this guide, we can mirror the output of the 'Build Docs' test. In this case, the issue is in index.rst. After fixing those issues, run the command again to verify that the docs are building correctly. In this case, they are, so we can commit and push those changes.

Now that everything is passing and the box has a green border, the PR is ready for review.