Now you've created your pull request and you're ready to continue the process. This section shows you how to ensure your PR is ready for review. It details the important features of your new PR. It covers how to read the logs generated by the check system, and deal with the built in code checks failing. Finally, you'll learn how to submit code to an active PR.
An important part of software development is ensuring your code is consistent. CircuitPython, like any open source project you might contribute to, has expectations and standards, and if you want your contribution to be accepted, you'll need to work within them. Our responsibility in this is to clearly communicate our expectations, and provide you with the tools necessary to guarantee your code complies. To that end, the CircuitPython libraries all have a series of checks to verify that your code fits with our standards.
Adafruit uses a GitHub tool called Actions. For CircuitPython libraries, it is used to check a number of things including:
- Are there any syntax issues with the code?
- Is the code style as expected?
- Is the code formatted properly?
- Does the code include an appropriate license and attribution?
- Does the documentation build?
These things help us by automating a significant part of the review process by ensuring that the basic standards are being met. It means the folks reviewing can spend more time in the review process working directly with you on your contribution, instead of taking the time to verify these requirements.
The fact is, you're going to run into these checks failing, no matter how many times you go over your code before submitting. So, it's important to be able to read the log generated by Actions. You'll be able to understand what the failures mean, and use the log to more effectively resolve the issues in your contribution.
Welcome to your pull request! Once you've clicked the Create pull request button, it will automatically take you to your newly created PR.
The main page is going to look something like the following. There's a lot going on here! By the time you're done with this section, you'll be familiar with all the important features of your PR. Let's take a look!
The PR header begins with the PR title, and the number assigned to it when it was created. My PR is #13. Below that is a quick view of whether the PR is open, closed or merged; it is currently Open. Next to the status, is the current PR content summed up in a human-readable sentence.
The bottom of the header has four tabs: Conversation, Commits, Checks, and Files changed. The tabs you'll spend the most time in are Conversation and Files changed.
At the bottom right of the header are some red and green numbers and blocks. The green shows you the number of additions to the code in your contribution, and the red shows you the number of deletions. If you add more changes to your PR, these numbers will update to match the overall statistics. They're not particularly important, but they are fun!
The first thing in the Conversation tab is your PR comment. You'll see your profile picture, your name, and when the comment was added. I clicked create a moment ago, so it's showing that I "commented now".
Below your comment is the list of commits currently included in this PR. You'll see who added the commits and when. Each entry in the list begins with the profile picture of the commit author, followed by the commit title, and on the far right, the last seven characters of the commit hash.
As you can see, I made the changes quite a while before I created this PR.
Below the commit list is the PR status. This section reflects the current status of the PR at any given time. This is different from the open status reflected in the header. This status tells you what condition the PR is in, whether checks are running or changes have been requested. You can always check here to see where things are at.
There are many statuses. If you scroll down as soon as you create the PR, you'll see the initial status, which is, "Checking for ability to merge automatically..." A PR can be merged automatically if there are no changes in the PR that conflict with the existing code.
It there are no issues, the next status will be, "This branch has no conflicts with the base branch".
If there were issues, you would have been notified during PR creation, and given the opportunity to resolve them before creating your PR.
You may also see the following on certain repos that have merge restrictions enabled. These are usually highly utilised libraries where changes must be considered carefully, as breaking changes would cause serious, wide-spread issues.
The last section of the main column is the comment dialogue box. This is where you would post another standalone comment to the PR, or an overall reply to a review comment. Here you can also close your PR if you desire, with or without a comment. Remember, it can always be reopened!
Here's a quick look at a couple of sections of the right column. The rest will be skipped as they are less relevant to this guide.
The top section is Reviewers. Here you will find the individuals or teams from whom a review has been requested, or those who are actively reviewing your PR. You will likely not be able to request a review on your own PR, but don't worry, we'll take care of it for you!
The sixth section is Development. Here, if applicable, you'll find a list of issues by name.
If you look back at my PR comment, you'll see the first thing I include is, "Fixes #10." Looking through that repository, you'd find that issue 10 refers to the f-strings. As my PR addressed that issue, I can put specific language in my PR comment, and it will automatically close the issue when the PR is merged!
If there are no associated issues, it will simply say "None yet".
The Files changed tab shows you the same comparison you saw when you created your pull request. In the case of only one file, it will look very similar to the PR creation comparison. When you've edited more than one file, in addition to the change comparison, it will also include a new column on the left showing the file names and directory structure. Below, one file in /, and two files in examples/ were edited.
To see the other two files, you would scroll down through the comparison until you find them.
That's your new pull request! Now you know what you're looking at, and will hopefully find it easier to make your way around as the process continues.
Once your pull request is created, Actions automatically begins going through the steps to check your code. You can keep up with where things are at by checking the status section! Know that while the status may say there is only one check running, that check is verifying a large series things at once.
The checks can sometimes take a bit of time to run. During that time, the status will be, "Some checks haven't completed yet".
You'll notice though, that now there's a new section in the status area. This section shows the check (or checks) that are being run on your pull request, as well as the current status of the check. Initially, it may show as queued.
Once the check is running, the status will update.
The check has completed, with the status, "All checks have failed". In the event of a failure, you'll need to work through it before the review process can begin.
The most recent commit in the commit list shows a red X next to it, indicating the same.
This is going to happen to you. Consider it to be a normal part of the process. We've all dealt with it. The more you go through it, the more you'll learn, and eventually it will happen less. But inevitably you'll miss something, and the Actions checks are here to let you know. Let's take a look at how to get that information from Actions.
Click on the Details link found in the section letting you know that the checks have failed.
This will take you to the Actions log. Lucky for us, it scrolls you directly to the place in the log where the failure occurred. Here's what you'd find if you clicked Details on my PR. There is a right column that you won't do much with. The info that you want is on the left. It looks really involved, but once you're through this section, you'll know exactly what you're looking for.
In my case, there are two code checks that failed. How can I tell? Let's take a closer look.
I'm going to look at the errors. The first indicates that the black check has failed. It also tells me which file Black failed on.
Black is our code formatter; it ensures that all library code is formatted consistently. When Black fails, it means there is a formatting issue in my code that I will need to resolve.
You'll see the next four checks passed. Excellent!
However, the pylint (library code) check also failed. The log provides the Pylint error, which includes all the information you need to fix it up.
Pylint is our linter, which is used to check your code for syntax and style. When Pylint fails, it means there is a stylistic issue in my code that I will need to resolve.
Now that I know what caused the PR checks to failed, I can work through it. This guide covers the process of handling Pylint and Black errors.
We highly suggest installing pre-commit which automatically runs these checks before you even commit, which means avoiding them in your pull request. I deliberately avoided pre-commit for this PR to show how to read the error logs.
You found the errors, and you fixed them on your computer. Now, you need to submit them. You don't have to make another pull request to do this! Simply follow the same steps you followed previously, push to the same branch, and your new commit will appear! Pushing a commit to the current branch will update the open PR. Let's make it happen.
Once you're satisfied that you've made the necessary fixes, you're going to
Now, you can go back to your pull request and check the commit list. There is the new commit!
The status will update to indicate the checks are running. Every time you add a new commit to a pull request, Actions will automatically run the checks. The checks can fail at any time during the PR process when multiple commits are involved. Automatically checking each commit ensures that, even if you get the checks passing with a particular commit, you don't accidentally introduce new issues with a later one. Let's see what happens!
There you have it! The PR status is, "All checks have passed", which means your PR is ready to go. You'll see a green check next to the commit hash in the commit list as well.
Your pull request is now ready for review! The next section covers the process of receiving a review.