Code Insights team processes

Weekly sync

The team holds weekly syncs.

The meeting notes of team syncs can be found our sync meeting notes Google Doc.

Before team syncs, teammates and stakeholders should write down under “Agenda” in the meeting notes document anything that they’d like to bring up for discussion with the whole team. Attendees are encouraged to add comments on talking points asynchronously before the meeting too.

Planning and prioritization

We plan and track our day-to-day work on our GitHub board. The project is separated into multiple views: Current iteration, Next iteration (both grouped by issue status) and All iterations (grouped by milestone).

We use an intentional list of statuses on our project board:

• No Status: Status is not assigned. These issues need triage.
• Backlog: We are keeping this issue open for reference, as a placeholder, and for future prioritization, but it’s not a current priority.
• On deck: These issues are not currently proposed for the upcoming iteration but are a maintained, priority ordering of likely next issues.
• Proposed for iteration: These are a select group of issues proposed for a specific iteration. They must have an iteration milestone attached.
• Todo: This is the small set of issues that are planned for our current iteration.
• In Progress: Issues currently being worked on in the iteration.
• In Review: Issues that have PRs in review.
• Done: All closed issues, including “won’t do” issues.

Our current process is as follows:

• We work in 2-week iterations. Every iteration has a GitHub milestone, which is created at least one iteration in advance.

• Incoming tickets (from team members or from other teams) are added to the GitHub project automatically when they are labelled team/code-insights and will be visible in the “All issues” view under “No milestone”. This represents our backlog of unscheduled work.

• While an iteration is ongoing, we plan the next iteration. This is a mostly asynchronous process.

  • Engineers, designer, PM and EM can propose issues to be worked on before the mid-iteration Thursday iteration planning by adding them to the next iteration milestone and setting “Status” to Proposed. This is done considering our higher-level goals and roadmap.

  • We plan our iterations with point baselines such that factor in time off, life events, and support across prior iterations. We calibrate these point baselines via temperature checks in retros and manual adjustment. Roughly 80% of our iteration capacity is planned by the PM as the decider, and ~20% of the capacity is explicitly left for engineers to prioritize, taking into account our goals and roadmap, technical roadmap, estimates, workloads on individuals, and release dates (the 20th of every month).
    The PM will choose issues among all proposed issues – engineers and designers should still propose issues, even if they are not the planning decider.

    • The issue should also have its Size column filled out, so that it can be evaluated whether it fits into the iteration. If the proposer lacks the information to estimate the issue, they reply on the issue in GitHub or raise it in our Slack channel to get the missing information or get an estimate from the appropiate person. Teammates may also discuss this in ad-hoc synchronous meetings if beneficial. An assignee may also already volunteer or be proposed, but this may still be changed at the Monday sync to distribute workload. See below for information on issue sizing.
    • If technical exploration is needed to get more information, a spike (a time-boxed investigation task meant to facilitate more granular planning) can be proposed for the next iteration instead to get that information.
    • Estimations include the testing time necessary to fully test an issue against test plans or test cases defined in the issue.

  • As much as possible, the proposer involves the necessary stakeholders asynchronously to get agreement on whether the issue should be worked on in the next iteration before the Thursday iteration planning. For example, the PM or EM might ping engineers in GitHub or Slack on whether an issue seems feasible, or engineers might ping their EM and PM to get buy-in whether the issue fits into our goals.
    If a task needs synchronous discussion with a smaller group than the whole team, teammates are encouraged to meet synchronously in a smaller group to have more clarity before the mid-iteration Thursday iteration planning.

  • Teammates can reorder proposed issues on the “Next iteration” board before the mid-iteration sync to their liking. The order at the time of the mid-iteration Monday sync is the proposed order.

  • Often, planning work involves RFCs or designs that require engineering input. For this process:

    • The goal of a product-manager-created RFC is to arrive at scoped outcomes for either designs or engineering: this is collected in a “Decisions for Design” or “Decisions for Engineering” section.
    • At this point, the engineering project lead or designer becomes the driver for taking the work through its next stage. For engineering, this may optionally involve an engineering RFC or a new implementation discussion among engineers on the existing RFC. For design, this usually involves Figma mocks. From those stages, the respective project lead or designer and engineers can create GitHub issues to put into proposed.
    • Although discussions and project scope can vary, the rough average goal timeline for this process is:
    • 0.5-1 week: product RFC and discussion
    • 1-1.5 weeks: designs or engineering implementation discussion and issue creation

  • The PM is in charge of moving issues from Proposed to Todo before the fortnightly synchronous iteration planning.

  • We hold a fortnightly synchronous iteration planning, we take a look at the proposed issues together on the “Next iteration” view.

• During an iteration, teammates work on their assigned issues for the iteration in the order they are listed in the “Current iteration” view of the board. When starting work on a task, the teammate updates its status column to “In Progress” to communicate it to their team. This gives a good overview in the “Current iteration” view, which can also be viewed in Kanban layout, on how the iteration is tracking.

• If one or more issues that were planned for an iteration are looking to not get finished (which includes testing) in the current iteration (while maintaining sustainable work practices) the assignee raises this as soon as possible asynchronously to the team (including the PM and EM), e.g. on the GitHub issue or Slack. These issues then become proposed issues for the next iteration (meaning nothing carries over automatically, but we also don’t just drop and forget missed issues).

• When an iteration is finished, the Current iteration, Next iteration and Next-next iteration views should be updated in the Code Insights project and the associated milestone should be closed from the milestones page.

Design planning and process

In addition to the above iteration planning process, we maintain a parallel design planning process as follows using our design project board:

1. Anyone on the team can create issues for things that need designs. These issues should be tagged with needs-design.
2. The product manager and designer add iteration milestones to these design issues. If a design issue has a milestone and a TODO (or a later-stage) status, this means that the design process should be completed by the end date of the iteration milestone.
3. For example, a design issue tagged “iteration 29” in TODO would be ready for engineering implemention by the final day of iteration 29.
4. Design issues do not need to, and often do not, follow 2-week iteration cycles. It is up to the designer when to start or make progress on various design projects within the constraints that designs are complete by the end of the tagged iteration. So, a larger 4-week project to be completed three iterations (in six weeks) away might be started before smaller 1-week project that only needs to be completed by a date four weeks in the future, and that’s fine.
5. The product manager, engineering manager, and designer meet synchronously once a week to review the design board, which requires aligning on proposed updates and re-prioritizing if over capacity.
   1. To propose an update or add a design issue, an issue labelled needs-design should be tagged with the proposed status and a milestone. In the sync, the triad will review all “proposed” issues and either align that the priority and timeline works – in which case, setting them to TODO – or discuss and reorder items.
   2. By the end of the planning sync, there should be no design items tagged with the “proposed” status.
6. Issues tagged needs-design should only ever have the designer assigned. We do not un-assign the designer and then re-assign engineers; we move the issue to done and create new engineering issues. We do this because:
   1. Past experience has taught us that this causes confusion as to the status of an issue, as it’s possible for an issue to from “in progress” on design back to “todo” on engineering.
   2. Often, designs are larger than a single engineering issue and we want to default to engineers breaking up a project into smaller items, rather than reusing a larger and imperfect issue.
7. During the design phase, the Designer creates and maintains a design changelog that is available as a separate Figma page and is linked from the main design issue. The design changelog is created to keep track of the key or pivotal design decisions for a given project as well as the reasoning behind them.
   1. The design changelog is primarily useful for big projects. Smaller issues may not require creating the changelog.
   2. When re-opening the discussion about the past design decision, please read the design changelog first to make sure that your point wasn’t addressed earlier and that new information came to light that warrants reconsidering the decision.

Project Leads

Larger projects, especially ones that involve multiple domains, may benefit from a “project lead”. A project lead assumes full responsibility for gathering all requirements to complete a project. The project lead is expected to have full understanding of the issue and pull in any resources or team members needed to complete the task.

How we think about issue sizes

When sizing an issue please keep in mind the size includes the entire lifecycle of the issue. The coding, any testing both automated and manual, as well as PR reviews and documentation.

When thinking about the size of an issue we try to stay away from actual time estimates. Generally, 1 and 2 sizes should be considered small. 3 and 5 are medium issues. 8 and 13 can be considered large issues. Any number larger than 13 can be considered significantly large, and possibly could represent a small project.

While there is no “maximum” number, once we get higher than a 13 in size it will probably prompt some discussion or at least need some explanation in the issue.

Product Feedback

Specific product feedback about well-defined, small features can be found directly in the GitHub board. More general product feedback that applies to larger features, or that needs more research and planning to be actionable, is kept in Productboard.

Retrospectives

Every two weeks, we hold a review/retrospective meeting to reflect on the past two weeks. We use this meeting to:

• Review the previous retro’s action items to ensure they get completed
• Give Shoutouts! to teammates to show appreciation for something they did that we appreciated
• Discuss things that went well in the past two weeks and that we should do more of / invest more into it
• Discuss the things that could have gone better and what we can learn from it to improve
• Talk about processes that we should revisit/refine/propose to improve our efficiency.

We capture and assign actions to individual teammates. Teammates should consider actions coming out of the retrospective as a very high priority.

Teammates contribute to the retrospective asynchronously during the iteration by adding their thoughts to our retrospective document. Teammates are highly encouraged to comment on points raised before the sync meeting in the document.

We rotate who leads the retrospective to allow all teammates an opportunity to lead the session. Teammates can find the rotation schedule at the top of the retrospective document.

Code reviews

The team follows the default code review guidelines with the following addition:

1. If the author would like any of the requested reviewers to merge the PR after approval they add the label merge-on-any-approve
2. If the author would like their PR to be merged once all of the requested reviewers have approved it they add the label merge-on-all-approve
3. When there are only minor issues, reviewers are encouraged to give “approval with comments” and trust their teammates to address the comments without requiring a follow-up review.
4. If there are any user-facing UI changes the author requests a review from the designer.

Support rotation

The team currently follows a support rotation that is intended to allow a single engineer to dedicate time towards supporting customer issues. This support rotation will automatically update based on an OpsGenie schedule and can be contacted with the @code-insights-support Slack tag. This support rotation is currently intended to be a work hours rotation, instead of on-call.

If the teammate on support duty has time off during their turn, someone else on the team will swap with them or cover. OpsGenie allows to add an override in these cases. It’s the support engineer’s responsibility to reach out proactively, find someone to swap with or cover and add the override.

The engineer assigned to the support rotation is responsible for:

1. Responding to and triaging escalations from other teams (for example: customer support, or security)
2. Performing a best-effort resolution of the issue
   1. This means even if someone doesn’t have much knowledge or context about some parts of the system, they are still responsible to try and solve the problem before escalating to other engineers on the team
   2. This could mean searching documentation, asking questions to other engineers, experimenting with the product, or any other means at your disposal to try and solve the problem
   3. As a reminder, it is better to reach a high quality resolution for our customers, even in high priority escalations. It is acceptable (and expected) to push back on support escalations if you need more time to understand and formulate an answer.
3. Updating any documentation that may help others understand and solve the issue