Documentation/user-attention-set.txt

= Gerrit Code Review - Attention Set

The Attention Set will be part of the upcoming 3.3 release (due late 2020).
We are testing at on some hosts on `googlesource.com` right now. If you build
your Gerrit from master, you can enable it using
link:config-gerrit.html#change.enableAttentionSet[enableAttentionSet].

Report a bug or send feedback using
link:https://bugs.chromium.org/p/gerrit/issues/entry?template=Attention+Set[this Monorail template].

[[whose-turn]]
== Whose turn is it?

Code Review is a turn-based workflow going back and forth between the change
owner and reviewers. For every change Gerrit maintains an "Attention Set" with
users that are currently expected to act on the change. Both on the dashboard
and on the change page, this is expressed by an arrow icon before the user name:

image::images/user-attention-set-icon.png["account chip with attention icon", align="center"]

While the attention set brings clarity to the process it also comes with
responsibilities and expectations. To provide the best outcome for all users, we
suggest following these principles:

* Reviewers are expected to respond in a timely manner when it is their turn. If
  you don't plan to respond within ~24h, then you should either remove yourself
  from the attention set or you should at least send a clarification message to
  the change owner.
* Change owners are expected to manage the attention set of their changes
  carefully. They should make sure that reviewers are only in the attention set
  when the owner waits for a response from them.

On the plus side you can strictly ignore everyone else's changes, if you are not
in the attention set. :-)

=== Rules

To help with the back and forth, Gerrit applies some basic automated rules for
changing the attention set:

* If reviewers are added to a change, then they are added to the attention set.
* If an active change is submitted, abandoned or reset to "work in progress",
  then all users are removed from the attention set.
* Replying (commenting, voting or just writing a change message) removes the
  replying user from the attention set. And it adds all participants of comment
  conversations that the user is replying to.
* If a *reviewer* replies, then the change owner (and uploader) are added to the
  attention set.
* Only owner, uploader, reviewers and ccs can be in the attention set.

*!IMPORTANT!* These rules are not meant to be super smart and to always do the
right thing, e.g. if the change owner sends a reply, then they are often
expected to individually select whose turn it is instead of adding *all*
reviewers to the attention set.

Note that just uploading a new patchset is not a relevant event for the
attention set to change.

=== Interaction

There are two ways to interact with the attention set: The hovercard of owner
and reviewer chips and the "Reply" dialog.

*The hovercard* (on both the Dashboard and Change page) contains information
about whether, why and when a user was added to the attention set. It also
contains an action for adding/removing the user to/from the attention set.

image::images/user-attention-set-hovercard.png["user hovercard with info and action", align="center"]

*The reply dialog* contains a section for controlling to whom the turn should be
passed.

image::images/user-attention-set-reply-modify.png["reply dialog section for modifying", align="center"]

If you do not click "MODIFY", then the backend will just apply the
automated rules as stated above. If you click "MODIFY", then the section will
expand and you can select and de-select users by clicking on their chips.
Whatever you select here will be the new state of the attention set for this
change. As a change owner make sure to remove reviewers that you don't expect to
take action.

image::images/user-attention-set-reply-select.png["reply dialog section for selecting users", align="center"]

=== Bots

[Caveat: This is not fully implemented yet!]

The attention set is meant for human reviews only. Triggering bots and reacting
to their results is a different workflow and not in scope of the attenion set.
Thus members of the "Non-Interactive Users" group will never be added to the
attention set. And replies by such users will not add the change owner to the
attention set.

=== Dashboard

The default *dashboard* contains a new section at the top called "Your Turn". It
lists all changes where the logged-in user is in the attention set. As an active
developer one of your daily goals will be to iterate over this list and clear
it.

image::images/user-attention-set-dashboard.png["dashboard with Your Turn section", align="center"]

Note that you can also navigate to other users' dashboards to check their
"Your Turn" section.

=== Assignee

While the "Assignee" feature can still be used together with the attention set,
we do not recommend doing so. Using both features is likely confusing. The
distinct feature of the "Assignee" compared to the attention set is that only
one user can be the assignee at the same time. So the assignee can be used to
single out one person or escalate, if there are multiple reviewers. Since
*every* reviewer in the attention set is expected to take action, singling out
is not likely to be important and also still achievable with the attention set.
Otherwise "Assignee" and "Attention Set" are very much overlapping, so we
recommend to only use one of them.

The "Assignee" feature can be turned on/off with the
link:config-gerrit.html#change.enableAttentionSet[enableAssignee] config option.

=== Bold Changes / Mark Reviewed

Before the attention set feature, changes were bolded in the dashboard when
*something* happened and you could explicitly "mark a change reviewed" on the
change page. This former way of keeping track of what you should look at has
been replaced by the attention set.

GERRIT
------
Part of link:index.html[Gerrit Code Review]

SEARCHBOX
---------