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.