GitHub Project Digests
5 min read
I use a GitHub project to manage household projects and tasks. I wrote about it a few times in the past, such as in how we used scrum to schedule our holidays and in an update on household_scrum. This is a continuation of that project to bring a never-ending TODO list to heel.
User Interfaces
Some people like seeing a shiny, sparkly project board with tasks and stories sorted neatly into columns. Moving cards to the right (i.e., taking a card from todo to in progress to done) brings dopamine hits and dashes of joy as things get done. It’s really a great feeling to take a big, involved task that took hours or days of work and plop it into the “done” column. I think I remember a classic black-and-white movie where they said, “Every time a card is moved to done, a project manager gets its wings.”
Some people don’t want to use a project board. It looks like extra work on an unfamiliar interface. It looks like a waste of time and energy. Why should I play around with a virtual whiteboard when I could be working on my next task? Isn’t maintaining the board someone else’s job?
I’ve long held the belief that a good user interface is the key to whether a project will be successfully adopted or if it’ll be discarded, worked-around, or otherwise despised.
I’ve spent most of my career on the backend side of software development. I generally prefer typing commands into a terminal over navigating graphical interfaces. I often use ssh to connect to systems where I work remotely. The mouse cursor is what I use to point at the terminal window where I’m actually getting work done.
Again, that’s just me.
Some folks need the work to come to them. Logging into some webpage (GitHub) in the morning to check on what needs to be done represents extra work. The workflow doesn’t work for them. The project user interface just isn’t worth the extra work.
An idea about how to change the workflow came to mind during a brainstorming session:
- what if we kept the project board, but had the relevant details sent in an email?
In my development work, often tasks and user stories align with iteration (sprint) planning. The scrum manager, when asked about the completion date for a unit of work, can respond by naming the sprint where the work is scheduled to be done.
In the real world, deadlines don’t fall neatly into sprints. A bill that’s due on July 21st can’t be moved to sprint 27 just because it’s convenient for the project board. So, cards can have due dates that don’t align with sprints. It’s not the end of the world. We just set the “due date” field on the card and we’re good to go.
That’s cool, but it still requires the user to go to the project board and look at the cards in the sprint.
GitHub Project Digest
I looked around for a while to find a tool that did what I wanted. I assumed that there were tools to send scheduled issue reminders and summaries. There are. Finding reminder tools wasn’t difficult. The real challenge was a tool that worked well with GitHub Project custom iteration fields. That is, I wanted a tool that could look for sprint: @current and do its thing. That, it turns out, isn’t a common request.
So, I decided to build something. Thanks to AI, an MVP wasn’t difficult to get up and running. Selecting issues with sprint: @current and looking for due dates and assignees and all of that could be codified through GitHub issue queries:
sprint:@current is:issue state:open assignee:@meThat would return open issues in the current sprint that are assigned to me.
The tool then used a pair of Jinja2 templates (HTML and plain text) to generate an email that gets sent to me. The issues are sorted by due date (overdue, due today, due soon, and no due date) and status (blocked, in progress, todo).
Alternative Uses
One of the very first things I did with the new tool was to customize the filter. On my team – my household – it’s important to know not just what I’m doing, but what others are doing, too. So, a filter change was all I needed to do:
sprint:@current is:issue state:openIt quickly became clear that there may be other types of users who could benefit from this. For example, a project manager may want a daily overview of what the team is working on today:
sprint:@current is:issue state:doingA product owner may want a weekly summary of what tasks were completed since Monday:
sprint:@current is:issue state:doneA technical lead may want to see a list of open pull requests that need to be reviewed:
is:pr state:openMaybe a project manager on another team needs to see issues that are blocked or are blocking other issues:
is:issue state:open has:blockingHow It Runs
The tool was written in Python and it can be run either locally or in a containerized environment. There’s a containerized version that’ll run under Docker or Podman that is hosted on Docker Hub:
wesleydean/github-project-digest:latest
If you’re interested in checking out the GitHub Project Digest tool, it’s in a public repository on GitHub:
wesley-dean/github-project-digest
It can be configured via command line flags, environment variables, or a .env file. Any version can be run from automation tooling such as Jenkins. I hope to make it available as a GitHub App at some point. You’re welcome to watch the repository for changes and announcements.