Publications Development using the GitLab® and AsciiDoc® Toolchain

Git (and distributed source control more generally) is a powerful tool for enabling collaboration on complex digital artifacts. It is probably no understatement to say that the Linux^® project would not have succeeded without it.

For a deeper understanding of distributed source control and why it is important see the section “Version Control” in the book Managing Digital: Concepts and Practices (see Referenced Documents).

In order to collaborate on documents using The Open Group GitLab facilities, you have two choices:

The advantage of the first approach is that no software installation is required, you do not need to know how to code, use a command line, or install Git (the underlying software that enables the GitLab platform). The GitLab environment provides web-based tools to enable all actions for project collaboration through the web browser. This approach is recommended for most users, and especially first-time users. We explore this approach in detail in Chapter 5, and even if you are an advanced user we recommend you read that chapter first.

The second approach is best suited for those who want to make advanced use of the environment, such as being able to work disconnected from the Internet. This allows you to take a local copy of a project, work on it, and then submit changes back to the main project. In order to do this, you first need to be able to use Git and be familiar with the basic operations. We cover this in Chapter 6 and subsequent chapters. There are also many online sources of information on how to use Git, but a particularly good one is titled Pro Git by Scott Chacon and Ben Straub; see Referenced Documents.

The GitLab website also has some GitLab Basics and Help Files (see Referenced Documents), which also give a very high-level overview; many of these will be more useful as you move through the chapters in this document.

It is hard to avoid the jargon, so here goes …​

Branch, Branching

Branching is the way to work on different versions of the project files at one time. When you create a branch you are making a copy of the project. This allows you to develop changes.

Commit

Saved changes are called “commits”. Each commit has an associated message with it describing why the change was made – the history of changes.

Merge Request

Merge requests are the heart of collaboration, where you are proposing changes and requesting they be reviewed and merged into the project.

The “project” is the basic unit of collaboration on content within the GitLab environment. Forums or Consortia may have multiple projects; to facilitate access to all eligible members, a group will be set up for each Forum, Work Group, or Consortium, and eligible members will be added to the group. Any project under that group will be open to all group members; members of other groups will not have access to the projects.

A person may of course be a member of more than one group if their membership entitlements permit.

Only members of a group can access projects that are set up under that group. Group membership is the principal way we limit access to projects, both to keep material inside a Forum until released, and also to enforce any national access controls. Users who are participants in multiple groups must take care to set up projects in appropriate groups, and also have a responsibility not to share information between groups.