pages/design-docs/attention-set/solution-1-workflow.md

---
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](/design-docs/attention-set-use-cases.html) before this doc.*

## <a id="overview">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](solution-1-user-interface.md) 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](#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](https://gerrit-review.googlesource.com/Documentation/rest-api-changes.html#mark-as-reviewed)
feature and its associated
[bolding of change-list items](https://gerrit-review.googlesource.com/Documentation/dev-stars.html#reviewed-star).

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.

## <a id="defaults">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.

## <a id="expectations">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".

## <a id="snoozing">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](use-cases.md):

*   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.

## <a id="implementation">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.

## <a id="implementation">Implementation Plan and Time Estimation

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