If you’ve spent any amount of time in the open source community, you’re probably familiar with GitHub issues. Issues are a fantastic way to organize the discussion around bugs and feature development in a codebase, and it’s common for open source projects to rely on issues to communicate actionable chunks of work to contributors. This practice is ubiquitous in open source repositories on GitHub, and with the help of issue labels and milestones, issues have supported the development of tons of projects and technologies.
That being said, even a relatively small project might have dozens or hundreds of issues at any given time, and as a new or returning contributor to a project, the issue page can be a little intimidating. Even with tags like “good first issue” or “low hanging fruit,” it can be hard to find an issue you can contribute to, and even harder to understand where your small contribution fits in to the larger picture for the future of the project. As the maintainer of several open source projects, I also find that issues and labels alone can be lacking in terms of communicating urgency, or task order to prospective contributors.
Enter the Project Board!
GitHub’s Project Boards, which have been around since 2016, are a Trello-like project management tool which allows for organization of issues, pull requests, and one-off notes into columns directly in your GitHub repository. It provides a great way to maintain a kanban style issue tracker that can:
- organize issues as they progress through the development cycle
- get an easy to digest visual overview of what’s being worked on at any given time
- give contributors an idea of what they should pick up next
There are endless possibilities in configuring these boards, so let’s start with one of the most basic use cases:
Regular ol’ Lists
In the most basic sense, Projects is a tool for making lists, so use it to make as many freeform lists as you like! It’s totally valid for a project board to be entirely disconnected from issues and PRs.
A slightly more common use case for me is using projects to organize a kanban board directly in my repository.
Instead of organizing the board around set sprints, I think that these boards are most effective when they are organized around just one milestone, feature, or specialty. In this way, the board can function as a helpful roadmap without all the process around things like estimation and velocity, which can produce limited value to a highly distributed and largely volunteer-based team of individual contributors.
Automated Issue Kanban
Although automation in project boards is still somewhat limited, when set up thoughtfully I still find that it can be a great tool to leverage in managing and maintaining an up to date kanban board! GitHub actually provides a default project template called “automated kanban” which works pretty well! Each project’s workflow will require a unique configuration. In this article, I’m only going to walk through adding the most basic automation to the kanban board above, but I recommend reading GitHub’s documentation to get an idea of the full potential of these features.
Issues can be added to projects in a similar way that labels are applied to them. GitHub provides handy automation for assigning newly added cards to a particular column in the project. I add issues to the to do column automatically when they are added to the board or when an issue on the board that was closed is reopened. Let’s walk through exactly what that looks like:
Adding an issue to the repository, I can select a project I want to add the issue to.
When the issue is added to the project, it is automatically put at the top of the to do column.
This still allows you as the maintainer to pick and choose which issues should be added to which project board from within your usual issue shepherding flow without having to go to any of the project boards directly.
Periodically, I’ll sort through the cards in the to do column and prioritize them. Because new cards are added to the top, I like to add a card to denote which tickets have been vetted and prioritized and are ready for development, and request that contributors try to pick issues from below that line. You could also easily automate adding new issues to a “triage” or “icebox” column, and manually move cards into “to do” as they are prioritized.
Unfortunately, with limited automation options and no way to self assign tickets, there’s still no replacement for human moderation when it comes to communicating that an issue is being worked on. I usually ask that contributors let a maintainer know they are working on something by mentioning us in the issue. When we get a chance, we’ll manually move the issue from the to do column to this one.
Note that for epic issues that will require many PRs (for example, large test coverage issues encompassing dozens of tests, where there might be individual PRs by different contributors for each test) I will usually leave the issue in the “to do” column so that contributors can easily see that it is still available to work on, even though it is technically “in progress”. I typically will move the issue into the “in progress” column when there is no remaining work on the ticket that isn’t already in flight.
Donezo! This is where all the cards land eventually. Issues are moved here automatically when they are closed.
Issues vs. PRs in Kanban Boards
The project boards I just described only included issue cards, but it is just as easy to add PRs to your boards in the same way. You could even have issues, PRs, and note cards all within the same board. I used issues in the above examples because issues have the cleanest one to one mapping with the tickets you’d see in any other project management tool like trello or pivotal tracker, and you may find that PRs can go stale much more often in open source projects than issues, so issues can sometimes be a more reliable indicator of work than PRs. There’s nothing wrong with using PRs in your project board if it makes sense for your project, and you’ll even be pleased to find that PR automation has even more bells and whistles than issues.
If you add PRs to your project board and find that it becomes messy or overwhelming try splitting it up into different project boards! You might find that having one board dedicated just to issues and another just to PRs helps ease the chaos, especially if you have a large repository with lots of issues and PRs. You may also find that putting issues into your project board isn’t helpful at all in your case, and just tracking PRs provides the greatest value to your organization.
The outlined strategies above are just a couple out of a vast number of possible configurations, so you should definitely experiment with it and find which workflow works best for your project.
Project Boards Wishlist
With all that being said, there are still lots of features that I wish Project Boards provided. If you’re reading this, GitHub, please make my Project Boards dreams come true! Here are a couple of features I wish Project Boards had:
- Label based automation, or hooks for moving an issue/PR when a user is assigned to it.
- Hooks for moving an issue when a PR is opened which resolves it.
- Along those lines, hooks for adding PRs to the board when it resolves an issue that has already been added.
- Project Boards API! Although an API is in development, it’s still in a preview period. Having a stable release of these endpoints to develop reliable GitHub bots that can do some of the heavy lifting in properly assigning and sorting issues and PRs would be super neat.
- Make it open source! I’d love for project boards to get the developer love it deserves. Please open it up to the community so we can make this amazing tool even amazinger!
Hopefully, you now have a better understanding of what project boards is and how it can be used to introduce another layer of organization to your open source project. Although there are still features that I wish existed, it’s still a super powerful tool that can be built right into your repo which I’ve found to be an essential part of my workflow for all the repos I manage.
Next time you find yourself managing an open source repository, give project boards a try, and please leave a comment with your favorite project board configuration!
Interested in more software development tips and insights? Visit the development section on our blog!