What's the point of project thread updates?

[sarayourfriend]

I am not really sure that I understand the point of the project thread updates. This one, for example does not add anything that couldn't be understood by reading the issue body, which is where I would personally prefer to go looking for stuff. Writing manual updates requires copying and pasting links that are already in the project thread issue body, forcing people to duplicate things if they want to be thorough. I have no idea what else I would add to that update, it literally says everything that you could possibly need to know about the status of the project, all of which is evident from the body of the issue.

I thought about adding a project update yesterday, before I received a reminder to add one today from the MSR, but I couldn't think of anything. I only added one to avoid getting pinged to add one again next week.

Are these reminders perhaps only needed on project threads that haven't had activity or any updates in the last two weeks? A checklist of what has been completed is tedious and inane, borderline useless information, assuming we are updating the project thread issue bodies and maintaining milestones appropriately. If that information isn't be updated and maintained or can't because the project doesn't use them for some reason, I can see a manual update being useful. But for regular development projects I find the current process tedious and redundant.

[dhruvkb]

Posting updates only makes sense if

• there is a blocker that needs to be resolved so that the project can move forward
• there is a notification about the project that needs to be propagated to the team

Unless there is something to be done or known, the update shouldn't be necessary.

[sarayourfriend]

@WordPress/openverse-maintainers Does anyone else have input to give here? I really like @dhruvkb's answer and would like to update the MSR instructions to reflect that, so long as no one objects.

[AetherUnbound]

I will be responding to this discussion this week.

[AetherUnbound]

I, personally, still appreciate these updates even though they duplicate information in the issue body. While updating the issue body is excellent and we should continue to do so as a project evolves to make it easiest to find all the related documents, what the issue body does not capture which regular, periodic updates do is the timeline for various changes. One could piece this together by looking at all of the edits made to the issue body, or trying to track the timeline of when certain items were linked to the issue in the GitHub timeline, but that ends up being much more tedious than looking across update posts. Particularly if the update posts have a regular format, they can skimmed quickly and could be useful in determining how long certain actions took when working on a project, what might have taken more or less time than expected, what had been accomplished while someone was out on AFK, etc.

In short, the update posts may provide redundant information for what was accomplished but they provide novel information relating to when it was accomplished in an easy-to-view format within the project issue. I support keeping them as-is.

[zackkrida]

Agreed on the importance of having a basic, if redundant, timeline of a project encapsulated in the comments. These projects are also historical records, for the community, for stakeholders, not just us, and it's important to keep in mind.

[zackkrida]

These updates were carried over almost verbatim from the previous project process, which existed outside of GitHub. There, it made much more sense to link to issues. Here, I don't think that lists of issues would serve us well, but I do think a fortnightly update on project threads would be very useful if we change our approach.

I agree that "This one, for example" doesn't provide a lot of value. However with some better guidelines for project authors, I think an update on this date for this project could have been informative if it touched on some things:

• Acknowledge the project process was approved (and link to it)
• Mention that a new design iteration was shared and that we're addressing considerations about audio and so on
• Mention that the sensitive terms list implementation plan was approved, perhaps even mentioning/pinging folks your questions about delegating the work
• Mentioning anything relating to other upcoming work, for example that you intended to create and work on the "Filtering and designating sensitive results in the API" issues once that plan was approved

I think in aggregate, those things become quite useful in painting a snapshot of where the project stands. If a stakeholder asks us about how the project is doing, we instantly have a link for them to share. Yes, it's a bit redundant, but it also provides an opportunity for project leads to reflect and take stock of the project they're working on.

I'm open to only requiring these only if the project lead hasn't provided an update to the project thread in two weeks. I also think the pings should be automated and removed from MSR which we could do quite easily. Regarding those, I'd be curious what format folks prefer:

• List all projects in need of update and @ the author of each one in a weekly Slack message
• A GitHub comment on the project thread (@author please update this thread using the template`) [this is my preferred, I think]
• Something else

My vote for next steps would be:

• Improve the project update template and only require updates if the assignee hasn't commented on the project in two weeks
• Identify the preferred notification type for the team
• Create a GitHub cron action to ping project thread assignees in the preferred format

[sarayourfriend]

I created an example project board here: https://github.com/orgs/WordPress/projects/92/views/1

The only thing necessarily better about using a project board rather than a milestone for the entire project is that the project board can include non-issue items as well as cross-repository items like infrastructure issues. The latter seems especially useful.

[AetherUnbound]

I like the idea of automating as much as possible here, and of individual board per-project (I wonder if we could even consolidate this to a single board, with each view being a filtered view for a different project? Would that be any easier? I don't think there are any limits to the number of projects we can have though, so maybe that would be a more time-consuming approach).

One thing that I'm still not sure is captured easily here is the timeline after the fact. Perhaps I'm putting an outsized emphasis on this particular aspect, but for the other project threads we've had which were not on GitHub, I found it quite helpful that there was a clear timeline of all the issue we worked on. We also frequently added commentary to those biweekly updates; for example, with the DAG stability/refactor work we also made notes on when certain DAGs were enabled/disabled. This information is likely all captured elsewhere (issue comments, PRs, discussions, etc.), but having it aggregated at the project thread level prevents having to dig through issues oneself long after the project is complete. The project board and milestones also don't necessarily capture this, since they still represent the state they're viewed at not a snapshot in time.

It may be that this sort of view/summary is not as useful to other maintainers or folks viewing our project as it is to me, and if that's the case then I'm happy to adjust to what other maintainers would prefer.

[stacimc]

Comments on the project thread for things that are important at the project level (things like enabling/disabling DAGs as you mention, and project-level blockers and announcements) are useful to me as well. It does seem like that's very project-dependent and probably not necessary every two weeks for every project, but I would still be fine with a biweekly reminder if other folks think it's useful.

For the timeline, I personally find a milestone easier to read and more accurate. When I write weekly updates I just list the issues that were completed that week, but not necessarily in order and mostly just as links. If you view the Closed tab on a milestone you can see what issues were closed in exact order, with more information visually displayed about each issue (including merge date, whether a PR was merged or the issue was simply closed, and assignee).

[AetherUnbound]

Unfortunately, it seems like even milestones may not be an ideal solution 😞 Our move to the monorepo and transfer of issues has removed all of the transferred issues from the old milestones, since those exist only on the old repo: example empty Provider DAG Stability milestone. I know it's unlikely that we're going to move repos again in the future, but it's worth noting that presence within a milestone is not necessarily an immutable way to view project history.

[stacimc]

It looks like we could have preserved the milestones by first making them present in the openverse repo before migrating the issues.

[stacimc]

I also find writing project updates to be somewhat tedious manual duplication of links and do not personally find them particularly useful. As far as establishing a timeline, weekly updates only loosely group issues/tasks without specific dates.

I do find the project updates useful in the scenarios @dhruvkb listed, which I think very broadly describes the sorts of updates @zackkrida has in mind as well.

Forgive me if I'm forgetting already established process, but is there a plan to create milestones for each project and place the issues in them? That allows us a convenient link to view all issues at once, the ability to re-order them, and clearly see completion dates/etc.

[dhruvkb]

I'm all for each project having a milestone, considering how the lack of cross-repo milestones was a one of the main drives for the monorepo.

[krysal]

I'm against removing the fixed periodic updates of the projects for the very reasons that @zackkrida and @AetherUnbound stated. Those should not be just a list of the completed issues. I think of them as a sort of executive summary for folks not actively participating in the project and wanting to get informed at some point, but more technical given that they're very close to the work. Given that this kind of update is more nuanced I also don't think it can get lifted to an automated workflow just to list done/next issues to work on, but agree 100% with automating the ping to leads to post the update.

[zackkrida]

Thank you all for your input here @WordPress/openverse-maintainers, and @sarayourfriend for raising it!. It's clear that our current approach to project updates can be improved to better serve our needs while reducing redundancy and tedium. The discussion has helped me refine what value these updates serve. I'd like to propose the following:

1. Change update contents:
   • Remove the template for project updates. There's not really a compelling reason to include a header with the word "update" and the data, both of those are already apparent. Instead, we'll include examples of more and less-effective project updates in our documentation. Updates will be comments on the project thread which provide a description of changes made to the project. Here's some examples now:
     • "The project plan was approved and merged. It's now referenced in the project thread. I created two issues for the necessary implementation plans which will be assigned in next week's community meeting"
     • "The project's primary developer has gone on extended AFK. I've updated the project status to blocked while we discuss re-prioritizing the project"
     • "The software vendor has confirmed we can move forward at the discounted rate for their Saas product. I've unblocked the project and created 4 new issues which are linked in the project body"
   • Add documentation to encourage regular updates to the project thread body. This is where document and issue links should be added.
2. Change responsibility for updates:
   • Update documentation to indicate any member of the project can and should update the project. If you author and merge a significant part of a project, or make any update to a project that folks should know about, leave a comment in the project thread.
   • If a project thread has not been commented on in two weeks, the project lead will be pinged via a GitHub comment on the thread requesting an update.
   • Remove all manual MSR pings

How do these changes sound? They're meant to solve the following problems:

• Updates can be redundant and time-consuming
• Updates place undue burden on project leads
• No activity on a project in two weeks suggests that a project may be blocked, stalled, or ignored
• Stakeholders (including me) need a quick place to see the 'latest' happenings on a project, including after periods of long or short-term AFK

@WordPress/openverse-maintainers Please object to this plan or request changes by 5/9, otherwise I'll move forward and create issues for the necessary changes.

[zackkrida]

Apologies, @fcoveram! I've added you to that group. Let me know if that results in you getting undesired or inactionable pings and we can find a better approach.

[zackkrida]

Can we include clearer expectations for milestone usage?

@sarayourfriend this is a great point. My inclination is to start with the first use case you described, implementation milestones. That's much more resilient and useful than keeping manual issue lists in sync inside of an issue body.

I'll include this point in the issues for documentation I create once we're done here.

[fcoveram]

Apologies, @fcoveram! I've added you to that group.

No worries! Thanks for adding me.

Let me know if that results in you getting undesired or inactionable pings and we can find a better approach.

Sure. I can always unsubscribe myself from tickets, so pings should not be a problem.

[stacimc]

These changes sound good to me as well. +1 for implementation milestones instead of issue lists in the project issue, too!

[AetherUnbound]

This all sounds excellent, I'm on board!