Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update project thread update docs #2329

Merged
merged 5 commits into from
Jun 8, 2023
Merged

Update project thread update docs #2329

Changes from 1 commit
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
30650e0
Update project thread update docs
zackkrida Jun 5, 2023
fee6ab2
Update documentation/projects/planning.md
zackkrida Jun 8, 2023
d4f2d93
Update documentation/projects/planning.md
zackkrida Jun 8, 2023
201cc04
Update documentation/projects/planning.md
zackkrida Jun 8, 2023
d374eb1
Formatting after applying suggestions in GitHub UI
zackkrida Jun 8, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
87 changes: 33 additions & 54 deletions documentation/projects/planning.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
zackkrida marked this conversation as resolved.
Show resolved Hide resolved
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!
zackkrida marked this conversation as resolved.
Show resolved Hide resolved
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

<!--- A very brief, nearly single line summary giving a clear description of the
project. Example: We continue to ship frontend PRs and are 75% complete with the
milestone. Blocked on design approval from community contributors for the new
signup flow. -->

### Done

<!-- List recently-completed tasks here -->

- [x]

### Next

<!-- List this week's tasks here. We can assume that the majority of tasks are
existing GitHub issues assigned to a contributor. -->

- [ ]

### Blockers

<!-- List any blockers for the week: any upcoming concerns which need to be
addressed. Please @ anyone who may be qualified to resolve these blockers. The
more proactive you are about potential solutions the quicker we can make
eliminate these 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.
zackkrida marked this conversation as resolved.
Show resolved Hide resolved

## Project Lifecycle

Expand Down Expand Up @@ -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.

Expand Down Expand Up @@ -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
Expand All @@ -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.

Expand All @@ -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
Expand Down Expand Up @@ -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
Expand Down