Collaborative book-editing

Collaborative book-editing#

User types

This page is useful for user type 3, 4 and 5.

A jupyter book is composed out of many files which contain the educational content produced by you. Through the use of branches it is possible to work on the book at the same time as your team-members. Working on content for the book is mainly individual work, the beauty of Git comes in when everybody’s changes are merged into the main branch.

We have previously introduced the notions of using Git in the online environment (remote) or locally. All the (text, figures, etc.) files that make up the book are contained on the remote repository on GitLab or GitHub. This could be on an open repository on gitlab.com or github.com. In the context of creating educational books for students at TU Delft, the repository will most likely be located on gitlab.tudelft.nl or github.com/teachbooks. If this is the first time you interact with books, you’re advise to use github.com.

The steps involved are as follows:

  1. Assign a task to yourself (milestones, issues)

  2. Create your own version of the book as…

… by creating your own version of the book (branching) or selecting existing version:

  • branching

… by
(a) creating your own version (branching) (b) opening the repository locally (cloning) and selecting correct version (checkout branch):

  • branching

  • cloning

  • checkout branch

… by
(a) creating your own version (branching)
(b) updating your repository (pulling) and select correct version (checkout branch):

  • branching

  • pulling

  • branching / checkout branch

  1. Edit the book as …

… by directly adding changes on a single file to Git-timeline (committing):

  • adding file or making changes to single file

  • committing

… by
(a) making changes on a single / multiple file(s),
(b) selecting changes to be added to the Git-timeline (staging),
(c) adding those to the Git-timeline (committing) and
(d) adding those changes to GitLab/GitHub (pushing):

  • adding or making changes to file(s)

  • staging

  • committing

  • pushing

… by
(a) regularly obtaining updates from colleagues from GitLab/GitHub (pulling),
(b) solving potential incompatible changes (merge conflicts),
(c) making changes on a single / multiple file(s),
(d) selecting changes to be added to the Git-timeline (staging),
(e) adding those to the Git-timeline (committing) and adding those changes to GitLab/GitHub (pushing):

  • pulling

  • solving merge conflicts

  • adding or making changes to file(s)

  • staging

  • committing

  • pushing

… by
(a) making changes on a single / multiple file(s),
(b) checking changes locally,
(c) selecting changes to be added to the Git-timeline (staging),
(d) adding those to the Git-timeline (committing) and
(e) adding those changes to GitLab/GitHub (pushing):

  • adding or making changes to file(s)

  • checking changes locally

  • staging

  • committing

  • pushing

… by
(a) regularly obtaining updates from colleagues from GitLab/GitHub (pulling),
(b) solving potential incompatible changes (merge conflicts),
(c) making changes on a single / multiple file(s),
(d) checking changes locally,
(e) selecting changes to be added to the Git-timeline (staging),
(f) adding those to the Git-timeline (committing) and
(g) adding those changes to GitLab/GitHub (pushing):

  • pulling

  • solving merge conflicts

  • adding or making changes to file(s)

  • checking changes locally

  • staging

  • committing

  • pushing

  1. Check changes online

  2. Repeat steps 3 and 4 until you’re satisfied

  3. Reviewing (merge request), (eventually repeat steps 3 and 4) and combine (merging) your version with main draft version of book