| 5 | | The !GitBook project for the Guide can be found at [https://www.gitbook.com/book/clarin-eric/cmdi-best-practices gitbook.com/book/clarin-eric/cmdi-best-practices]; the published version is available at [https://clarin-eric.gitbooks.io/cmdi-best-practices/ clarin-eric.gitbooks.io/cmdi-best-practices]. |
| 6 | | |
| 7 | | [[Image(about.png, 480px)]] |
| 8 | | |
| 9 | | Also, if you have any, please [#ExperienceswithGitBook share your experiences with GitBook] if you think they may be helpful others. |
| 10 | | |
| 11 | | == How to contribute? == |
| 12 | | 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 [https://clarin-eric.gitbooks.io/cmdi-best-practices/ online version of the document]. Each paragraph has the option to add a new comment (which will create a [https://www.gitbook.com/book/clarin-eric/cmdi-best-practices/discussions discussion], allowing for follow-up comments); the following screenshot shows this feature in the !GitBook reader: |
| 13 | | |
| 14 | | [[Image(discussion.png, 480px)]] |
| 15 | | |
| 16 | | == Procedure for editors == |
| 17 | | |
| 18 | | Editors can work on the [https://www.gitbook.com/book/cmdi-taskforce/cmdi-best-practices/details cmdi-taskforce/cmdi-best-practices fork] (that we will call the 'draft' from here on). |
| 19 | | |
| 20 | | In brief, the following cycle should define the procedure for editing and publishing iterations of the Guide: |
| 21 | | |
| 22 | | * Editors create change request (typically one branch per (sub)section) |
| 23 | | * Please do '''not directly edit the 'primary version''''! |
| 24 | | * Editors make modifications in the change request branches |
| 25 | | * Editors discuss the pending changs amongst eachother |
| 26 | | * Main editors accept one or more change request and merge the contents into the primary version of the ''draft'' |
| 27 | | * Main editors carry out an editorial pass on the ''draft'' |
| 28 | | * The changes in 'master' are merged into the main project/repository; this constitutes a 'release' of the Guide |
| 29 | | |
| 30 | | The following sections describe parts of the process in more detail. |
| 31 | | |
| 32 | | === 'Change requests' (branches) === |
| 33 | | 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: |
| 34 | | |
| 35 | | [[Image(select-branch.png, 480px)]] |
| 36 | | |
| 37 | | 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 [https://www.gitbook.com/book/cmdi-taskforce/cmdi-best-practices/changes change requests page]. If you choose for the latter option, you can press the `Open in editor` button to start making your change request. |
| 38 | | |
| 39 | | [[Image(create-change-request.png, 240px)]] |
| 40 | | |
| 41 | | This triggers the following dialogue: |
| 42 | | |
| 43 | | [[Image(create-branch.png, 480px)]] |
| 44 | | |
| 45 | | To edit a change request via its change request page: |
| 46 | | |
| 47 | | [[Image(open-in-editor.png, 480px)]] |
| 48 | | |
| 49 | | You can discuss change requests by going to the [https://www.gitbook.com/book/cmdi-taskforce/cmdi-best-practices/changes 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. |
| 50 | | |
| 51 | | [[Image(changerequest.png, 480px)]] |
| 52 | | |
| 53 | | === Applying your change request to the primary version of the draft === |
| 54 | | 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__. |
| 55 | | |
| 56 | | 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. |
| 57 | | |
| 58 | | === Releasing a version of the Guide === |
| 59 | | 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. |
| 60 | | |
| 61 | | !GitBook will then automatically publish the update, and also generate the various downloadable versions such as the PDF version. |
| 62 | | |
| 63 | | == Account == |
| 64 | | 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 [https://legacy.gitbook.com/login login]: |
| | 5 | Overleaf links for the **draft document**: |
| | 6 | * [https://www.overleaf.com/read/wfsggvdjbbgj Read] |
| | 7 | * [https://www.overleaf.com/5272115735bdsxsshpmctp Edit] (**ONLY to be used with editors, do __NOT__ share publicly ! **) |
