🎉 Feature Introduction: Branches


Branches are a new feature to improve the way PubPub handles permissions and version history. Branches also lay the groundwork for new peer review functionality. We’re excited! But first, the basics:

  • Branches are contained within Pubs.
  • A Pub can have unlimited branches, but as we roll out, Pubs will be limited to two branches: #public and #draft.
  • Each branch contains a history of document changes. Branches can be ‘ahead’ or ‘behind’ other branches, or could diverge entirely.
  • Branches have their own permissions. For example, the #public branch may allow anyone to read it, while the #draft branch allows only a few people to read and edit.
  • All discussions and annotations are kept within (and share permission with) a single branch.

The basic workflow is to make your changes to a private branch, and then Merge those changes into a public branch. For example, you may spend a week writing on #draft, and then at some point Merge those changes into #public. Those familiar with the git workflow will find this feels quite similar.

When an author doesn’t have permission to directly Merge their changes into #public (e.g. because it needs to go through a review process), they will be able to create a Review which has a source and destination branch. Successful completion of this Review will enable a Merge to content from the source branch to the destination branch.

The history on the #public branch will show the Merges as single updates - while the #draft branch will retain the full history of updates.

Why do this?

Writing, publishing, and reviewing is complex. Most tools ignore this complexity, and simplify the model such that there is only ‘one’ document. Our experience working with scientists, authors, and publishers has shown us that what really happens is a cacophony of different documents, with names like ‘draft_v5_alexNotes.doc’. These documents get shared over email, Dropbox, or in some horrible cases, WhatsApp message attachments. Often times the management of these documents takes more time than the actual review and editing processes.

We’ve spent a lot of time thinking about these complexities and think that Branches offer an exciting solution.

Is this git?

No. Git is a version control system that was designed to allow a distributed group of people to work together on a single code base. It works phenomenally well and has enabled a whole suite of open-source cultures. If git would work here, we’d be thrilled. The primary reason we don’t use git is that prose is simply different than code. Code is line-by-line plain text, whereas prose can be richly formatted and chunked into paragraphs that have semantic meaning. Git just isn’t designed to handle the nuance and specifics of prose. The output one would expect from a ‘View changes’ screen for Prose are simply ill-served by the output of a git-based diff algorithm.

Sounds good, what now?

We’re slowly rolling out branches. To begin, pubs will be limited to two branches, #public and #draft. Eventually, you will be able to create new branches off of existing branches, merge them back in, or keep them separate (e.g. to allow you to have a branch that is a translation of another branch).

This is new for us and newer for all of you. Journals, conferences, and books don’t typically work with a system of Branches, so the language and expected interfaces are all new territory. We’d love for you to be part of the process of defining what language and interfaces provide accessible and clear experiences. Let us know what is working for you and what isn’t. Constructive suggestions are always appreciated.


How do you envision that peer review operates within the branches framework?

I’m imagining that if a journal wanted a closed peer review process, then the peer review discussions held would be held within the draft branch (or a separate branch once those are possible). However, if you wanted open peer review, then the discussion should still be carried out in the public branch. Does this sound correct? Or maybe there is another, smarter way to use the branches for this that I’m not thinking of.

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.