How to use GitHub for Gutenberg

The WordPress project uses GitHub to manage all issues related to the Core Editing experience including everything from, core blocks like image or paragraph, core editor APIs, full site editing, and more. Because this system is separate from Trac, the ticketing software that core WordPress uses, it can cause some confusion about when to engage here.

This video will teach you everything you need to know about creating, updating, and browsing GitHub issues so that you can effectively contribute to the core editor and follow along with the project using GitHub (This line is partially stolen from the how to use Trac workshop!).

Learning outcomes

1. How to create a new GitHub Issue
2. What makes a good GitHub issue
3. How to search through currently open issues and follow relevant issues
4. Understanding the various GitHub labels
5. When to share in GitHub over Trac or the support forums

Comprehension questions

• What should you do before opening an issue?
• What makes a good GitHub issue?
• What are GitHub projects used for?
• When should you share in GitHub over Trac?

Resources

• Gutenberg GitHub Repository
• What’s New in Gutenberg
• What’s Next in Gutenberg
• GitHub Glossary

Transcript

Howdy, my name is Anne McCarthy. I’m a WordPress contributor and triager for the Gutenberg GitHub repository.

In this video, I’m going to cover how to use GitHub to get information you need about Gutenberg. This should help you better keep up to date with what’s happening in the project through the lens of GitHub. This will not cover things like making pull requests or setting up Gutenberg locally, as this course is meant for non technical folks. It also will not cover the many of the other GitHub repositories as part of the word WordPress GitHub organization. Let’s dig into what this will cover though after a quick intro.

In case you’re not familiar, Gutenberg is the project codename for the Core Editing experience. Meanwhile, GitHub is the ticket tracking tracking software that the WordPress project uses to make changes to the core editor experience. This repository is where all open issues and pull requests aka proposed changes to the Code are managed. This repository is separate from Trac, which is the ticket tracking software that the WordPress project uses to make changes to the core WordPress experience. Keep in mind that Trac does still include Core Editor work though.

After watching this video, my hope is that you’ll have all the information you need to help explore the Gutenberg GitHub repository and stay up to date on the latest work.

Here’s a quick outline of what we’ll go over: how GitHub is used in the Gutenberg project; a brief overview of terminology; how you might interact with GitHub; how best to search through the repository; how to submit issues; an overview of project boards; and tips and tricks.

Before going further, it seems important to first pause to share a bit more about what GitHub is used for. Simply put, it’s a project tracking software where all open issues and pull requests are managed by those who help organize the project itself. This means that’s not the right place for support requests configuration help or things like job postings. It is the right place though to submit enhancement requests, bugs you found, to review what developers and designers are working on, to help contribute to the codebase, and more.

Keep in mind that there are other avenues to stay up to date with what’s happening with Gutenberg to if GitHub isn’t for you. In particular, it’s recommended to review the biweekly “What’s New” posts covering what’s in each Gutenberg release, and the monthly “What’s Next” post highlighting the work plan ahead. You can see the links to both of these in this slide.

At this point, let’s go over the most basic terminology you need to know to get the most out of GitHub.

To start, issues. Issues are suggested improvements, tasks or questions related to the repository. Issues can be created by anyone for public repositories like Gutenberg, and are moderated by repository collaborators like myself, a triager.

Pull requests, aka PRs. Pull Requests are proposed changes to a repository submitted by a user and accepted or rejected by repositories collaborators.

Commit, this is an individual change to a file or set of files. Commits usually contain a commit message too, which is a brief description of what changes were made. This is typically pretty helpful to get a sense of what changes happened.

Labels, this is a tag on an issue or pull request. Repositories come with a handful of default labels, but Users can also create custom ones. For example, the Gutenberg repository has over 250, and we’ll talk about them more in a bit.

@ mention, this is used to notify a person on GitHub by using @ before their username. I find this is pretty helpful if you need to interact with others in a discussion.

With these terms in mind, it’s important to note that you’ll see discussions happen in issues and pull requests. This is to be expected as contributors find the best way forward to complex problems, and you’re welcome to join the conversation if you have thoughts to share.

Keep in mind too that there are a ton more terms you might run into, but consider this just a quick overview for this specific course. If you want to learn more, check out GitHub’s documentation shown at this link on this slide.

With the terminology in mind, let’s talk about the various ways you might interact with GitHub.

You can submit issues for bugs or feature requests. You can submit pull requests for proposed changes to files, whether related to the Gutenberg plugin or certain types of documentation. You can search GitHub for information and read the latest updates. You can check the status of projects.

For most of these modes of interacting, you’ll want to create a GitHub account in order to best follow along, join the conversation and more. However, if you don’t want to create an account, that’s okay to. Just keep in mind that you’ll only be able to read about what’s happening without being able to contribute back on GitHub.

While there are a ton more ways you can interact with GitHub, like for example, checking out a specific PR that hasn’t yet been merged. These are the main ways of interacting to be familiar with.

A main way most people interact with GitHub is by submitting issues for consideration. Before talking about this, though, let’s go over how to search through the repository. It’s important to cover searching first, as before submitting an issue, you want to make sure it hasn’t been reported. If you find it has, it helps to add a comment sharing your experience and what versions of Gutenberg and WordPress you’re using, especially for older issues.

The best way to search the repository is to use a combination of key phrases and if needed labels. Let’s quickly peek at the labels for the repository, now.

As you can see, there are over 250 labels in the repository. If you’re up for it, I recommend taking some time skimming through these simply to get familiar with the breadth of labels. For now, though, let’s notice that there are various clusters of labels. You can use the search field to see these more readily. For example, there are issues related to accessibility. You can also find labels for each block. There are even labels for specific features like Full Site Editing. Then there are more general ones like bug and enhancement that you can find under type. If there’s a label that you think should exist, but doesn’t yet, it’s just adding it in the core editor channel in the WordPress.org Slack. It’s important to mention now that these labels are for both issues and for pull requests. So you can use these when searching either section. Let’s look at the issue section, now.

As you can see, there’s the same search box that was in the label section. You can use this to search for keywords and phrases related to the problem or enhancement requests you might have. Here are a few more tactics to narrow things down even more. To start, you can add labels to your search. The easiest way to do this is to select from the drop down like so. Keep in mind that you can add as many labels as it’s helpful to narrow things down. You might even narrow it down to the point where there’s no results found. This is okay, I recommend removing labels like so, to then see the open issues. You can also filter by Milestones. This tends to be more helpful when searching through Pull Requests and I’ll show an example in a bit.

Finally, you can check open issues only using, this is:open. You can check closed issues by using is:closed, like so, and then you can search all issues by just removing this. Keep in mind too, you can also click on these titles to pull up open or closed issues and you’ll notice that the search changes as a result. Let’s go back to all open issues. At this point. depending upon what you’re trying to do. You might also find it helpful to use the Sort By section to see the most commented on issues to perhaps find lively conversations. Look at that 93 comments! Or you could use recently updated to see what issues have traction.

Let’s switch over to the Pull Request section where you’ll see the same tools. And we can go over an example of how you can put this all together. So here’s the label, here’s the milestone, and here’s the source. Now let’s say you want to check the latest release to find any changes really to Full Site Editing for Gutenberg 9.9. To start, I recommend removing the ‘is:open’. This helps you see all PRs whether they’re merged or closed or still open. This is pretty important, especially if you’re trying to find something in a recent release. From there, let’s use the milestones to choose Gutenburg 9.9. At this point, we went from about 500 different open issues to now 174, this is still a lot to go through so let’s see if we can narrow it down even more using the label. There you have it. Now we only have 17 issues to look through to see what’s changing in Gutenberg 9.9.

Now that you know how to search both issues and PRs, let’s quickly go over submitting issues. Specifically, we’re going to focus on bug requests and feature requests as those are the most common issues one will likely open.

To start let’s head back to the issues section. From there, we can select new issue. You’ll then want to select Get Started next to the bug report. Keep in mind that there’s another form for Mobile issues currently too, so select which one is more relevant to you. This then brings us to this screen where you can see a lovely template that helps guide you through the best way to report a bug so that its most likely to be addressed. This template was created by maintainers of this project, so please try to follow it as best as you can. While you might be tempted to skip over these sections, please fill them out! Ultimately, doing so will help increase the chances that the right people have the right information to help resolve your problem. Let’s go over each section now.

To start, there are some nudges that tell you what to do before submitting a bug report. This includes things like checking to see if the bug has been fixed with the latest version, or things like deactivating all your plugins except Gutenberg to rule out the problem. From there, you’ll see a place to put the description of the bug, please try to keep this brief. From there, you can list step by step instructions to reproduce the issue. This is extremely important, as it helps others find the same problem that you found. From there, describe what you expected to have happen. Finally, what actually happened, this helps us see the difference between the two. If you can please share screenshots or screen recordings. Keep in mind that you can always upload files using GitHub itself. There’s also a handy tool you can use if you want to create a GIF. From there, another optional section is to add a code snippet. This might be helpful if you’re trying to follow more technical issue. Finally, the last two sections have to do with device information and WordPress information. This is extremely helpful because it allows us to know if you’re using the latest version, and where the issue might be.

Now we’ve covered bug report, let’s go back and look at Feature Requests. We’ll go through the same flow just so you can get a sense of it. Once more, you’ll click “Get Started”. As you can see, this looks very familiar to the bug report, with another albeit shorter template in place to help set you up for success. Let’s quickly go over each section now.

To start, the question is what problem does this address? As you can, try and be as descriptive as possible particularly if you can include screenshots or videos or even from other projects that do this well. From there, share your proposed solution. Again, make sure that it addresses the problem identified above. That’s it for a feature request, but keep in mind as much information as possible that you can provide help set this up for success.

Now let’s turn our attention to Project Boards to see how some of this work gets organized. Keep in mind that not every feature uses a project board so don’t be alarmed if you don’t find one. As their name suggests, these are meant to organize work around specific projects. You can generally expect project boards for the following items: Major WordPress releases and some larger scale feature projects.

Because I’m recording this in February 2021, let’s look at the 5.7 project board to get a sense of how this is set up. To do this, I’ll go back to the main repository page. From there, I’ll head to Projects. Finally, you can see this board at the top, WordPress 5.7 Must Haves. As you can see from the start there are various columns to group issues based on what stage of work it’s in. Whether it’s to do or in progress, or if it needs review, or if it’s being completed. If you’re trying to track keep track of a specific project, this is a great way to stay on top of what’s happening. It’s a bonus tip, you can also use the “Filter Cards” field to search for specific issues.

To close out this course, let’s go over some extra tips and tricks to make the most of using GitHub. At a glance, here are the tips and tricks I’ll go over: checking closed issues and prs; reviewing pinned issues; subscribing to issues and PRs; checking the overview label. Let’s dig into each on GitHub now. The first one you’ll probably find familiar.

As mentioned before, you can change the search parameter to see both open and closed issues, or to see all. I find this is really helpful, especially if you’re looking for context on a previous decision. The easiest way to remove this is to remove the is:open. From there if you need to, you can search just closed, just open or again, remove the parameter all together to see all issues. From there, you can search whatever you’d like, use labels, check projects, check milestones, and even sort.

Next up, let’s check out the pinned issues. You can find these here. I find these are particularly helpful, because anything that’s pinned tends to be relevant for everyone. For example, site at any milestones reflects the current priorities of the Gutenberg project. Let’s click on it now.

For the next tip or trick, I’m going to go over subscribing to issues or PRs. Mind you, in order to subscribe, you have to have a GitHub account. This is where it’s also really helpful to have an account set up. As you can see, there’s a notification section over here. I’m already subscribed to this issue, but let’s pretend I’m not. All I have to do is hit subscribe and I can get instant notifications about any updates to this issue. You can also go a step further and go into GitHub notification settings to set what notifications you’d like. In this case, I like to get email notifications, but someone else might want browser notifications.

For the final tip or trick, we’re going to look at a specific label. It’s called the Overview label. This is a very high priority and important label as it often covers the most comprehensive issues. I’ll scroll down briefly so you can get a sense. To start there’s only 31 open even though there’s almost 3000 issues. So you can see this is a very rarely used label, and often one for bigger projects. I highly recommend digging through these if you want to get a sense of past discussions, decisions, or future work coming up.

We’ve reached the end of this course. This should help set you up for success for using GitHub to stay up to date on the Gutenberg project and to find ways to participate. Thanks for being interested and I hope to see you in the repository.