Document existing project automations and plan implementation of new ones (#3042)

dhruvkb · AetherUnbound · obulat · web-flow · commit c25106b89cc3 · 2023-11-15T10:27:02.000+04:00
Co-authored-by: Madison Swain-Bowden &lt;bowdenm@spu.edu&gt;
Co-authored-by: Olga Bulat &lt;obulat@gmail.com&gt;
diff --git a/documentation/meta/index.md b/documentation/meta/index.md
@@ -6,6 +6,7 @@
 github_contribution_practices
 dev_flow
 maintainer_tasks
+project_boards/index
 ci_cd/index
 decision_making/index
 documentation/index
diff --git a/documentation/meta/project_boards/discussions.md b/documentation/meta/project_boards/discussions.md
@@ -0,0 +1,34 @@
+# Discussion project: Openverse Discussions
+
+The [Openverse Discussions](https://github.com/orgs/WordPress/projects/79)
+project board tracks project proposals and implementation plans through their
+lifecycle, as they move from pending to accepted. This board tracks issues and
+pull requests so it has workflows for both kinds of events.
+
+## Event automations
+
+### PR is created
+
+If a new PR is created with either of the following labels, it is automatically
+added to the project board.
+
+- 🧭 project: implementation plan
+- 🧭 project: proposal
+
+- [Built-in workflow](https://github.com/orgs/WordPress/projects/79/workflows/8235206)
+
+### Issue/PR is added to the project
+
+The status of this issue/PR will be set to "Pending proposal" and thus, it will
+be included under the "Pending proposal" column.
+
+- [Built-in workflow](https://github.com/orgs/WordPress/projects/79/workflows/7503192)
+
+### Issue/PR is closed/merged
+
+If an issue/PR is closed, it moves into the "Accepted" column. This is not
+affected by whether the issue was closed as resolved or as discarded or if the
+PR was merged or closed without merge.
+
+- [Built-in workflow (closed)](https://github.com/orgs/WordPress/projects/79/workflows/7304449)
+- [Built-in workflow (merged)](https://github.com/orgs/WordPress/projects/79/workflows/7304450)
diff --git a/documentation/meta/project_boards/index.md b/documentation/meta/project_boards/index.md
@@ -0,0 +1,25 @@
+# Project boards
+
+Openverse project management consists of four project boards,
+[one for issues](https://github.com/orgs/WordPress/projects/75),
+[one for PRs](https://github.com/orgs/WordPress/projects/98),
+[one for project threads](https://github.com/orgs/WordPress/projects/70) and
+[one for discussions](https://github.com/orgs/WordPress/projects/79).
+
+Issues and PRs are added to these boards and move across columns based on their
+status. Automations to move these cards can be broadly classified into two
+types:
+
+- automations built into the GitHub Projects UI
+- custom automations run as GitHub Actions workflows
+
+Read on to know more about these boards and the automations that apply to them.
+
+```{toctree}
+:titlesonly:
+
+issues
+prs
+projects
+discussions
+```
diff --git a/documentation/meta/project_boards/issues.md b/documentation/meta/project_boards/issues.md
@@ -0,0 +1,52 @@
+# Issues project: Openverse Backlog
+
+The [Openverse Backlog](https://github.com/orgs/WordPress/projects/75) project
+board tracks all issues through their lifecycle, as they move from creation to
+completion. This board does not track any pull requests, so all workflows for
+this board are tied to events occurring for issues.
+
+## Event automations
+
+### Issue is created
+
+If a new issue is created in the
+[`WordPress/openverse`](https://github.com/WordPress/openverse/) repository, it
+is automatically added to the project board provided it does not contain any
+label with the text "project".
+
+```{note}
+This workflow also sets the Priority custom field in the issue so that we can
+create a kanban-board view based on priority.
+```
+
+- [Custom workflow](https://github.com/WordPress/openverse/blob/main/.github/workflows/new_issues.yml)
+
+### Issue is closed
+
+If an issue is closed, it moves into the "✅ Done" column. This is not affected
+by whether it was closed as resolved or as discarded.
+
+- [Built-in workflow](https://github.com/orgs/WordPress/projects/75/workflows/6899392)
+
+### Issue is reopened
+
+If a previously closed issue is reopened, it goes back to the "📋 Backlog"
+column. That is because it will need to be re-prioritized alongside other
+ongoing work and moved to "📅 To do" when it can be worked on again.
+
+- [Built-in workflow](https://github.com/orgs/WordPress/projects/75/workflows/8193212)
+
+### Issue is added to the project
+
+The status of this issue will be set to "📋 Backlog" and thus, it will be
+included under the "📋 Backlog" column.
+
+- [Built-in workflow](https://github.com/orgs/WordPress/projects/75/workflows/6899490)
+
+### Issue is closed and inactive
+
+If an issue is closed, and has not been updated in 8 days, it will automatically
+be archived from the project board. This ensures that the board is cleared in
+time for the weekly development chat.
+
+- [Built-in workflow](https://github.com/orgs/WordPress/projects/75/workflows/8222891)
diff --git a/documentation/meta/project_boards/projects.md b/documentation/meta/project_boards/projects.md
@@ -0,0 +1,32 @@
+# Project project: Openverse Project Tracker
+
+The [Openverse Project Tracker](https://github.com/orgs/WordPress/projects/70)
+project board tracks project tickets through their lifecycle, as they move from
+not being started to being successful.
+
+Project threads are issues, so all workflows for this board are tied to events
+occurring for issues, however the issue status has slightly different
+interpretation when the issue is a project thread.
+
+## Event automations
+
+### Thread is created
+
+If a new issue is created with the label "🧭 project: thread", it is
+automatically added to the project tracker project board.
+
+- [Built-in workflow](https://github.com/orgs/WordPress/projects/70/workflows/6730708)
+
+### Thread is closed
+
+If a project thread is closed, it moves into the "Shipped" column. These
+projects are considered shipped but not successful (yet).
+
+- [Built-in workflow](https://github.com/orgs/WordPress/projects/70/workflows/6373102)
+
+### Thread is added to the project
+
+The status of the project thread will be "Not Started" and thus, it will be
+included under the "Not Started" column.
+
+- [Built-in workflow](https://github.com/orgs/WordPress/projects/70/workflows/6730724)
diff --git a/documentation/meta/project_boards/prs.md b/documentation/meta/project_boards/prs.md
@@ -0,0 +1,70 @@
+# PR project: Openverse PRs
+
+The [Openverse PRs](https://github.com/orgs/WordPress/projects/98) project board
+tracks all PRs through their lifecycle, as they move from creation to merge (or
+closure). This board does not track any issues, so all workflows for this board
+are tied to events occurring for pull requests.
+
+```{note}
+GitHub treats PRs as a subcategory of issues, all issue related automations have
+PR counterparts but not vice versa.
+```
+
+```{caution}
+The PRs board is currently private. It may be made public in the future.
+```
+
+## Event automations
+
+### PR is created
+
+If a new PR is created, it is automatically added to the project board. PRs from
+the infrastructure repository are also added to the board.
+
+- [Built-in workflow (monorepo)](https://github.com/orgs/WordPress/projects/98/workflows/8656692)
+- [Built-in workflow (infra)](https://github.com/orgs/WordPress/projects/98/workflows/8674459)
+
+### PR is closed or merged
+
+If a PR is closed or merged, it moves into the "Merged" column. Understandably,
+this is slightly misleading for PRs that were closed unmerged.
+
+- [Built-in workflow (closed)](https://github.com/orgs/WordPress/projects/98/workflows/8656664)
+- [Built-in workflow (merged)](https://github.com/orgs/WordPress/projects/98/workflows/8656665)
+
+### PR is reopened
+
+If a previously closed, but unmerged, PR is reopened, it goes back to the "Needs
+Review" column, even if had been reviewed before being closed.
+
+- [Built-in workflow](https://github.com/orgs/WordPress/projects/98/workflows/8674442)
+
+### PR is added to the project
+
+The status of this PR will be set to "Needs review" and thus, it will be
+included under the "Needs review" column. This is not affected by whether the PR
+is actually ready or in a draft state.
+
+- [Built-in workflow](https://github.com/orgs/WordPress/projects/98/workflows/8674448)
+
+### PR is closed and inactive
+
+If a PR is closed (includes merged) and has not been updated in two weeks, it
+will automatically be archived from the project board. This is different from
+the archival threshold of the issues board (8 days).
+
+- [Built-in workflow](https://github.com/orgs/WordPress/projects/98/workflows/8674454)
+
+### PR has required approvals
+
+If a PR has the required number of approvals, it moves into the "Approved"
+column. PRs with fewer approvals than the merge requirement are not affected.
+
+- [Built-in workflow](https://github.com/orgs/WordPress/projects/98/workflows/8674451)
+
+### PR has requested changes
+
+If a PR was reviewed with change requests, it moves into the "Changes requested"
+column. Even one change request qualifies the PR for this automation.
+
+- [Built-in workflow](https://github.com/orgs/WordPress/projects/98/workflows/8674445)
diff --git a/documentation/projects/proposals/project_improvement/20230913-project_proposal_project_improvements.md b/documentation/projects/proposals/project_improvement/20230913-project_proposal_project_improvements.md
@@ -0,0 +1,96 @@
+# 2023-09-13 Project proposal: Project board improvements
+
+**Author**: @dhruvkb
+
+## Reviewers
+
+- [x] @AetherUnbound
+- [x] @obulat
+
+## Project summary
+
+The end-goal of this project is to have a comprehensive set of boards where one
+can track all aspects of work being done in Openverse. This includes issues, PRs
+and project discussions. These boards should have lots of different views, for
+different purposes, and these views should be standardised and documented.
+
+Each of these projects should be highly automated, where minimal effort is
+needed to keep these boards synced to reality. Most human actions should be
+complemented by automations that can sync the effects of the event to the board.
+These should be a combination of built-in and custom workflows, where custom
+workflows are consistent, well-tested and maintainable.
+
+## Goals
+
+This project should do both of the following things:
+
+- enhance our productivity by reducing a lot of work required to keep these
+  projects up to date
+- increase our accountability by helping us stay on top of our work and also
+  being aware of what others in the team are working on
+
+## Requirements and success
+
+The following are requirements & success criteria for the project automations:
+
+- all issues and PRs are automatically added to the relevant project boards
+- all cards are in the right columns as per their status
+- rarely, if ever, do we need to manually move cards to the right columns
+  (except for moving cards from "📋 Backlog" to "📅 To do" to prioritise them)
+- all custom automations are in a single place and are easy to maintain
+- all automations are documented
+
+The following are requirements & success criteria for the project views:
+
+- views are created based on clear utility in helping maintainers track work
+- views are clearly labelled, and it's known which view to use for what purpose
+- all views, and their utilities, are documented
+
+## Participants
+
+The boards are primarily an internal tool for maintainers and to some extent, an
+external tools for contributors (to find potential inroads to contribute) and
+project leadership (to gauge activity and progress).
+
+### Expectation for maintainers
+
+- Knowing what issues everyone, including themselves, is working on at a given
+  time.
+- Having a clear idea of what issues need to be worked on after the current
+  issues on hand are resolved.
+- Being able to find critical or high priority issues that haven't been
+  addressed.
+- Knowing the status of their own PRs.
+- Identifying PRs that require additional reviews.
+
+### Expectation for contributors
+
+- Finding help wanted or good first issues that are not already assigned or
+  being worked on by someone else.
+- Knowing that their PRs will be noticed, reviewed and merged in a timely
+  manner.
+
+### Expectation for project leadership
+
+- While project leadership are not directly concerned with the day-to-day issues
+  and PRs, they should be able to see a steady movement of cards from
+  left-to-right.
+- The project discussion boards are more relevant to the leadership.
+
+## Miscellaneous
+
+This project should not have any components related to infrastructure, a11y or
+marketing as it is internal. Several new workflows will be defined which will be
+executed on GitHub Actions.
+
+## Required implementation plans
+
+The following implementation plans would be required:
+
+1. improvements to existing, restoration of previous and creation of new
+   automations
+   ([plan](/projects/proposals/project_improvement/20230914-implementation_plan_project_automations.md))
+2. documentation of existing and creation of new useful views for project boards
+   (plan)
+3. discussion of ideas related to the project and discussion boards as that has
+   not been covered in #1.
diff --git a/documentation/projects/proposals/project_improvement/20230914-implementation_plan_project_automations.md b/documentation/projects/proposals/project_improvement/20230914-implementation_plan_project_automations.md
diff --git a/documentation/projects/proposals/project_improvement/index.md b/documentation/projects/proposals/project_improvement/index.md
