From c25106b89cc3a2ac048ae9092540f11748b0b925 Mon Sep 17 00:00:00 2001 From: Dhruv Bhanushali Date: Wed, 15 Nov 2023 10:27:02 +0400 Subject: [PATCH] Document existing project automations and plan implementation of new ones (#3042) Co-authored-by: Madison Swain-Bowden Co-authored-by: Olga Bulat --- documentation/meta/index.md | 1 + .../meta/project_boards/discussions.md | 34 +++ documentation/meta/project_boards/index.md | 25 ++ documentation/meta/project_boards/issues.md | 52 ++++ documentation/meta/project_boards/projects.md | 32 ++ documentation/meta/project_boards/prs.md | 70 +++++ ...3-project_proposal_project_improvements.md | 96 ++++++ ...implementation_plan_project_automations.md | 273 ++++++++++++++++++ .../proposals/project_improvement/index.md | 8 + 9 files changed, 591 insertions(+) create mode 100644 documentation/meta/project_boards/discussions.md create mode 100644 documentation/meta/project_boards/index.md create mode 100644 documentation/meta/project_boards/issues.md create mode 100644 documentation/meta/project_boards/projects.md create mode 100644 documentation/meta/project_boards/prs.md create mode 100644 documentation/projects/proposals/project_improvement/20230913-project_proposal_project_improvements.md create mode 100644 documentation/projects/proposals/project_improvement/20230914-implementation_plan_project_automations.md create mode 100644 documentation/projects/proposals/project_improvement/index.md diff --git a/documentation/meta/index.md b/documentation/meta/index.md index 79f9104e177..abddfa99828 100644 --- 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 new file mode 100644 index 00000000000..0fcf92ad900 --- /dev/null +++ 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 new file mode 100644 index 00000000000..c955008a615 --- /dev/null +++ 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 new file mode 100644 index 00000000000..532897c761e --- /dev/null +++ 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 new file mode 100644 index 00000000000..3399217a423 --- /dev/null +++ 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 new file mode 100644 index 00000000000..46a68cbdaf8 --- /dev/null +++ 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 new file mode 100644 index 00000000000..1dbbc55d386 --- /dev/null +++ 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 new file mode 100644 index 00000000000..50f877169c9 --- /dev/null +++ b/documentation/projects/proposals/project_improvement/20230914-implementation_plan_project_automations.md @@ -0,0 +1,273 @@ +# 2023-09-14 Implementation plan: Project automations + +**Author**: @dhruvkb + +## Reviewers + +- [x] @AetherUnbound +- [x] @obulat + +## Project links + +- [Project Thread](https://github.com/WordPress/openverse/issues/1931) +- [Project Proposal](/projects/proposals/project_improvement/20230913-project_proposal_project_improvements.md) + +## Overview + +This is the implementation plan describing new automations for the project +board. More information about the project board and existing automations can be +found in our [documentation](/meta/project_boards/index.md). + +## Historical context + +The new project board was created as a successor to our original project boards, +that were "classic" GitHub Projects. + +- [Openverse](https://github.com/orgs/WordPress/projects/3) +- [Openverse PRs](https://github.com/orgs/WordPress/projects/8) + +```{note} +These classic project boards have been closed. They are no longer updated, nor +referred to in any discussions. +``` + +These boards were highly automated. A number of automations related to these +boards were deleted ([PR](https://github.com/WordPress/openverse/pull/2338)) +when they were closed. Those automations can serve as inspiration for their +reboots for the new project board. + +## To-do + +The complete work of automating our boards can be broadly classified under three +categories. + +### General improvements to boards + +1. Normalise emoji usage + + The backlog board uses an emoji for each column. None of the other boards do. + Personally I appreciate them and would like all boards to use them but + wouldn't mind dropping them from the backlog board for consistency's sake. + + **For emoji:** + + - @dhruvkb + - @AetherUnbound + - <add your name here> + + **Against emoji:** + + - <add your name here> + +2. Column changes + + - **Issues** + - Create new column "🗑️ Discarded" for issues that were closed without + resolution (like label "⛔️ status: discarded"). + - **PRs** + - Split "Needs Review" into two columns based on their number of existing + reviews. + - 2️⃣ Needs 2 Reviews (no reviews yet) + - 1️⃣ Needs 1 Review (one approval, near finish line) + - Create new column "🗑️ Discarded" for PRs that were closed without merge. + - Rename "Merged" to "✅ Done" for consistency with issues board. + +### Improvements to existing automations + +1. [Issues/Issue is created](/meta/project_boards/issues.md#issue-is-created) + and + [Issues/Issue is added to the project](/meta/project_boards/issues.md#issue-is-added-to-the-project) + + The issue should be added to the project board under the appropriate column, + "📋 Backlog" or "⛔ Blocked" depending on the issue labels. + +2. [Issues/Issue is closed](/meta/project_boards/issues.md#issue-is-closed) + + The issue should be moved to the "✅ Done" column only if it was resolved. If + it was closed as discarded, it should be moved to a new "🗑️ Discarded" + column. + + The built-in workflow will have to be replaced by a custom one that looks at + the `state_reason` field inside the issue payload of the `closed` activity of + the + [`issues` event](https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows#issues). + +3. [Issues/Issue is closed and inactive](/meta/project_boards/issues.md#issue-is-closed-and-inactive) + + The current system means that issues are archived one by one as they become + inactive and with an 8 day cadence, this will slowly drift out of sync with + the weekly development chat. + + Archiving should be performed by a custom scheduled workflow that archives + all items in the "✅ Done" and "🗑️ Discarded" columns weekly (preferably + immediately after the chat). + +4. [PRs/PR is created](/meta/project_boards/prs.md#pr-is-created) and + [PRs/PR is added to project](/meta/project_boards/prs.md#pr-is-added-to-the-project) + + The PR should be added to the project board under the appropriate column, "In + Progress" or "Needs <x> Review(s)" depending on the PR's draft or + ready-for-review state and the number of existing reviews. + +5. [PRs/PR is closed or merged](/meta/project_boards/prs.md#pr-is-closed-or-merged) + + The PR should be moved to the "✅ Done" column only if it was merged. If it + was closed without merge, it should be moved to a new "🗑️ Discarded" column. + + This can be implemented by updating built-in workflows. + +### Restoration of previous automations + +1. Issues/Issue is connected to PR + + When an issue is + [connected](https://docs.github.com/en/rest/overview/issue-event-types?apiVersion=2022-11-28#connected) + to a PR, the issue should move from "📋 Backlog" or "📅 To do" to the "🏗 In + Progress" column. If the issue is labeled as "⛔ status: blocked", that label + should be dropped. + + Unfortunately, the `connected` event does not trigger workflows. So this can + be implemented using a combination of multiple workflows. + + - scheduled workflow + - [`pull_request` event](https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows#pull_request) + - created + - edited + +2. Issues/PR linked to issue is closed without merge + + When the PR for an issue in "🏗️ In Progress" is closed without merge, the + issue should go back to the "📅 To do" column. + + The `closed` activity in the + [`pull_request` event](https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows#pull_request) + can trigger workflows to do this. + +### Creation of new automations + +1. Issues/Issue is relabeled + + When an issue's labels change, it should automatically move to the right + column. + + - issues labeled as "⛔ status: blocked" ⟹ Move into "⛔ Blocked" column + - issues unlabeled as "⛔ status: blocked" ⟹ Move into "📋 Backlog" column + + Both `labeled` and `unlabeled` activities in the + [`issues` event](https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows#issues) + can trigger workflows to do this. + + The priority field in the project board issues should also be synced to the + priority label using the same workflow. Additionally, critical issues can + directly be added to the "📅 To do" column instead of the "📋 Backlog" column + to prioritise their resolution. + +2. Issues/Issue is assigned + + An assigned issue in "📋 Backlog" must be moved into "📅 To do". The opposite + event, i.e. moving unassigned issues from "📅 To do" to "📋 Backlog" should + not happen. + + The `assigned` activity in the + [`issues` event](https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows#issues) + can trigger workflows to do this. + +3. PRs/PR state is changed + + When a PR is drafted or made ready for review, it should be relocated to the + right column. + + - PR is converted to draft ⟹ Move into "In Progress" column + - PR is ready for review ⟹ Move into the "Needs <x> Review(s)" column + + Both `converted_to_draft` and `ready_for_review` activities in the + [`pull_request` event](https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows#pull_request) + can trigger workflows to do this. + +## Modifications + +Each of these automations performs one of these modifications to the cards. + +- add cards +- move cards between columns +- archive cards + +## Plan + +Here we define workflows based on the above-mentioned improvements. Each +workflow should have multiple steps that are controlled based on two params +`github.event_name` and `github.event.action`. + +### Issues ([`issues`](https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows#issues)) + +Activity types: + +- `opened` + + Add to project board. Perform same label-related steps as the `labeled` + activity. + +- `closed` + + Check `state_reason` field in payload and move to "✅ Done" or "🗑️ Discarded" + column. + +- `assigned` + + If in "📋 Backlog", move to "📅 To do". Else leave as is. + +- `labeled` + + If "⛔️ status:blocked" in existing labels, move to “⛔ Blocked” column. Else + if "🟥 priority: critical" in existing labels, move to "📅 To do" column. Else + move to "📋 Backlog" column. Sync priority label to priority field. + +- `unlabeled` + + If the "⛔️ status:blocked" label is removed, move to "📋 Backlog" column. + +### PR ([`pull_request`](https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows#pull_request)) + +Activity types: + +- `opened` + + Add to the project board. Perform the same state related steps as the + `converted_to_draft` and `ready_for_review` activities. + +- `edited` + + When a PR is edited, it can be linked to an issue via the description. If the + PR is linked to an issue, move the issue to "🏗️ In Progress" column. + +- `closed` + + Check `github.event.pull_request.merged` field in payload and move to "✅ + Done" or "🗑️ Discarded" column. + +- `converted_to_draft` + + Move to the "🏗 In Progress" column. + +- `ready_for_review` + + Perform the same state related steps as the `pull_request_review` event. + +### PR review ([`pull_request_review`](https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows#pull_request_review)) + +Check all submitted reviews. If a PR has at least one "CHANGES_REQUESTED" +review, do nothing (the built-in action will handle this). If the PR has one +approval, move to the "1️⃣ Needs 1 review" column. If the PR has no approvals +yet, move to the "2️⃣ Needs 2 reviews" column. + +### Scheduled + +Schedules: + +- weekly + + Archive "✅ Done" and "🗑️ Discarded" columns. + +- daily + + Identify linked issues and move them to "🏗️ In Progress" column. diff --git a/documentation/projects/proposals/project_improvement/index.md b/documentation/projects/proposals/project_improvement/index.md new file mode 100644 index 00000000000..4d965690a91 --- /dev/null +++ b/documentation/projects/proposals/project_improvement/index.md @@ -0,0 +1,8 @@ +# Project board improvements + +```{toctree} +:titlesonly: +:glob: + +* +```