Use projects for focused, short-term work with a specific audience

[handrews]

This issues summarizes a discussion from Slack between @lornajane, @earth2marsh, and myself.

TL;DR: Too much of our progress on recent focused tasks has relied on me actively maintaining lists of issues/PRs, aggressively putting the in front of people, and taking up lots of time in the weekly meetings. We would be better off with a more collaborative and flexible way to see what work needs immediate attention, and one that is more robust to any one person being unavailable for a couple of weeks.

Our current weekly meeting approach is working pretty well, and I think would continue to function whether I organized issues/PRs from all of the comments each week or not. But I think well-organized issue/PR lists have helped us be more productive in recent weeks (e.g. this past week's security focus). Curating those organized lists takes time and effort, and I think Projects would be a way to do that that does not depend on any single person manually curating things from multiple sources every week.

Problem statements

• It's a lot easier for many new contributors to make changes to infrastructure-y things, like PR automation, JavaScript environment management, etc. Those things are often pain points that don't get focused attention by the more active contributors who are focused on the spec itself.
• We have a lot of open process issues that we need to resolve in order for potential contributors to be able to successfully navigate the project (and for folks with write access to know, with confidence, how to handle contributions); These things are very much pain points but require the attention of the TSC to make decisions.

Things these two problems have in common are that the work should be finished in the near-ish term, and that there's something specific about who can or must do the work: One is good for folks who do not know the spec process, or just have different skills, and the other requires specific permissions.

What are projects?

Projects are one of three ways GitHub offers to group issues and/or PRs, the others being labels and milestones. I'll summarize the differences here:

	labels	milestones	projects
multiple per issue/PR	Y	n	Y
supports workflows	n	n	Y
optional iterations	n	n	Y
optional due date	n	Y	n
supports discussions	Y	n	n

My personal view (where "items" == "issues + PRs"):

• Labels are good for functional categorizations, as items stay in the same category indefinitely. They are not good for workflows as they have to be manually updated, and mixing too many purposes within labels leads to a confusing amount of labels (as we have right now).
• Projects are good for workflows. You can see what is being worked on, what is done, what is available to work on immediately (TODO column) and what is in the project but deeper in the backlog. Project-related status changes can be automated, and closing an item automatically puts it in the "Done" column. Status changes are otherwise done by dragging items from one column to the next.
• Milestones are good for releases, but TBH I suspect that if they weren't older than projects, we'd only have Labels and Projects

How would we use projects

I have created two projects, currently called "Automation & Infrastructure" and "Contributor Guidance", to play around with this. I am only able to create private projects so unless/until and admin goes and makes them public, I can't link to them. I will add some screenshots in a comment.

These projects replace the single 2024 New Year's Cleaning meta-issue which is only find-able because its pinned. But we know that people don't always look at the pinned issues. I don't think it would be any harder to direct people to projects, and projects are much better at organizing work than checkbox lists in issues.

I picked these two because they're much more specific and obvious than trying to figure out whether and how to carve up the spec work into projects. I figure we can consider that if these smaller, more focused projects prove helpful.

Questions and Answers

@lornajane

I am not sure what can't be achieved with good issue tagging however?

The labels/tags don't map well to projects. The Automation & Infrastructure project has some combination of Process, Housekeeping, and Schema labels, while the Contributor Guidance is mostly Process and Housekeeping.

We could improve the Proess/Housekeeping split, but really this is about focusing and prioritizing work, which is a transient condition, while labels work well for stable conditions like categorizing. We'd like to not keep changing the labels around, but opening, finishing, and closing a project is a natural thing. I think this the main answer to this question.

We also just removed several past rounds of using labels to do project tracking, several of which pre-dated GitHub projects. Everyone agreed that those labels were good to retire. No one argued for keeping that project-tracking system. I don't think that's the kind of tagging you were asking about, but it's worth noting that we just decided to get rid of them.

@earth2marsh

It sounds like issues are potential work and projects are planned/prioritized work?

They're a way to visualize the priority/progress that isn't just tagging, no? I think they give better insight into the sprawling backlog of issues that could be picked up or are in progress.

Yes, this feels right. Labels categorize potential work, Projects say "this is the work, from whatever categories, that people with X skills/access should prioritize right now." It's much nicer than making priority labels, which I've tried in many projects. None of those priority-labeling systems were used reliably.

What's not working about the current system?

I've been making a point to gather high-priority PRs and issues and put them in the meeting agenda or even send then in Slack directly to folks who need to act on them. This has been OK because:

1. Everyone agrees that we should clear out the old PR backlog and define our processes more clearly, so no one has been pushing back on my priorities
2. There are a very small number of people (essentially 2) who have been able to merge spec PRs in the last few months. Me sending them stuff in slack is feasible (and not yet too irritating, apparently - sometimes people even thank me :-)
3. I show up to the meetings (or in slack conversations) and explain the status and context of things, so folks don't have to dig around and remember why we're looking at something.

However, I've kind-of dominated the meeting agendas recently, which doesn't feel collaborative or welcoming. With a project, more people can impact the priorities, and the context is more clear.

A good thing about the meeting agenda process is that anyone can put anything on the agenda. A problematic thing is that there's no way to see how those items fit into the larger context, unless someone makes a point of organizing them.

For example, last week I made a point of organizing a bunch of security-related issues into a prioritized list by incorporating comments from others into the issue/PR list I had already started. Otherwise we would have jumped around a lot more, and probably missed the opportunity to look at closely related PRs that did not have a champion that week. As it was, we got a lot done in this past meeting because the work was organized.

As far as Slack usage goes, we will soon have more active TSC members (and probably maintainers and triage as well). It won't scale for me to keep messaging specific people to look at manually-curated lists.

How would this change our weekly meeting process?

After the SIG updates, we could look at current projects to see what needs attention during the meeting. Perhaps we would first look at agenda comments for folks asking to add issues/PRs to projects. Then we'd look at each current project and decide how much of the meeting to devote to each one. We could look at issues/PRs that aren't part of a project either before or after the ones that are (probably depending on whether most work goes through projects, or only very specific things).

Discussion would probably flow more smoothly if we group related topics by project, and it would be more clear when a whole area is being starved of time when we keep not getting to a project each week. We would also be less likely to starve an entire area just because no one is being noisy about it for a few week if we look over the projects each week.

[lornajane]

I think my main hesitation is that this adds another thing that also needs to be maintained (the individual issues need updates whether we do this or not), and this project hasn't been traditionally strong in project management. It's not a real objection that projects are a bad idea, but I don't have confidence that we can sustainably run with this approach for the long term.

How about spinning up projects for specific things, and trying to keep a lid on the number of active ones at any one time? So the majority of issues are standalone and managed ongoingly - but we can get a few people and focus on a batch of things like those markdown updates, or the security issues, for a few weeks, using a project?

[handrews]

@lornajane

How about spinning up projects for specific things, and trying to keep a lid on the number of active ones at any one time?

I am specifically proposing two projects, and only two projects, both of which should be completed in the near term, as they are intentionally chosen due to being sets of things blocking our progress on specification work.

[handrews]

If someone with permissions could make the two projects I've created public, it would be a lot easier to have this discussion. I do not have permissions to make them public. (It might be that this can't be done, I'm really not sure.)

@lornajane as for this:

I think my main hesitation is that this adds another thing that also needs to be maintained... but I don't have confidence that we can sustainably run with this approach for the long term.

I have 100% confidence that I'm not going to continue having time to do the project manager-ish work that I've been doing 😅 . So I guess the question is whether that effort needs to be replaced. It might not, which would not bother me. It might have been nice-to-have but not essential, or maybe we're reaching more of a steady state so there just won't be as much. If that's the case, I'm perfectly happy to drop the idea of using GitHub Projects.

But otherwise, short of OAI hiring a project manager, GitHub Projects will make it much easier for multiple people to share the PM work load. There might be other options, but starting with the one integrated into our main tool seems best to me.

Still, if we don't need to replace the sort of issue curation and pointing specific folks at PRs/issues that need action from them that I've been doing, then we can just close this out. GitHub Projects will still be there if we decide we need them later.

[lornajane]

We need issue curation and direction, the work you have done in this project is so valuable and I wish you could just hang out here and make it work like this forever! My only concern with adding process is that while people might keep things going with issues (at a lower standard than we have recently enjoyed!), projects feel like another thing, and they can easily be missed and end up being outdated. I like the idea of the two smaller projects though, and hopefully I'll turn out to be totally wrong with my reservations :) Consider my reservations addressed, let's try projects.

[handrews]

Thanks, @lornajane – I've asked @webron to make the two projects I created public (or create new public projects that I can populate) since no one else seems to have the necessary permissions.

[handrews]

@webron has made the projects public, so we can close this issue and give them a try :-)