Collaborative Working

In this chapter we look at ways of working collaboratively in a GitLab project.

GitLab allows multiple users to be developing a document at the same time. This potentially can lead to coordination problems. There are a number of ways to manage the coordination, with different approaches depending on where you are in the document development timeline.

Document Structure

Document structure is a key factor to support distributed development. If a document is a single file, then the coordination is going to be difficult, in many cases relying on knowing who has the “editorial pen”, and application of manually-generated changes to the single source.

Splitting a document into multiple files, based on chapter divisions, with the possibility to go beyond that to sections within chapters allows for individual pieces to be edited by different users simultaneously, and largely independently of each other.

Use of Branches

Using the GitLab capability for users to create separate branches of the document, which are essentially private copies, allows for proposed changes to be created, reviewed, revised, and agreed, prior to merging back to the master source of the document.

Branches

When you create a new branch, you are creating a snapshot of an existing branch, usually the main branch, at its current state. From there, you can make changes without affecting the main project, until you want to merge it back into the project. The history of your changes is tracked in your branch.

You should create a branch for each set of related changes you make. This keeps each set of changes separate from each other, allowing changes to be made in parallel, without affecting each other.

The Document Tree

First, and most important, if you haven’t done so already, familiarize yourself with the current draft document, and the way it is organized in the repository.

You should become familiar with the Repository, Issues, and Merge request links within the web browser view.

The File Tree

You can browse the file tree under Code → Repository.

In general, files beginning with underscore (_) and dot (.), or with suffix .yml are configuration files. They often need to be tailored for the document and are setup once. Files with suffix .sh are system scripts used by the build system. Files with suffix .adoc are AsciiDoc files containing the content of document.

We will only consider the manipulation of the AsciiDoc files in this document. Manipulation of shell scripts and document configuration are either handled by the editorial team or the project maintainer.

The top-level file tree typically looks as shown in Figure 1:

Figure 1. Browse the Top-Level Files in the Repository

The source for the document is developed in the modules directory, as shown in Figure 2.

The modules directory is divided into three main directories:

1	00-front-matter: frontmatter files, such as the preface
2	01-doc: the main document contents
3	99-appendices: the appendices for the document

Figure 2. Browse the Book Directory

A typical file tree is shown in the left pane of the Brackets editor as seen in Figure 3.

Contents of the file tree are as follows:

1	The bin directory with system scripts used to build the document
2	The modules directory containing the document sources, a series of directories for sections, and chapters of the document The frontmatter of the document is in the 00-front-matter directory; files that need updating here are the acknowledgements, preface, and references.
3	The main body of the document is in the 01-doc folder, with a subdirectory called pages for content, and one called images for image files. Chapter files are named chap01.adoc, chap02.adoc, …, chapNN.adoc.
4	For the document, if there are images they are placed into an images directory within the applicable section (00-frontmatter, 01-doc, etc.)

Figure 3. Typical File Tree Shown in the Brackets Editor

Adding a New Chapter

To insert a new chapter, either enter the “Web IDE” or use Brackets to add a new file within the 01-doc/pages directory.

In Brackets, right click on the 01-doc directory then into the pages folder, and select “New File”.

Figure 4. Add a File

An untitled file appears and in this example we overtype with chap05.adoc, following the naming convention.

Figure 5. Set the File Name

To have this new chapter appear in the document we would then also edit the top-level file _files.adoc and add it after chap04.adoc.

Figure 6. Add the File to the Spine File

If the chapter includes images, then they should be placed in the images subdirectory within the section directory (e.g. 01-doc). A convention is to initialize the images subdirectory with an empty file x, otherwise Git will not commit an empty directory (it only commits files).

The Collaborative Work Flow

It is recommended to adopt a standard work flow for collaboration (which was shown in Using the GitLab Platform in the Browser).

We recommend the work flow: issue → branch → merge request.

Raise or Assign the Issue, Create Branch

If there is already an issue that covers your idea, then assign it to yourself and start a branch with your document edits; if not, create an issue, then continue as before with a branch; for example, see Creating an Issue and Creating a New Branch.

Make Proposed Changes on the Branch

Make your edits in your branch in the AsciiDoc source files

Create a Merge Request

Once you have finished your proposed new content in your branch, you can do an initial check of the build, and then create a merge request; for an example, see Creating a Merge Request.

Small editorial changes (non-technical issues), such as correcting a spelling mistake, punctuation, and grammar can be done simply as an edit to the main branch.

Review the Merge Request and Obtain Consensus

A review should then be held on the merge request to achieve consensus on whether to apply the merge; for example, see Reviewing a Merge Request.

Manage releases using Branches

Once a document has been completed and published it is best to consult wih the editors about establishing a number of branches to manage releases. For example, three branches could be established to retain a copy of the published document, a branch for corrections, and a development branch.