title: “Design Doc - Attention Set - Solution 1 - Workflow” permalink: design-docs/attention-set-solution-1-workflow.html hide_sidebar: true hide_navtoggle: true toc: false folder: design-docs/attention-set

Solution 1 - Workflow

Please read Use Cases before this doc.

Overview

We propose to establish an “Attention Set” per change that at each point in time contains the users that are expected to take action on a change.

Being in the attention set and requiring/needing attention are used as synonyms in this doc.

Being in the attention set is a state that every user must understand and act on. The expectations and obligations are the same for all users on all changes on all hosts. So as an owner for example you can rely on reviewers to take action, if they are in the attention set.

A user in the attention set is required and expected to take action on a change, i.e. it is their turn. More specifically:

  • As a reviewer you shouldn‘t have to concern yourself with changes that don’t need your attention.
  • As a reviewer you are expected to act, if a change needs your attention. (That action can be removing yourself from the attention set.)
  • As an owner I can expect reviewers to take timely action, if they are in the attention set.

We are establishing the attention set as a first class citizen of the review process by building a User Interface that emphasizes its importance and allows users to see “at a glance” whose turn it is on both the dashboard and the change pages.

We define some simple defaults for how the attention set should change for a few common actions. In the reply dialog users will have fine grained control over attention set changes.

Only review participants (owner, uploader, reviewers and CCs) can be in the attention set.

Email notifications about uploaded patch sets will not be sent anymore (only to the owner, if someone else uploads a patchset). Reviewers will get emails when they are added to the attention set.

We propose to drop the Reviewed feature and its associated bolding of change-list items.

We propose to keep the “Assignee” feature around, but new releases would have it turned off by default, because for most hosts the overlap with the attention set is too big, and they don't have a need for the urgency aspects of Assignee. OTOH hosts that make good use of the feature should be able to keep using it.

Defaults

In order to help the user, we propose to apply useful default modifications to the attention set when standard review events happen. Each of the following defaults can be overridden when executing the action in the user interface:

  • When reviewers are added they are added to the attention set.
  • When someone other than the owner uploads a patchset the owner is added to the attention set.
  • When a change is submitted or abandoned all users are removed from the attention set.
  • Replying (commenting, voting or just writing a change message) will remove the publishing user from the attention set.
    • When a reviewer replies add the owner (and uploader) to the attention set. Refinements:
      • For each comment thread that the reviewer replies to also add all participants of that thread to the attention set.
    • When the owner (or uploader) replies add all reviewers to the attention set. Refinements:
      • When the uploader replies also add the owner to the attention set.

The above defaults are also applied when using the API (but can also be overriden). For example if the reviewers-by-blame plugin adds a reviewer, then that reviewer is also added to the attention set.

The upload of a new patchset by itself is not associated with a default change of the attention set. The owner may want to upload intermediate states or want to wait for CI systems before passing back the attention to reviewers.

These simple defaults are not expected to do the right thing in 100% of the cases, just maybe 90%. The owner of a change is still expected to manage the attention set individually and make sure that it reflects their expectations.

There are some special cases to be considered:

  • Work in Progress (WIP): When a change leaves WIP state with reviewers, then all reviewers are added to the attention set. When a change enters WIP state, then the attention set is cleared. While a change is in WIP state the defaults above for adding users to the attention set are not applied.
  • Merged and Private Changes: Will be handled with the same defaults as normal changes.

Deferred Enhancement: Expectations

This is an optional additional enhancement of the proposal. The above can be implemented with or without it. Actually you could argue that it has nothing to do with the attention set. :-)

At the moment we are not planning to include “Expectations” in v1 of the Attention Set.

We propose to associate every reviewer with an expectation message, which simply is “please review my change” by default, but can be changed by the owner or the reviewer to something like “please approve ownership once code review is completed” or “please vote on library compliance”.

Deferred Enhancement: Snoozing/Pausing

This is an optional additional enhancement of the proposal. The above can be implemented with or without it.

At the moment we are not planning to include “Snoozing/Pausing” in v1 of the Attention Set.

The attention set proposal above assumes that at any point in time it is either the owner‘s or the reviewers’ turn to act on a change. But often a user may wait for some event to happen, so they would like to unassign themselves until this event happens, and only then act on the code review. Some example scenarios taken from Use Cases:

  • snooze for a fixed time (being out of office or otherwise busy)
  • wait for tests or other checks to finish
  • as an owner on a “ready to submit” change wait for the parent or some other change to be merged, reviewed, released
  • staged review: wait for a review from someone else (e.g. a shadowed reviewer), then assign another reviewer (e.g. a shadowing reviewer, or someone with +2 powers)

We propose to allow a snoozing condition to be associated with a user that is currently not in the attention set.

Alternatives Considered

  • The Assignee feature could have been replaced entirely, because it is fairly similar to the proposed Attention Set feature. But it was pointed out that it is already used heavily for a use case that is not covered by the Attention Set: Singling out one person to convey urgency. So taking away the Assignee feature would be too disruptive for some teams.

Implementation Plan and Time Estimation

Will be implemented by Google and be ready for the 3.2 release.