How to do triage on GitHub

To keep the Core Editor GitHub repository healthy, it needs to be triaged regularly. Triage is the practice of reviewing existing issues and pull requests to make sure they’re relevant, actionable, and have all the information they need. Anyone can help triage and this workshop is meant to help you learn how to get involved covering everything from the various ways to help to how to escalate serious problems. No development or design experience is necessary!

If you’re looking for a way to get involved with the WordPress project and don’t know where to start, triage is a great place to begin as it gives you a deeper look into current issues, longstanding problems, new approaches being tried out, and interesting discussions.

Links:

Get involved in triage: https://github.com/WordPress/gutenberg/blob/master/docs/contributors/triage.md

Learning outcomes

How to get triage permissions for GitHub if you want them and what the expectations are
Where to communicate triage efforts and the types one can do (join triage meetings, do triage solo, etc)
Understanding commonly used labels
Understanding commonly used filters
Understanding how best to escalate any serious problems

Comprehension questions

How do you get access to help with triage efforts?
What are the main ways one can participate in triage efforts?
How do you determine and escalate a serious problem?

Transcript

Howdy! My name is Anne McCarthy. I’m a WordPress contributor and triager for the Gutenberg GitHub repository. In this video, I want to cover how to do triage and GitHub for Gutenberg. This is one of many ways to contribute back to the WordPress project. And I hope you’ll join me.

In case you’re not familiar, Gutenberg is the project codename for the core at any experience. Meanwhile, GitHub is the ticket 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 are managed. Finally, triaging is essentially taking on the role of helping label issues and pull requests appropriately so they can be better handled and organized. Of note, this repository is separate from Trac which you might be familiar with, and is the ticket tracking software the WordPress project uses to make changes to the core WordPress experience. After watching this video, you will have all of the information you need to help contribute to the WordPress project through triaging Gutenberg issues, and helping maintain a healthy repository.

Here’s a quick outline of what we’ll go over what accounts are needed for triage, documentation in case you need a refresher, how to get access, ways to triage, common approaches to triage, how to escalate issues when necessary, when to close issues, and tips and tricks. To help with triage and GitHub, you’ll need three different accounts want to go over each one at a time.

To start, you’ll require a GitHub account, you can sign up for one at github.com/join. Once you have one, you’re then able to create new issues and pull requests in the Gutenberg repository. At this point, though, you won’t be able to start adding labels or removing them which is a key part of helping with triage. The next account you need is in making WordPress slack account. You can sign up for this account at make.wordpress.org/chat. This will give you access to the wider slack community that supports the WordPress project.

Once you have this account, you want to navigate to the pound core editor Slack channel, where you can ask for triage ask access. Please wait to do this until you complete this course and have reviewed the repository to make sure it’s something you really are ready to commit to.

The last account you need is a wordpress.org account, you can register for an account at login.wordpress.org/register. Having this account helps complete the connection to the wider community including reviewing Trac issues. As a reminder, Trac is where changes to the core WordPress experience are handled.

If this feels like a lot of information, don’t worry, there’s great documentation that you can always refer to as you get started with triage. Just go to the Gutenberg repository, head to the docs folder, followed by the contributors folder, and you’ll see a triage document. This will lead you to this link below. There’s a screenshot as well, so you know you’re in the right place. Much of this course will cover the same information that’s shared there. So please refer to it as it’s helpful for you. Before going further, let’s talk a bit about getting access to do triage. Well, anyone with a GitHub account can open an issue or submit a pull request for review. There are additional roles in the repository that give people additional permissions, including everything from managing labels to merging code has a result, there’s an additional step that’s needed in order to get proper permissions to help out here.

Thankfully, doing so it’s pretty easy. Just head to the core editor channel in the WordPress slack installation and share there that you want to help with triage along with your GitHub username. If possible when you send this initial message, please also share what you plan to focus on triage, as this helps with coordination. If you aren’t sure just yet, no worries as this course will give you a great overview of the most common options. Let’s go over those ways now. There are three main ways that triage tends to happen, and all of them help keep the repository healthy, so pick what works for you. The first way is to hold regular triage sessions on your own time. This could range from 10 minutes every day to one hour each week.

The second way is to join an organized triage session done as a group. These sessions are held in the wordpress.org slack community. You can review the meetings page on wordpress.org to find these triage sessions and appropriate slack channels. The link for the meetings page we found at make.wordpress.org/meetings. The final way is to be part of more focused gr sessions on a specific board label or feature. This often happens as part of feature projects and is typically done by core contributors. No matter How you decide to help with triage, there are a few general expectations to keep in mind. You’re expected to do some form triage and whatever form works for you at least once a week as you can try to join organized triage sessions as it helps with consistency. Finally, if you join the triage team to focus on a specific label or board, it’s expected you will focus there and it’s important you announced. With this foundation in place, let’s dig into the most common approaches to triage. Well, there are a ton more ways you could help triage beyond what I’ll share here, these are the most common ways get started that will have a big impact on the health of the repository. To start, let’s look at all issues without an assigned label by going to label unlabeled. Charging by simply adding labels helps people focus on certain aspects of Gutenberg find relevant issues faster and start working on them sooner. Next up, let’s look at the source section where you can sort the issues in their repository by different variables. To start. Here’s the least recently updated Gutenberg issues. Charging issues that are getting old and possibly out of date he’s important work from being overlooked. Next, you could focus on all Gutenberg issues with no comments by typing this.

Judging this list helps make sure all issues are acknowledged and can help identify issues that may need more information or discussion before they are actionable. Similarly, you could also look at the lease covenant on Gutenberg issues. Once more, you’ll return to the source section. Judging this list helps the community figure out what things might still need traction for certain proposals. Finally, you can check on the most common and Gutenberg issues. If you feel comfortable chiming in and the conversation has stagnated. The best way to triage these kinds of issues is to summarize the discussion thus far. Do your best to identify action items blockers etc. Charging this list is finding solutions to important and complex issues to move forward.

for charging issues, you’ll often find the following labels are the most commonly used. Type bug. This is when an intended feature is broken type enhancement. When someone is suggesting an enhancement to a current feature, type help request when someone is asking for general help with setup or implementation needs technical feedback. When you see new features or API changes proposed needs more info, when it’s not clear what the issue is, or it would help to provide additional details needs testing. When a new issue needs to be confirmed, or old bugs seem like they’re no longer relevant. There are a ton more labels though. So definitely take some time to explore. Here’s a quick recording to demonstrate how to add labels. So in this case, if I go to labeled unlabeled, I’ll be brought to this page. From there, you’ll select an issue, head to the label section and pick something that makes the most sense. So in this case, I’m going to choose Full Site Editing and enhancement. I knew this because I’m very familiar with this project. And I actually open this issue. But in most cases, you’ll probably have to read the issue in order to know how best to label it. Beyond just charging issues, unlabeled pull requests also need to be reviewed. To check these out. You want to switch from looking at issues to looking at pull requests by going here.

From there, just like with the issues tab, you’ll select label unlabeled to view all unlabeled pull requests. It’s important to note that labeling these requires a level of comfort with code.

If that’s not something you can do, no worries. You can also always check with the person authoring the pull requests to make sure the labels match what they are intending to do. Finally, keep in mind that you can also always create your own custom set of filters on GitHub. If you have a filter that you think might be useful for the community, feel free to submit a pull request to add it to this list. Now let’s talk about how to draw attention to issues when necessary. If you find an issue that impacts a lot of users, or that creates a serious problem, like an inability to use a screen or a block, there are actions you can take to get more attention on that issue. The most obvious action is to label it with one of the priority labels. Let’s go over what each priority means. Priority OMG WTF BBQ. This is a somewhat silly Label that’s meant to represent major issues that are causing failures and are reported frequently. Typically, these are issues that are critical because they break important behavior or functionality. An example might be unable to remove a block after it is added to the editor. Priority Hi, this would be an issue that fits one of the current focuses and is causing a major broken experience, including flow visual bugs and blocks. Priority Whoa. This would basically cover enhancements that aren’t part of focuses niche bugs are problems with old browsers, things like that. It’s important to note that it’s intentional that there’s a level of knowledge needed to determine priority so if you aren’t comfortable doing this to start, don’t worry. Finally, it’s also on purpose that there’s no normal label as that’s the baseline all issues are considered to be. Outside of these priority labels. You can always drop a message in the core editor Slack channel, to alert others to check out an issue you were concerned about. If you are certain there’s a serious issue going on. You can also always use the group alerts by commenting on an issue with the following group handles: @WordPress/Gutenberg (this will alert the entire Gutenberg team), @WordPress/Gutenberg-Core (this will alert the Gutenberg development leads), @WordPress/Gutenburg-Triage-Team (this will alert everyone else on the triage team). These should very rarely be used. So please be very mindful if you can get a second opinion before using any of them, as they will each ping a lot of people. Now that we’ve covered handling labels and determining priority, let’s go over window close issues. Closing issues helps make sure that the issues that are open are the most relevant for developers and designers to investigate further. This leads to lots of save time and effort. Currently, issues are closed for the following reasons. a pull request and or the latest release resolve the reported issue. It’s a duplicate of a current report. It’s a help request that is best handled in the wordpress.org forums. It’s an issue that’s not able to be replicated either by yourself or someone else on that thread. It’s an issue that needs more information that the author of the issue has responded to for at least two plus weeks. It’s an item that is determined that’s unable to be fixed or is working as intended. When you close an issue, please clearly and kindly state why and a comment so that the person who originally opened the issue has a shared understanding going forward.

The final part of this course covers tips and tricks. These should help you supercharge your triage abilities. To start always search for duplicates first. With a project as big as Gutenberg, it’s common for there to be duplicates, and it helps to consolidate those. When doing so it’s a best practice to keep the oldest issue open and close out the newer one. Next, ask what WordPress and Gutenberg version reporter is using. This often helps narrow down where the problem might be and when it was introduced. Well plugin and theme conflicts early on in triage. You can do this by asking someone reporting a bug to confirm that they could replicate this without any other plugins installed except Gutenberg or by asking them to temporarily use a default theme while trying to replicate the issue. This helps make sure that the problem being discussed is indeed in the Gutenberg codebase.

Edit the title to bring clarity to the issue. Doing so allows everyone at a glance to understand the issue at hand and helps people find it in the future. If it’s a bug report, test it to confirm the report or add the needs testing label so someone else can get to it. It’s important that this is done to confirm if an issue is indeed relevant. Add a GIF or GIF Some might say or a screenshot. If a bug report would benefit from more visual information that’s helps those that might be able to fix the issue get up to speed faster on the problem at hand. By being able to visually see the problem. Take time to set up your GitHub notifications. This might seem like an odd suggestion, but trust me, this will help you better keep on top of any follow up that might be needed in your interactions with people who open issues or work on pull requests. Remember that you can search the repo across multiple labels. For example, this means that you can look at all open bugs for the paragraph block and dive into triage from there. This is particularly useful as you get more comfortable exploring their repository. We’ve reached the end of this course. Congrats. This should help set you up for success for triage on GitHub. Thanks for being interested and hope to see you in the repository.