From 32fcbf53844875c16c776d828689dd19ddf92849 Mon Sep 17 00:00:00 2001 From: Chris Holdgraf Date: Tue, 3 Aug 2021 10:54:42 +0200 Subject: [PATCH] Update meetings and team practices --- .../ISSUE_TEMPLATE/meeting-deliverables.md | 39 ++---- .github/ISSUE_TEMPLATE/meeting-team.md | 2 +- .github/ISSUE_TEMPLATE/new-bug.md | 2 +- .github/ISSUE_TEMPLATE/new-enhancement.md | 15 +- practices/development.md | 131 ++++++++---------- practices/meetings.md | 49 +++++-- 6 files changed, 117 insertions(+), 121 deletions(-) diff --git a/.github/ISSUE_TEMPLATE/meeting-deliverables.md b/.github/ISSUE_TEMPLATE/meeting-deliverables.md index c3f08841..78b2e1bb 100644 --- a/.github/ISSUE_TEMPLATE/meeting-deliverables.md +++ b/.github/ISSUE_TEMPLATE/meeting-deliverables.md @@ -7,37 +7,28 @@ title: "Deliverables Review Meeting: " # 2i2c Deliverables Review meeting -This is a **30 minute** recurring meeting every two weeks on **Tuesday at 8:00AM Pacific time** (here's [**a timezone converter**](https://arewemeetingyet.com/Los%20Angeles/2000-01-01/08:00/2i2c%20Team%20Meeting#eyJ1cmwiOiJodHRwczovL2hhY2ttZC5pby9ZNVNCTXhWN1I2Q01xemVUWGdtNWtBIn0=), ignore the date!). +This is a **30 minute** recurring meeting every **Tuesday at 8:00AM Pacific time** (here's [**a timezone converter**](https://arewemeetingyet.com/Los%20Angeles/2000-01-01/08:00/2i2c%20Team%20Meeting#eyJ1cmwiOiJodHRwczovL2hhY2ttZC5pby9ZNVNCTXhWN1I2Q01xemVUWGdtNWtBIn0=), ignore the date!). Our goal is to synchronize the team on the most important things to work on, and to divide work between one another so we know what to work on next. - **Video conference link:** https://bit.ly/zoom-holdgraf - **Calendar for future meetings:** [this Google Calendar](https://calendar.google.com/calendar/embed?src=c_4hjjouojd8psql9i1a8nd1uff4%40group.calendar.google.com&ctz=America%2FLos_Angeles) -- **Meeting moderator**: +- **Meeting facilitator**: +- **Meeting recorder**: +- **Meeting timekeeper**: ## Meeting agenda _Follow the agenda below, checking boxes as we complete each step._ -### Activity Backlog -_(5m) Quick review of [Activity Backlog](https://github.com/orgs/2i2c-org/projects/5?fullscreen=true) to let team members signal-boost if needed._ - -- [ ] Team members signal-boost latest team sync items if they wish. -- [ ] Note items that 2i2c team members wish to highlight for review. -- [ ] Note important upcoming dates for the team. - -### Major deliverables - -_(20m) Overview major work items in our [Development Backlog](https://github.com/orgs/2i2c-org/projects/7?fullscreen=true)._ - -- [ ] Discuss any high-priority items that need refinement. -- [ ] Each 2i2c team member knows the next two things that they'll work on. -- [ ] Each high-priority ready-to-work issue has at least one team member assigned to it. - -### Support steward transfer - -_(5m) Transition support steward roles to the next team member._ - -- [ ] Preview support steward describes major support issues that have come up (with links to relevant issues) -- [ ] Open issue for next Support Steward. -- [ ] Close previous issue for Support Steward. +- [ ] (5m) Quick review of [Activity Board](https://github.com/orgs/2i2c-org/projects/5?fullscreen=true) to track progress from last week. + - [ ] Team members signal-boost any issues/PRs/discussions if they wish. + - [ ] Note any deliverables that we didn't finish in the last cycle, decide what to do with them. +- [ ] (20m) Populate [Activity Board](https://github.com/orgs/2i2c-org/projects/5?fullscreen=true) with new deliverables to work on for this cycle. + - [ ] Somebody assigned to each item on the Activity Board + - [ ] Everybody agrees the current cycle's plan is realistic that the right items are on the board. +- [ ] (5m) Support ticket overview. + - [ ] Support steward asks for assistance on issues that need it. + - [ ] (_every two weeks_) Transition support steward roles to the next team member + - [ ] Open issue for next Support Steward. + - [ ] Close previous issue for Support Steward. diff --git a/.github/ISSUE_TEMPLATE/meeting-team.md b/.github/ISSUE_TEMPLATE/meeting-team.md index 31977fc1..62a35d9c 100644 --- a/.github/ISSUE_TEMPLATE/meeting-team.md +++ b/.github/ISSUE_TEMPLATE/meeting-team.md @@ -29,7 +29,7 @@ _Steps to take to have the meeting._ - **At least 1 day prior to meeting** - [ ] Agenda items added to the meeting - - [ ] Moderator and Note Taker identified in HackMD + - [ ] Meeting roles identified in meeting issue - [ ] Have the meeting - [ ] Open up any follow-up issues or discussions and link above - [ ] Cut notes out of HackMD and add to the Team Compass: diff --git a/.github/ISSUE_TEMPLATE/new-bug.md b/.github/ISSUE_TEMPLATE/new-bug.md index 3f007ed4..b1dacc34 100644 --- a/.github/ISSUE_TEMPLATE/new-bug.md +++ b/.github/ISSUE_TEMPLATE/new-bug.md @@ -12,7 +12,7 @@ labels: "type: bug" -# Actions to improve this? +# Actions to address this diff --git a/.github/ISSUE_TEMPLATE/new-enhancement.md b/.github/ISSUE_TEMPLATE/new-enhancement.md index 605f6733..9b0c1879 100644 --- a/.github/ISSUE_TEMPLATE/new-enhancement.md +++ b/.github/ISSUE_TEMPLATE/new-enhancement.md @@ -8,23 +8,18 @@ labels: "type: enhancement" -# User Stories +# Benefit +- This issue is important because... - As a `` I want to `` so that ``. - ... -# Acceptance criteria +# Actions to complete - - -- Given ``, when ``, then ``. + # Important information - - -# Tasks to complete - - \ No newline at end of file + diff --git a/practices/development.md b/practices/development.md index ae8cd8e5..98bd9abe 100644 --- a/practices/development.md +++ b/practices/development.md @@ -2,105 +2,90 @@ # Team development workflow This section describes how our development team carries out its planning and day-to-day work. -Here's a quick summary: -* [Deliverables](coordination:deliverables) are discrete units of value that we bring to others. To be ready for work, they should be scoped properly, with enough information to complete them (e.g., a set of [tasks](coordination:tasks)). -* The [Project Backlog](coordination:project-backlog) contains lists of **deliverables** that we are currently working towards across all of the 2i2c projects. Deliverables on the Project Backlog define our team priorities at any moment. -* [Tasks](coordination:tasks) are concrete actions to take, and should be accomplishable in a single work session by one person. -* The [Activity Backlog](coordination:active-backlog) contains lists of **tasks** that we are currently working on. This defines 2i2c's current activity. - -(coordination:project-backlog)= -## Project Backlogs - -The Project Backlog contains all of the deliverables across our projects that we wish to work on quickly. -These are organized into a few columns, representing the _state_ of each deliverable. -Here is a common column structure: - -- {guilabel}`Needs Discussion/Refinement`: Deliverables that are high-priority but un-refined. Our goal should be having discussion and doing research in order to get these deliverables ready for work. -- {guilabel}`Ready to Work`: Deliverables that are well-scoped and have a clear path forward, and are thus ready to implement. As deliverables in {guilabel}`In progress` are completed, we should replace them with deliverables from this column. Generally speaking, deliverables near the top have higher priority than those at the bottom. -- {guilabel}`In progress`: Deliverables that we are currently working towards. This means that we should be generating [Tasks](coordination:tasks) in our [Activity Backlog](https://github.com/orgs/2i2c-org/projects/5?fullscreen=true) to complete this deliverable (more on this below). -- {guilabel}`Blocked/Waiting`: Deliverables for which we are waiting for some action that is out of our team's immediate control. -- {guilabel}`Done`: Deliverables that have been completed. We should close these issues and celebrate the improvements that we have made! - -:::{note} -In general, there should be only two or three deliverables per team member, per column on this board. -It should not become so heavily-populated that it is hard to keep track of deliverables! +:::{admonition} Helpful links +👉 [Here is a link to all 2i2c GitHub Issues that have been assigned to you](https://github.com/issues?q=is%3Aissue+is%3Aopen+archived%3Afalse+sort%3Aupdated-desc+assignee%3A%40me+user%3A2i2c-org+) +👉 [Here's a link to see all Pull Requests for which your review is requested](https://github.com/issues?q=is%3Aopen+archived%3Afalse+sort%3Aupdated-desc+user%3A2i2c-org+type%3Apr+review-requested%3A%40me+) ::: -There are two Project Backlogs at 2i2c: - -- The [2i2c Development Projects Backlog](https://github.com/orgs/2i2c-org/projects/7?fullscreen=true) contains deliverables for our development-focused projects. -- The [Organizational Project Backlog](https://github.com/orgs/2i2c-org/projects/8?fullscreen=true) contains deliverables that are organization-wide and not related to development. +## Cadence of work +Our team works in one week cycles. +Each cycle begins on Monday with our [team deliverables review meeting](meetings:deliverables-review). +In this meeting we prioritize and assign the items that each team member will work on for the next week, and review items that require discussion and planning. +At the end of each week, we should have completed all of the major delivearables set out for that week. + (coordination:deliverables)= ## Deliverables -Deliverables represent incremental amounts of value we can deliver to a particular stakeholder, and should be completable in a week or two. +Deliverables represent incremental amounts of value we can deliver to a particular stakeholder, and should be completable in a week. +They are **encoded as GitHub Issues**. -Most issues in our repositories are deliverables, in varying states of readiness. When a deliverable is first created, it may lack information, be improperly scoped, or have an unclear path to implementation. We improve this through _deliverable refinement_ (see below). +Most issues in our repositories are deliverables, in varying states of readiness. +Deliverables that are added to the [Activity Board](coordination:activity-board) should have enough context and tasks that a team member can realistically close them on their own. [^invest] -A deliverable is ready to work (and can thus be added to the Project Backlog) when it has the following properties (adapted from the [INVEST methodology](https://agileforall.com/new-to-agile-invest-in-good-user-stories/)). +[^invest]: A good resource for considering what kinds of information makes a deliverable "ready" is [the INVEST methodology](https://agileforall.com/new-to-agile-invest-in-good-user-stories). +:::{admonition} Deliverables should... +:class: tip - **Have a short title and description:** Deliverables should be glanceable and have enough context that the reader can quickly understand the scope. - **Have one or more [user stories](https://www.atlassian.com/agile/project-management/user-stories):** User stories should define who benefits from the deliverable, and why they want it. -- **Have completion criteria:** We have clear completion criteria for this deliverable to denote it as “done”. - **Have tasks to complete it**: Deliverables should have a set of tasks, which are actions needed to complete the deliverable. +::: -### How refinement happens +(coordination:activity-board)= +## The Activity Board -_Deliverable Refinement_ is the process of improving the scoping, context, and structure of our Deliverables issues so that they are ready for us to work on them. When a deliverable is created, it may not have all of the information needed to take the next step. Adding that information is the goal of Deliverable Refinement. +The [Activity Board](https://github.com/orgs/2i2c-org/projects/5?fullscreen=true) contains the collection of [Deliverables](coordination:deliverables) that the team is currently working on. +All deliverables on the Activity Board should be accomplished by the end of the week. +This board is filled during our [Deliverables review meeting](meetings:deliverables-review). -All team members are expected to participate in deliverable refinement, though the more experienced and higher-level you are, the more you should be contributing to this process. -The important thing is that we always have a list of high-quality deliverables ready to work towards. +:::{admonition} The Activity Board should... +:class: tip +- Have enough deliverables to keep the team occupied for the week +- Not have so many deliverables that a team member gets overwhelmed +- Under-estimate our team's total capacity, to provide room for unexpected work (e.g., support work) +- Have a team member assigned to each item on the board +::: -Here's a small table that explains how to decide whether deliverables issues should be put in a project backlog: +The Activity Board is broken down into these columns: -:::{list-table} -:header-rows: 1 -- - - - Needs more information - - Ready for working -- - Low priority - - Stays in issues - - Put in {guilabel}`Ready to work` -- - High Priority - - Manually put in \ - {guilabel}`Needs Discussion/Refinement` - - Put in {guilabel}`Ready to work` -::: +- {guilabel}`Up Next` Deliverables that are ready to be worked on. +- {guilabel}`In progress` A deliverable that a team member is currently working towards. +- {guilabel}`Done` Tasks that are complete! When you move a task here, make sure to update any relevant deliverables. -(coordination:active-backlog)= -## Activity Backlog +## Requesting reviews -The [Activity Backlog](https://github.com/orgs/2i2c-org/projects/5?fullscreen=true) contains the collection of **Tasks** that the team is currently working on. -Tasks are actions that are needed to accomplish some deliverable. -These tasks are generated from the deliverables on the Projects Backlog. -They define a “to do” list of tasks to complete on a day-to-day basis. +When you have an implementation that requires feedback, use GitHub's **Request Review** feature to ask other team members to take a look. +You can either add all team members as a request, or add specific team members if you believe they'll be particularly helpful in a review. -The Activity Backlog is broken down into these columns: +% TODO: We should define a more structured process for requesting reviews and how it fits in with our merge policies. -- {guilabel}`Needs Discussion/Refinement` Tasks that require some team discussion around _implementation_. If there are higher-level discussions about the deliverable itself, perhaps the deliverable is not yet ready to be worked on. -- {guilabel}`Ready to Work` Tasks that are ready to be worked on. Roughly speaking, tasks higher on the list are of higher priority. -- {guilabel}`In progress` A task that a team member is currently working towards. When you move a task to In progress, indicate that you are working on it (either by adding your username to the card, or “assigning yourself” in the issue/PR associated with it. -- {guilabel}`Needs review` Tasks that have an implementation that require feedback from others. For example, reviews for pull requests. -- {guilabel}`Done` Tasks that are complete! When you move a task here, make sure to update any relevant deliverables. +## Encoding longer-term efforts -There is one Activity Backlog defined [at this GitHub Projects Board](https://github.com/orgs/2i2c-org/projects/5?fullscreen=true). +Longer-term projects are generally more complex and may be made up of many actions and deliverables to accomplish. +There is no official way to track long-term projects within 2i2c, but there are a few patterns that may be useful to do so. -(coordination:tasks)= -## Tasks +% TODO: We should define a more reliable process for tracking long-term projects -Deliverables of sufficient complexity are broken down into _tasks_. Tasks should be completable by a single person in less than one day (generally, completable with a few hours of focused work at most). Make sure to attach a link between your deliverable and its tasks (e.g., by adding links to issues in the deliverable’s "tasks" checklist) +### Tracking issues -Tasks are generally encoded as checklist items in a deliverable, then added to the Activity Backlog when the deliverable is being worked on. +The simplest way to track longer-term efforts is with a **Tracking Issue**. +This is a GitHub Issue whose job is to keep track of many actions and deliverables over time that are needed to close the issue. +They are generally encoded as **Task Lists** in the issue's top comment. +Each item in the list tends to be a deliverable, and can be converted into its own GitHub Issue (e.g., to put on the [Activity Board](coordination:activity-board)) as-needed. -Here’s an example of a deliverable with a few tasks: +(coordination:project-backlog)= +### Project Backlogs -- **Deliverable:** Side notes in Jupyter Books. \ - **User story**: _As a book author, I want to be able to create “aside” content that does not break up the narrative flow of my text._ \ - **Tasks:** - - Create design doc for directive name and general API - - PR to prototype functionality and documentation - - Add tests and QA - - Final approval + merge +For more complex efforts, it can be useful to create a Project Backlog. +These are GitHub Projects boards that contain all of the deliverables that will complete a given project. +These are often organized into a few columns, representing the _state_ of each deliverable. +Here is a common column structure: +- {guilabel}`Needs Discussion/Refinement`: Deliverables that are high-priority but un-refined. Our goal should be having discussion and doing research in order to get these deliverables ready for work. +- {guilabel}`Ready to Work`: Deliverables that are well-scoped and have a clear path forward, and are thus ready to implement. As deliverables in {guilabel}`In progress` are completed, we should replace them with deliverables from this column. Generally speaking, deliverables near the top have higher priority than those at the bottom. +- {guilabel}`In progress`: Deliverables that we are currently working towards. This means that they should be added to the [Activity Board](coordination:activity-board) to track its completion. +- {guilabel}`Blocked`: Deliverables that require another action or delivearable from the 2i2c team to complete before they can move forward. +- {guilabel}`Waiting`: Deliverables that require another action from a **non-2i2c team member** before they can move forward. +- {guilabel}`Done`: Deliverables that have been completed. We should close these issues and celebrate the improvements that we have made! diff --git a/practices/meetings.md b/practices/meetings.md index d3fe2954..1c20d732 100644 --- a/practices/meetings.md +++ b/practices/meetings.md @@ -15,33 +15,52 @@ They are listed below. - All planned team meetings should be encoded asnychronously somehow (e.g., via GitHub Issues, notes in our team compass, etc). - All meetings should have an agenda that includes estimations of time and is ideally filled out 24 hours in advance. -- All meetings should have a designated moderator that will run the meeting and help move discussion forward. -- For meetings with notes, all meetings should have a designated **Note Taker** that will take notes. +- All meetings should have a designated person for each [role in a team meeting](meetings:roles). +- In general, [meeting roles](meetings:roles) should rotate between regular attendees of meetings in order to share work and build groups skills. - All attendees of all meetings follow the [2i2c Code of Conduct](https://team-compass.2i2c.org/en/latest/code-of-conduct/index.html) -### Meeting Moderator +(meetings:roles)= +## Roles in team meetings -The role of meeting moderators is to structure the meeting so that it is well-scoped, and to guide conversation to be productive and inclusive. +These are major roles that should be filled by someone explicitly for any team meeting[^1]. -:::{admonition} Responsibilities of the Moderator +[^1]: See [this blog post on team meeting roles](https://cfe.unc.edu/facilitator-recorder-and-timekeeper-roles/) for more inspiration here. + +### Facilitator + +The role of meeting facilitator is to structure the meeting so that it is well-scoped, and to guide conversation to be productive and inclusive. + +:::{admonition} Responsibilities of the Facilitator - Set the agenda before the meeting (either creating it themselves, or asking for agenda items from others) - Run the meeting, ensuring that we stay on-time with agenda items and discussion - Convert actionable items into issues and close-out the meeting issue if it exists ::: -### Meeting Notetaker +### Recorder -The Meeting Notetaker is responsible for encoding the discussion points and actionable items that came out of a meeting. +The Meeting Recorder is responsible for encoding the discussion points and actionable items that came out of a meeting. Their primary goal is to make sure we don't miss something important after the meeting, and ensure that the content of the meeting is saved for reference from others. -:::{admonition} Responsibilities of the Notetaker +:::{admonition} Responsibilities of the Recorder - Write down major discussion points and ideas during the meeting - Write down action items / to-dos explicitly so that we know what to follow up on - Clean up the notes after the meeting - Archive the notes in the appropriate location (e.g., the Team Compass) ::: -## Monthly team meetings +### Timekeeper + +The timekeeper's role is primarily to assist the Meeting Facilitator in moving the meeting forward. + +:::{admonition} Responsibilities of the Timekeeper +- Keep track of the current time, and proivde the Facilitator / meeting attendees cues that help them decide when to move things forward. +::: + +## Kinds of recurring meetings + +The following are meetings that we regularly hold. + +### Monthly team meetings The 2i2c Team meets the **first Monday of each month** for 90 minutes. @@ -59,15 +78,21 @@ We use [this HackMD for our team meeting notes and agenda](https://hackmd.io/Y5S See the [Team Calendar page](team/calendar) for information about when and where the meetings are held. -## Deliverables review meetings +(meetings:deliverables-review)= +### Deliverables review meetings + +:::{admonition} Temporarily weekly! +We are still working out the best structure for the deliverables review meeting and how it fits in with our team coordination. +We are currently holding this meeting **weekly** and will revisit its frequency in three months or so. +::: -The 2i2c team meets **every other Tuesday** for 30 minutes. +The 2i2c team meets **every Tuesday** for 30 minutes. The goal of this meeting is to review our major work deliverables, synchronize with one another, and prioritize work across team members. It is also a chance to hand off the Support Steward role to the next person. You can find the meeting format/agenda {download}`in the Deliverables meeting template <../.github/ISSUE_TEMPLATE/meeting-deliverables.md>`. -## One on one meetings +### One on one meetings In addition to group meetings, we also try to have one-on-one meetings to guide and help one another. These meetings happen with different cadences and formats for different pairs of people.