A Place for Everything: How I Track Work

When I have management responsibility on a project and influence to shape workflows, this is how I typically manage issues and pull requests. None of this is the One True Way – it's just the system I've arrived at, and I find writing it down useful both for myself and for blog readers who enjoy such things and want to evolve their own flows.

Aside: If I'm joining a team that already has a working software lifecycle, I don't inject any of this out of the blue. I might ask a lot of questions about their process and why they landed there, but any changes are more gradual through team discussion and choice.

Issue Tracking

I like to keep issues in GitHub Issues and present progress / scheduling via GitHub Projects. I choose GitHub to be as close to the code/repo as possible. Two reasons:

• Knowledge stays next to the code it's about, instead of drifting off into a separate tool that's easy to lose. (I find people shift documentation tools a lot, and switching out of GitHub seems doubtful – though that wind might be changing these days.)
• Stakeholders get visibility – they can see what's in flight, watch epic-level progress, and gauge risk against a schedule.

Issue Statuses

I tend to organize issues by status, and I use more stages than most. The extra granularity makes it easy to see, at a glance, exactly where work actually is:

• Opportunities – unshaped ideas for work
• On Deck – prioritized, well-shaped, and understood
• In Progress – started
• Needs Review – finished (not merged) but awaiting peer review
• Done (Merged) – merged but not yet deployed
• Deployed (Shipped) – deployed to customers
• To Be Verified – deployed work explicitly awaiting business review before it's considered complete
• Verified – reviewed by business stakeholders and considered correct and complete
• Canceled – dropped and no longer being considered

The naming here is deliberate. I use Opportunities instead of "Backlog" because "backlog" implies a pile of work you're obligated to get through. "Opportunities" can sit around indefinitely and may never be prioritized – and that's fine. It gives ideas a home for public consideration and discussion without the quiet guilt of an ever-growing backlog.

The risk is that the Opportunities column gets too big to browse. When that happens, you clean it up and close issues. That's allowed.

Issue Types, for navigating a large list of opportunities

Statuses tell you where work is; types help you navigate what it is, especially when an Opportunities list gets long.

• Task – a specific thing to do, including non-code work
• Bug – an unexpected problem or behavior
• Feature – new functionality
• Enhancement – an improvement to existing behavior
• Enhancement: UI – interface changes that improve usability without new behavior
• Security – work related to platform security
• Code Refactor / DevOps – code-quality changes and developer quality-of-life improvements
• Documentation – improvements or additions to captured knowledge

Pull requests that tell a story

Pull requests are where issues are actually resolved, so I like to tie the two together explicitly.

A PR should reference the issue it fixes so it closes automatically on merge. If the work moves an issue forward but shouldn't close it, I just say Related to: #123.

A few things I lean on:

• Use a PR template. A template helps everyone remember the things reviewers tend to need. It's a default, not a rule – if a particular change is better presented some other way, ignore the template and present it that way.
• Shape the PR as a story. Explain the problem or the enhancement request, then walk through the change and how it resolves that problem. Give clear instructions on how to verify the change – and if the default dev environment doesn't have the data needed to demonstrate it, include code to seed that scenario.
• Open PRs early as drafts. I tend to push a PR early in my own dev cycle so people can see what I'm working on. The "draft" state indicates I'm not requesting review yet. Only when it's marked "open" – and I formally request review – am I actually looking for eyes.

A sample template

Templates can be as light as you like. Here's about the simplest one I use:

Fixes #<issue-number> / Related to #<issue-number>

## How to test/verify

Please include instructions for manually reviewing this changed behavior.

Other teams I've worked with prefer a template that prompts the author to check their own work before handing it off – a short list of questions to ask yourself before you ask for anyone else's time:

Fixes #<issue-number> / Related to #<issue-number>

## Problem Statement

## About the Change

## How to Test and Verify

## Author checklist

- [ ] Is the code well tested?
- [ ] Are typespecs explicit, or are the new types too generic?
- [ ] Have you considered the performance characteristics of the new code?
- [ ] Did you document any new decisions?
- [ ] Are there changes to ubiquitous language or naming that others should know about?
- [ ] Does this need a documentation or changelog update?
- [ ] Are there any follow-up issues worth opening before this is forgotten?

The exact questions matter less than the habit they encourage: a moment of self-review before a PR becomes someone else's responsibility. Don't waste your peer's time. Respect them by giving them the context and tools they need to do a good review.

And it should not need saying, but keep the PRs as small as possible. Learn to break down your changes.

Note: The Lobsters discussion page (https://lobste.rs/s/yu7k51/place_for_everything_how_i_track_work) returned HTTP 404 at ingest time and could not be captured.