CMDI Best Practices Guide editing procedure

We are currently using/adopting/experimenting with GitBook as a means to edit and publish the CMDI Best Practices Guide. This page serves to document the current procedure and conventions for editing this document.

The GitBook project for the Guide can be found at ​gitbook.com/book/clarin-eric/cmdi-best-practices; the published version is available at ​clarin-eric.gitbooks.io/cmdi-best-practices.

Also, if you have any, please share your experiences with GitBook if you think they may be helpful others.

How to contribute?

In principle the Guide is edited by members of the CMDI and Curation Taskforces. However anyone is welcome to contribute by creating comments/starting discussions. This can be done from the interactice ​online version of the document. Each paragraph has the option to add a new comment (which will create a ​discussion, allowing for follow-up comments); the following screenshot shows this feature in the GitBook reader:

Procedure for editors

Editors can work on the ​cmdi-taskforce/cmdi-best-practices fork (that we will call the 'draft' from here on).

In brief, the following cycle should define the procedure for editing and publishing iterations of the Guide:

• Editors create change request (typically one branch per (sub)section)
  • Please do not directly edit the 'primary version'!
• Editors make modifications in the change request branches
• Editors discuss the pending changs amongst eachother
• Main editors accept one or more change request and merge the contents into the primary version of the draft
• Main editors carry out an editorial pass on the draft
• The changes in 'master' are merged into the main project/repository; this constitutes a 'release' of the Guide

The following sections describe parts of the process in more detail.

'Change requests' (branches)

Regular editors that want to work on sections of the document, or others that want to propose a edit (even a small one ;)), should do so through change requests. These effectively act as branches (GitBook being built on git) with a predefined purpose although change requests cannot be explicitly scoped. In the editor, you can select the change request you wish to work on:

If no change request exists for the task or section of the document you want to work on, please create one before making changes. You can do so either from the editor or from the ​change requests page. If you choose for the latter option, you can press the Open in editor button to start making your change request.

This triggers the following dialogue:

To edit a change request via its change request page:

You can discuss change requests by going to the ​change requests page. Here you can also find, for each change request, a list of concrete changes that are part of the change requests (a diff), as well as a link to the preview version that allows you to share the unmerged contents of the individual branches e.g. for review.

Applying your change request to the primary version of the draft

Change requests can be accepted, i.e. the change request branch can be merged into a target branch. Although you may have the rights to do this, please wait until the changes have been discussed.

Note that it may be the case that conflicts have to be resolved before the merge can be completed. This can be avoided by limiting work on a paragrap (or ideally section) to a single change request. GitBook does provide facilities that make resolving conflicts relatively easy.

Releasing a version of the Guide

After one or more change requests have been accepted into the master (i.e. the change request branches have been merged into the master branch), a final editorial pass can be made before merging the changes in the primary version of the main repository.

GitBook will then automatically publish the update, and also generate the various downloadable versions such as the PDF version.

Account

As GitBook imposes a limit to the number of members of an organisation, some of us have to use a shared user for editing. You can use the following credentials to ​login:

• User: cmdibestpractices
• Password: pxm9skapzvet97qg

Please mention your name if posting anything while logged in as this user.

Experiences with GitBook

You can use this section to share your experience with GitBook and related hints/tips...

• Alexander had trouble signing in/up after receiving an invitation. A report has been submitted to GitBook...