Team development workflow¶
This section describes how our development team carries out its planning and day-to-day work.
The 2i2c team uses Sprints to coordinate with one another in focused cycles of work. To begin each sprint, we collectively choose items to work on in the next sprint. Each item should have a person assigned to it, who will be responsible for ensuring that the work gets done. However, our work within a sprint is a team commitment, and we are all responsible for helping one another accomplish our tasks.
We are still working out the best structure for the Sprint Planning meeting and how it fits in with our team coordination. See this GitHub issue for the latest information.
Our team works in one week sprints. Here is a brief overview of each sprint.
Sprint begins with our sprint planning meeting.
In this meeting we prioritize and assign the items that each team member will work on for this week, and review items that require discussion and planning.
Team members work on the deliverables assigned to them at the sprint planning meeting.
By the end of the day, team members should have completed all of their deliverables for that week. Each team member fills out a team sync update to share the major things they worked on, and note any unexpected challenges or blockers.
Sprint planning meeting¶
The 2i2c team meets every Tuesday for 60 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.
Sprint Planning Meetings roughly follow a two-step process:
Scan and discuss the deliverables backlog in order to understand our WIP deliverables and their prioritization relative to one another.
Add deliverables, or their tasks, to the week’s Sprint Board, and work on them throughout the week. It’s up to the team whether a deliverable or one of its tasks should be added to the board.
You can find the meeting format/agenda
in the Sprint Planning meeting template.
The Sprint Board¶
The Sprint Board is a place to keep track of the Deliverables our team intends to work on for the week. It is a GitHub Projects board that is created for each week, and closed at the end of each week. The team’s goal is to complete all deliverables on the Sprint Board by the end of the Sprint. This is a team commitment - while one person may be assigned to a deliverable, we all commit to working together to get the work done.
The Sprint Board should…
Have enough deliverables/tasks 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
The Sprint Board is broken down into these columns:
Up Next Deliverables that are ready to be worked on.
In progress A deliverable that a team member is currently working towards.
Needs Input Items that require input from one or more team members before moving forward. If a review is needed, use the needs:review label, and if a decision is needed, use the needs:decision label.
Done Tasks that are complete! When you move a task here, make sure to update any relevant deliverables.
Deliverables represent incremental amounts of value we can deliver to a particular stakeholder. They are encoded as GitHub Issues and updated over time as we learn more about the particular deliverable. Most issues in our repositories are deliverables, in varying states of readiness.
How are deliverables structured?¶
There are a few special sections of a deliverable issue. Not all of them are strictly required, but are particularly useful for more complex or long-lasting deliverables.
See this Github Issue template for an example of a deliverable’s structure. Below are some major sections that are common:
- Top Comment
The top comment of a deliverable has meta information associated with that deliverable. This includes background information, user stories, task lists, etc. The top comment should be frequently updated by anybody on the team with relevant information to add. Do not hesitate to update somebody’s top comment with new information, even if you didn’t open the issue (though you’re encouraged to leave a comment noting what has changed!).
What is the benefit for completing this deliverable? This should be in the form of user stories that explicitly define the stakeholders that care about a deliverable, and why.
- Tasks to complete
Use task lists encode discrete steps to take in order to complete a deliverable. All deliverables should have either a set of concrete steps to take to meet the deliverable, or at least one task with the acceptance criteria for when the deliverable will be complete. Task lists should be in the top comment of the deliverable, and are encoded as markdown tasks lists (e.g. with
- [ ]). Task lists should be updated over time as we learn the steps needed to close the deliverable. For more complex deliverables, these tasks may be what goes onto the Sprint Board, rather than the deliverable itself.
The Deliverables Backlog¶
The Deliverables Backlog is a GitHub Projects Board with a list of Deliverables across all of our active projects. These deliverables adhere to the following principles:
Each item on this board should be ready to work, meaning that it has enough background information and context for a team member to steward it to completion.
The order of these deliverables should be roughly according to priority, with higher priority deliverables at the top of lists.
High-priority deliverables should be added to a weekly sprint board in order to be worked on.
If a deliverable has multiple components or would otherwise take longer than a week to complete, create task lists inside it to track steps. Add those steps to the Sprint board, not the whole deliverable.
Working on deliverables¶
Deliverables are ready to work when they have enough context and tasks so that a team member can begin making progress towards closing them. This doesn’t mean that we know all of the tasks needed to complete the deliverable, but that there’s enough information to begin work. 1
The team picks up work associated with a deliverable via our Sprint Planning meeting. In this case, there are two options:
Add the deliverable to the Sprint Board. If a deliverable is scoped tightly enough that it can be completed within one sprint, then add it to the Sprint Board and complete it in a sprint.
Generate issues from tasks and add them to the Sprint Board. For deliverables that are more complex and require tasks that would take more than one sprint, use the Task List in the deliverable to generate issues for use on the Sprint Board.
You can use GitHub’s task issue tracking features to keep track of tasks associated with a deliverable issue.
As work is done towards a deliverable, update the top comment of the deliverable with new information and tasks. The deliverable issue is the Source of Truth for all work associated with it (instead of, for example, an issue created for a task for that deliverable).
Merging and Reviewing policy¶
The sections below describe major policies around merging and reviewing depending on the kind of change being made. There are some extra policies for changes that affect actively-running infrastructure. See the section below for details.
Not all of them are followed strictly, though some are more important than others, and are marked with REQUIRED.
Always make a Pull Request. (REQUIRED). All changes to 2i2c repositories should be made via a Pull Request. This should be enforced by setting the
masterbranch of each repository to be “protected”.
PRs should reference (and close) issues. A pull request should almost always be related to an issue. Ideally, the issue should be tightly-scoped enough that the PR will close it when merged. If you have an idea that doesn’t yet have an issue, open an issue first and then make the PR to close it. This ensures that the team has context around Pull Requests, and a chance to discuss before we implement.
Request Reviewfeature. Add specific team members so that it is clear who is needed to review the PR.
Be explicit about what feedback you want. When you open a PR, include some language about specific things you’d like feedback with, if applicable. This helps others focus their attention.
Use the review column on sprint boards. When a PR needs review, move any relevant issues to the Review column of the active Sprint Board so others notice it.
Merge after one approval. If there is at least one approval on a PR, then anybody, including the PR author, may merge the PR. PR authors should not hesitate to merge their own PR after an approval if they think it is ready to go!
Merging without review is discouraged, but not forbidden. For changes that are minor, very straightforward, and do not affect actively-running infrastructure, it is acceptable to self-merge a PR without getting an approval.
If you don’t believe that your PR requires an approval before merging, make it clear in your PR or in a comment that you plan to merge it in 24 hours.
Leave PRs open for at least 24 working hours. This helps ensure that others on the team have a chance to look at the PR and give their thoughts (by working hours we mean hours during a weekday).
Policy for changes to running infrastructure¶
Changing active infrastructure is a bit different from developing technology that is not immediately in production. As such, we follow some more specific guidelines for these kinds of changes. See Review and merge guidelines.
Policy for team compass changes¶
If a change affects the 2i2c team policies, or makes significant changes to our documentation or public-facing material, then you should also follow these extra policies:
Ensure that the team has consented. For any major change, you should make sure that you have followed best-practices in consent-based decision making. See How we make decisions for more information.
How to keep track of projects¶
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, described in this section.
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 Sprint Board) as-needed.
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:
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.
Ready to Work: Deliverables that are well-scoped and have a clear path forward, and are thus ready to implement. As deliverables in 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.
In progress: Deliverables that we are currently working towards. This means that they should be added to the Sprint Board to track its completion.
Blocked: Deliverables that require another action or delivearable from the 2i2c team to complete before they can move forward.
Waiting: Deliverables that require another action from a non-2i2c team member before they can move forward.
Done: Deliverables that have been completed. We should close these issues and celebrate the improvements that we have made!
How we make decisions¶
The 2i2c Team follows consent based decision-making in making all of its team decisions. This roughly means the following for any decision that impacts all team members:
The proposed decision and relevant context must be available to all team members. This is generally done via opening GitHub issues.
Ensure that team members have time to understand the proposal, and ask questions about it to understand its ramifications.
Ensure that team members have time to object and make suggested changes.
Ensure that the result of the decision is recorded somewhere that is available to all team members.
Generally speaking, this process is carried out via GitHub Issues and Pull Requests. See Merging and Reviewing policy for how this works in practice.
Resources to learn about consent-based decision making¶
Here are some helpful resources for more information about consent-based decision-making.
A short primer: https://thedecider.app/consent-decision-making
A more in-depth discussion: https://www.sociocracyforall.org/consent-decision-making/
A well-known technical proposal on “Consent via humming”: https://tools.ietf.org/html/rfc7282