From 30650e009d2fc49f7eaa85295d5c52c4350e3ce0 Mon Sep 17 00:00:00 2001 From: Zack Krida Date: Mon, 5 Jun 2023 17:31:51 -0400 Subject: [PATCH 1/5] Update project thread update docs --- documentation/projects/planning.md | 87 ++++++++++++------------------ 1 file changed, 33 insertions(+), 54 deletions(-) diff --git a/documentation/projects/planning.md b/documentation/projects/planning.md index cec690f747c..3f6a258872b 100644 --- a/documentation/projects/planning.md +++ b/documentation/projects/planning.md @@ -71,57 +71,36 @@ relevant step of the process is complete. ## Providing project updates -At all stages of a project (except for `Not Started` projects), fortnightly -public updates are the best way for Openverse contributors and maintainers to -understand the health of a project. Importantly, these updates allow us to -allocate more time or material resources to projects that need them before work -stalls completely. - -Project updates should be left as comments in the project threads. Even if the -update is "the project is blocked." or "No developments this week.", the updates -should still be posted. This removes ambiguity for folks visiting the project, -avoiding questions like "I don't see an update this week; is it being worked on -or not?" +For all active projects (anything that isn't in the `Not Started`, `Completed`, +and `On Hold` statuses), fortnightly public updates are the best way for +Openverse contributors and maintainers to understand the health of a project. +Importantly, these updates allow us to allocate more time or material resources +to projects that need them before work stalls completely. They also allow for +identifying projects that have stalled and may need special attention, if they +haven't seen an update in some time. + +Project updates should be left as comments in the project threads by the project +lead or anyone working on a project. If you merge or a significant update to a +project, or identify a bug that impacts an open project, please leave an update! +Even if the update is "the project is blocked." or "No developments this week.", +the updates should still be posted. This removes ambiguity for folks visiting +the project, avoiding questions like "I don't see an update this week; is it +being worked on or not?" These updates are useful for folks checking in on a project but also for the project lead. It's an opportunity to _reflect on_ the status of the project and any blockers, or successes to be shared. -### Update Template +Here are some real-life examples of useful project updates: -Here is an update template to be followed for every project update. Some update -information will be specific to the current phase of the project. In the future -we might develop different templates for each project phase. For now, we'll see -which conventions emerge as we begin using this process. +- https://github.com/WordPress/openverse/issues/377#issuecomment-1566296377 +- https://github.com/WordPress/openverse/issues/392#issuecomment-1574444963 +- https://github.com/WordPress/openverse/issues/433#issuecomment-1560213117 -```md -## Update YYYY-MM-DD - - - -### Done - - - -- [x] - -### Next - - - -- [ ] - -### Blockers - - -``` +There are automated reminders configured for these updates via a +[daily GitHub action](https://github.com/WordPress/openverse/blob/main/.github/workflows/project_thread_update_reminders.yml) +which comments on the project thread. The project lead is reminded (via a bot +comment on the project) to provide an update. ## Project Lifecycle @@ -341,10 +320,10 @@ necessary. Finally, the implementation plan is merged into the repo. Project contributors create GitHub issues for all of the work identified in the implementation plan. -This process can be quite time-consiming for large projects. Generally, it makes +This process can be quite time-consuming for large projects. Generally, it makes sense to create issues in the order which they must be completed; this allows work to begin if, for some reason, there is delay in creating issues for work at -the end of a project. It also however makes sense to priorize issues that are +the end of a project. It also however makes sense to prioritize issues that are "good first issues" and "help wanted" issues contributors outside of the core maintainers can help with. @@ -409,7 +388,7 @@ and riskier, due to increased review overhead, than going step-by-step. Code reviewers should focus primarily on the technical aspects of the implementation required by the issue. At times, during the course of a project, -unforeseen amiguities will discovered during implementation and sometimes an +unforeseen ambiguities will discovered during implementation and sometimes an alarm bell must be rung. However, these should be reserved for issues that will cause long-term harm to the project. Merely disagreeing with a particular detail of the project's implementation details is not sufficient for holding up a PR @@ -430,7 +409,7 @@ difficult or much more time-consuming. ### Delivery (`status: Shipped`) -After shipping, the project enters a period of evaluation. We do this to meaure +After shipping, the project enters a period of evaluation. We do this to measure the success of the project and determine if it achieved the desired goal, but also to reflect on and make improvements to our own team processes. @@ -443,14 +422,14 @@ changes in traffic to Openverse, as examples. During this phase, the project lead should report updates on these metrics regularly to help the team make a determination about changing the project status to `Success` or `Rollback`. Please make these updates on the project -thread using the standard [update template](#update-template). Rolling back a -project is not a decision we should take lightly, and by providing regular -updates project leads can prevent this action from seeming like a surprise or a -rash decision to others. +thread using the [standard suggestions](#providing-project-updates). Rolling +back a project is not a decision we should take lightly, and by providing +regular updates project leads can prevent this action from seeming like a +surprise or a rash decision to others. Frequent feedback on the success criteria can also help contributors come up with fast-follow improvements or modifications to the feature that may prevent -rollback. Project leads should itentify these types of improvements in their +rollback. Project leads should identify these types of improvements in their project thread updates as well. After the designated evaluation period we will make a decision about rolling @@ -489,7 +468,7 @@ all projects and some additional metadata: - The status of the project At the time of writing, projects are added to this board manually. In the future -we may develop automatations, for example one which automatically adds any issue +we may develop automations, for example one which automatically adds any issue with the "project" label to this board. This board should be checked regularly as a 'dashboard' to answer some critical From fee6ab26daad72e98bdde54b529a1d5942e90ee1 Mon Sep 17 00:00:00 2001 From: Zack Krida Date: Thu, 8 Jun 2023 10:50:59 -0400 Subject: [PATCH 2/5] Update documentation/projects/planning.md Co-authored-by: sarayourfriend <24264157+sarayourfriend@users.noreply.github.com> --- documentation/projects/planning.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/documentation/projects/planning.md b/documentation/projects/planning.md index 3f6a258872b..f9507bbb758 100644 --- a/documentation/projects/planning.md +++ b/documentation/projects/planning.md @@ -75,8 +75,7 @@ For all active projects (anything that isn't in the `Not Started`, `Completed`, and `On Hold` statuses), fortnightly public updates are the best way for Openverse contributors and maintainers to understand the health of a project. Importantly, these updates allow us to allocate more time or material resources -to projects that need them before work stalls completely. They also allow for -identifying projects that have stalled and may need special attention, if they +to projects that need them before work stalls completely. They also help identify projects that have stalled and may need special attention, if they haven't seen an update in some time. Project updates should be left as comments in the project threads by the project From d4f2d9347d0f5ab6e5b2c4d9dd50bc6fd2fa6f6a Mon Sep 17 00:00:00 2001 From: Zack Krida Date: Thu, 8 Jun 2023 10:51:13 -0400 Subject: [PATCH 3/5] Update documentation/projects/planning.md Co-authored-by: sarayourfriend <24264157+sarayourfriend@users.noreply.github.com> --- documentation/projects/planning.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/documentation/projects/planning.md b/documentation/projects/planning.md index f9507bbb758..5a8cf7e73bf 100644 --- a/documentation/projects/planning.md +++ b/documentation/projects/planning.md @@ -79,8 +79,7 @@ to projects that need them before work stalls completely. They also help identif haven't seen an update in some time. Project updates should be left as comments in the project threads by the project -lead or anyone working on a project. If you merge or a significant update to a -project, or identify a bug that impacts an open project, please leave an update! +lead or anyone working on a project. If you merge a significant PR related to the project or identify a bug that impacts an open project, please leave an update! Even if the update is "the project is blocked." or "No developments this week.", the updates should still be posted. This removes ambiguity for folks visiting the project, avoiding questions like "I don't see an update this week; is it From 201cc04d276fdb39039a26a2f1f011989d7a827e Mon Sep 17 00:00:00 2001 From: Zack Krida Date: Thu, 8 Jun 2023 10:51:25 -0400 Subject: [PATCH 4/5] Update documentation/projects/planning.md Co-authored-by: sarayourfriend <24264157+sarayourfriend@users.noreply.github.com> --- documentation/projects/planning.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/documentation/projects/planning.md b/documentation/projects/planning.md index 5a8cf7e73bf..68fc1c361ad 100644 --- a/documentation/projects/planning.md +++ b/documentation/projects/planning.md @@ -97,8 +97,7 @@ Here are some real-life examples of useful project updates: There are automated reminders configured for these updates via a [daily GitHub action](https://github.com/WordPress/openverse/blob/main/.github/workflows/project_thread_update_reminders.yml) -which comments on the project thread. The project lead is reminded (via a bot -comment on the project) to provide an update. +that comments on the project thread, prompting the project lead to provide an update. ## Project Lifecycle From d374eb13daa73fe027934cd43bb76a62c59e4366 Mon Sep 17 00:00:00 2001 From: Zack Krida Date: Thu, 8 Jun 2023 10:52:55 -0400 Subject: [PATCH 5/5] Formatting after applying suggestions in GitHub UI --- documentation/projects/planning.md | 17 ++++++++++------- 1 file changed, 10 insertions(+), 7 deletions(-) diff --git a/documentation/projects/planning.md b/documentation/projects/planning.md index 68fc1c361ad..86a6c05909b 100644 --- a/documentation/projects/planning.md +++ b/documentation/projects/planning.md @@ -75,15 +75,17 @@ For all active projects (anything that isn't in the `Not Started`, `Completed`, and `On Hold` statuses), fortnightly public updates are the best way for Openverse contributors and maintainers to understand the health of a project. Importantly, these updates allow us to allocate more time or material resources -to projects that need them before work stalls completely. They also help identify projects that have stalled and may need special attention, if they +to projects that need them before work stalls completely. They also help +identify projects that have stalled and may need special attention, if they haven't seen an update in some time. Project updates should be left as comments in the project threads by the project -lead or anyone working on a project. If you merge a significant PR related to the project or identify a bug that impacts an open project, please leave an update! -Even if the update is "the project is blocked." or "No developments this week.", -the updates should still be posted. This removes ambiguity for folks visiting -the project, avoiding questions like "I don't see an update this week; is it -being worked on or not?" +lead or anyone working on a project. If you merge a significant PR related to +the project or identify a bug that impacts an open project, please leave an +update! Even if the update is "the project is blocked." or "No developments this +week.", the updates should still be posted. This removes ambiguity for folks +visiting the project, avoiding questions like "I don't see an update this week; +is it being worked on or not?" These updates are useful for folks checking in on a project but also for the project lead. It's an opportunity to _reflect on_ the status of the project and @@ -97,7 +99,8 @@ Here are some real-life examples of useful project updates: There are automated reminders configured for these updates via a [daily GitHub action](https://github.com/WordPress/openverse/blob/main/.github/workflows/project_thread_update_reminders.yml) -that comments on the project thread, prompting the project lead to provide an update. +that comments on the project thread, prompting the project lead to provide an +update. ## Project Lifecycle