🎉 Feature Introduction: Branches

Our answer here is still a work in progress (hence the slow roll out), but here is our current thinking:

There are a few nouns to introduce:

  1. Review: A structure containing the metadata, branches, and meta-conversation associated with a review.
  2. Review branch: A branch given to a specific person or group of people for the purpose of their review. This branch contains any review annotations or document changes. (Analogous to a Word doc with edits and comments made by a reviewer).
  3. Review Response: The combination of 1) a review branch, and 2) structured answers that are set by the review administrator. (Analogous to the email that a reviewer would send with comments and an attached Word doc).

In the beginning, I expect most peer-reviewed pubs to have a single Review containing ~three Review Responses (one from each of ~three reviewers).

The visibility of each element within a Review can be adjusted. Things we want to enable include:

  • Keeping the entire review private.
  • Setting the review metadata public, but the names and review responses of each reviewer private.
  • Setting the review and review responses public, but keeping the names of each reviewer private.
  • Setting the review public with a single review branch that is public-edit (or public-discuss), so that anyone can contribute to the review.

The UX we’re hoping to achieve is one where reviews always happen on Review Branches, with means of moving review annotations onto other branches if necessary (e.g. to share an insightful comment with the #public branch). The ability to move annotations across branches is important as it allows 1) review annotations that are interesting to bubble up to the #public branch, and 2) annotations made on the #public branch to be moved to an editable branch so that it can be addressed through changes to the document.

Less formal reviews that are simply styled as ‘Show up and annotate this doc’ could take place on either a #draft or #public branch depending on the preferences of the editor.