Tracking issue - project management infrastructure

[zmitchell]

This is a tracking issue for setting up some basic project management infrastructure on GitHub so that we can more effectively task out projects and track progress.

The idea is that for each project/feature we have a tracking issue that contains a series of steps/tasks required to move the project to completion, where each step or task links to an associated GitHub task or PR where applicable. We can also list the username of the person the task/issue is assigned to so we know who to contact for status updates. This is similar to how new features are tracked/implemented in the Rust ecosystem (example).

We can then create a "mega-tracking-issue" that we can pin at the top of the Issues page that will contain links to all of the currently active tracking issues. This way we can see which projects are currently being worked on and quickly assess the status of each project by following the links.

Steps

• [x] Give @zmitchell the ability to create labels on NixOS/nix.dev
• [x] Create an issue template for tracking issues
  • https://github.com/NixOS/nix.dev/pull/501
• [ ] Create the mega-tracking-issue (Issue: WIP)
• [ ] Assemble tracking issues for the currently active projects.

Open questions

• Is this valuable?
  • The project board tracks issues spanning multiple repos, and imposing structure across repos to fit our needs is impractical.
  • Issues often get lost in the board because there's little structure.
  • The project board is grouped by status, but it's often useful to put a task in the context of the deliverable that it's working towards, and this system provides that context.
• Is this too much overhead?
  • It doesn't require any external tools, doesn't require anyone to create new accounts, and can be automated to a degree with the issue template and labeling.
  • It removes cognitive load trying to remember who volunteered to work on which issue.
• Are there problems it doesn't solve?
  • It's often useful to see which tasks are blocking other tasks, and this system doesn't have a structured way of recording that information. That's a limitation of GitHub issues though.
• Why not use GitHub Milestones?
  • I've never used Milestones, but to my knowledge they can only be associated with issues under the same repository. Since we're tracking issues across repositories that doesn't meet our needs.

[nixos-discourse]

This issue has been mentioned on NixOS Discourse. There might be relevant details there:

https://discourse.nixos.org/t/this-month-in-nix-docs-1-march-2023/26913/1

[fricklerhandwerk]

Today we figured out an alternative hack: use another item field in the project board to group by topic. Those can be added independent of the repository.

It's a different trade-off: minimal manual handling, allows filtering board views, but does not allow tracking overall progress or dependencies (with lists, at least a dependency tree can be captured).

I think it's better - for now - because we don't care all that much about future projections, and can always query GitHub for what happened in the past (although I don't know if project board fields are shown in the API). Also, if we stay in tight feedback loops we're quite good at identifying blockers that have to be addressed first, which makes making dependencies explicit less of a requirement (although that doesn't scale beyond the active team members).

[zmitchell]

This is more for keeping track of the status/progress on a project while providing context on a grouping of tasks. It's not really about providing future projections.

although that doesn't scale beyond the active team members

The tracking issues also make it easier for new people to onboard themselves to a particular project by seeing its history, what's left to do, etc.

[fricklerhandwerk]

It's not really about providing future projections.

I understand it's not about the future here, but the unfinished tasks give a sense of what's left to do.

I don't disagree with tracking issues, we definitely need a way of providing overview and expressing dependencies. Both ways should go hand in hand, and we have to tinker with workarounds, because GitHub is not a particularly good project management tool.

[zmitchell]

but the unfinished tasks give a sense of what's left to do

Maybe you can clarify what you mean by this. Are you saying this is a good or bad thing?

I think it's very important to keep track of what's left to do. With volunteer work people inevitable drop off because of bandwidth, etc so it's important to be able to pick up where someone left off. The PR (https://github.com/NixOS/nix.dev/pull/501) about adding issue templates makes it trivial to create a tracking issue, you just need to think ahead about what "done" looks like, which you should already be doing without a tracking issue.

I have no problem adding additional metadata in whatever form that takes for tracking things on the board.

[fricklerhandwerk]

unfinished tasks give a sense of what's left to do

Are you saying this is a good or bad thing?

It's definitely a good thing to have. Setting realistic expectations is essential.

[zmitchell]

Setting realistic expectations is essential.

Issue templates makes effort nearly zero. You don't have to create the subtask-issues up front or anything like that, just a todo list of what you think needs to be done.

I'm still unclear on your stance. Is the idea for a hybrid approach where we create tracking issues for context on projects and then mark individual issues with whatever metadata you had in mind for tracking individual items on the board? If so, then merging #501 would be the next step. I don't think you can add project board metadata in issue templates, so those wouldn't need tweaking, but this is a manual step that needs to happen whenever we create an issue regardless of whether we use tracking issues or not. I'm not super attached to the mega-tracking issue as a table of contents, but I think having tracking issues for individual projects would be very helpful for keeping track of work. At the very least I'll be using them for the working group.

Regardless, I think tracking issues have merit because we can keep track of project discussions (like we're doing now) at the project level rather than scattering it across individual issues. There's also no way to attach conversation to the project board.

[fricklerhandwerk]

Oh yes, I'm all for tracking issues. Let's discuss the issue templates in the next team meeting so everyone is informed.