Open Project Management with GitHub
Is it possible to manage a big, important, open source project without ever leaving GitHub? Yes it is. Our team took on this concept recently with one of our most engaging and involved projects, and it worked like a charm.
The InfernoRed Technology team recently partnered with Microsoft’s Defending Democracy program to build out their open source project known as ElectionGuard. ElectionGuard is designed to work with a multitude of voting platforms to ensure end-to-end verification of elections. Our team has worked on several different pieces of the project from the starting demo for the Aspen Security Forum, to supporting a live election in February of 2020 and to the most recent python release.
When developing on ElectionGuard, I wanted to seamlessly blend the developer and the project management experience. The project didn't have a large team of developers and I wanted the project management experience to feel as open as the code. Most developers will probably only associate GitHub with their code repository services, but GitHub has some great tools for project management that reduce the necessity of having secondary tools. With the new changes to GitHub pricing, this is a great time to drop in and try them out. Setting up your project can all be done from GitHub quickly. For this post to make the most sense, I'll assume you have created some repositories and are ready to get started with project management.
? Setup a Project Board
The first step after a repository is made is setting up a project board. Boards can be set up by individuals, organizations or for particular repositories. When working with ElectionGuard, I used a single project board for the organization and then tied all the different repositories to a single project board. The average use case for most teams will probably be a board per repository.
The boards have templates such as Basic Kanban and default automation settings. I highly recommend starting with these for beginners and altering them over time.
Once your board is made, it's time to get started making cards and get to coding.
? Create a Card
Cards are the replacement for your scrum board post-its. These are to help you track work. On a project board, there are 3 types of cards that can be added:
- Note
- Issue
- Pull Request
Let's take a deeper look...
Note
A Note is a card that isn’t associated with any repository – just the board. I found the best use case for notes was non technical cards or tasks that were unrelated to code.
A helpful hint is that GitHub links like PR links will display detailed information on Note cards. This can be useful for those teams just starting out.
Issues & Pull Requests
Pull requests can have the project added to them to show up on the board. This can be useful for big open source repositories that may want to manage strictly the PR due to a large amount of issues.
Issues are typically bugs or features and are probably the 90% use case. These are the most useful and can be created directly from the board to ease the amount of effort.
Choosing a Card approach
Currently, there are two main approaches to cards.
A. Pull Requests First
The easiest approach is focusing on pull requests. This is the basic GitHub approach of waiting for pull requests. The automation currently seems to work best with this approach. The draw back is the reason for the work takes a backseat to the code.
B. Issues First
Issues can be treated in much the same way that cards are used in methods like Scrum. Multiple pull requests can also be put against the same issue. This makes the board really clean and what many project managers expect. The biggest disadvantage is the automation only works currently with opening and closing the issue. This is the route I took for ElectionGuard since I wanted more focused on the issues and tying into milestones.
? Handling Iterations
Iterations or sprints are particularly tricky in the GitHub world. When you make a project, this creates a singular project board. This could be used for creating a single sprint and some teams will take the tactic of just creating multiple projects to have multiple boards per sprint. Naming-wise I feel like this isn't the intent and is rather confusing.
The second option and the more likely option is to use Milestones as the sprint indicator. Milestones also track progress of the attached issues and can give an indication on how close the milestone is to completion. The only part about this that leaves something to be desired is there is no tool to have a milestone created for all the repositories on a project board. This is a feature that has been heavily requested.
Using milestones for sprints is a great way of showcasing developers exactly how close the iteration is to being finished, thus helping to schedule work. I used the milestone approach with ElectionGuard, which allowed the team to showcase the issues completed with each release by just linking to the milestone. The approach was pretty similar to Scrum with planning and completion steps for each iteration.
Planning
Before an iteration, a milestone would be created from the issues page perhaps setting a date for completion. The team would then select or create issues relevant to the iteration and place them in the ToDo or equivalent column. The board is now prepped and ready for coding.
Completion
When the iteration is complete, the milestone should be complete. If it is not, depending on your work you could (1) move the date and (2) move the unfinished cards to a new milestone. Once the milestone is truly complete, cut the code and make a release! ??
? Managing Work
Handling new cards
New work will arise at some point and new cards will need to be made. Also, if you're running an open source project, you may have users adding issues or pull requests. For ElectionGuard, we used Issues First approach and would add new cards to our milestone relevant to the release. If you take the Pull Request First approach, you merely have to tag new pull requests with the project and let automation do the rest of the work for you. If you seem to lose a card, be sure to check the triage section of your board.
Updating Cards
Updating cards mainly applies to Issue First Approach. Pull Request are not only automated by default, but typically aren't blocked since the code has been implemented. Thus, I'll explain updating cards from the issue side.
Cards (aka Issues) have a couple different statuses with the setup we used. This is how I broke them down for the team.
- To Do - Issue awaiting to be worked
- In Progress - Developer working on the issue
- In Review - Pull request(s) is open and linked to issue
- Done - PR merged and issue closed (automated)
- Blocked - Issue blocked by something like requirements
All of these can be handled from the project board or the issue itself depending on your preference. Personally, I preferred the project board, but either way this minimizes the work you need to do. You can also update the release/milestone from the board as well.
? Open Source
Time to show off. For open source projects, remember you can share your project board to the world by making it public. Perhaps you can add the link to your README.
If your board is a mess, no need to worry. The issues themselves will indicate the status on the board even if the board stays private. Also, if you go the milestone route, those are visible for visitors as well.
?Try it out yourself!
Hopefully this will help new GitHub users embrace project boards as a lightweight tool and save some developers the hassle of having multiple tools just for some card management. Save yourself some time and have fun collaborating! Feel free to share your own tips and tricks with our team at @infernoredtech.