Guidelines

Submission Instructions

In order to simplify submissions and avoid any merge conflicts, it is recommended to create a separate branch for each chapter (considering that every preceptor is working on a separate chapter). A good template to follow would be to name the branch as your-name/chapter-name.

1. After cloning the repository on your local machine, create a new branch by using: git checkout -b <branch-name>. If working on an existing branch, use git checkout <branch-name>. To check which branch you are on use: git branch. If the branch doesn't exist on the remote repository, push the branch using: git push origin <branch-name>
2. Make your edits, commit and push it to your branch using: git add ., git commit -m 'commit comment' followed by git push origin <branch-name>.
3. The changes will be pushed to the remote branch. This now should be followed by a pull request. Go to the remote repository and you'll be able to see a pull request option with your recent commit on your branch. Click to create pull request. One of the admin will merge it to the master and publish it using a release.
4. It is better to always pull the latest changes from your master branch to your local branch using git pull origin master. In case of some structural change, this can prevent a major merge conflict.

Avoiding Merge Conflicts:

Since there are multiple contributors to this workbook, there are some best practices to be taken care of in order to avoid merge conflicts, which often arise when more than a single contributor is changing a line of code around the same time. Resolving it can become tedious.

The taking care of the following set of steps, conflicts can be avoided:

• Divide and assign the modules among the contributors
• In case, contributors are working on the same module, frequently communicate regarding updates before pushing any changes
• Pull and push changes frequently rather than resisting to push a large set of changes.
• There is a high probability of these conflicts arising in case the structure, content list of the workbook or the name of a notebook is changed. Be cautious in that scenario and inform all the contributors clearly about such a change.
• Always check the generated html file before a release to the website. This way a conflict can be easily caught before it causes a major issue on the website.

Notebook Structure:

All notebooks or markdown files have to be placed under the textbook/ folder. The structure has been kept simple where each folder is a chapter whereas every subfolder within the numbered folder is the section. You can create further folders within these section folders to divide each section into sub-sections.

To display them on the book in an order, each file has to be linked on _toc.yml file under the textbook/ folder, which is the table of contents and structures the textbook according to the configuration given. The _toc.yml should be easy to understand and amend. However, it is recommended to have one admin to make those changes in order to avoid a major conflict catastrophe. If a file is not linked on _toc.yml, it won't build and publish. The textbook is divided into chapters, where each chapter has sections and each section can have further sub-sections. All the chapters, sections and sub-sections can be given a title in the table of contents. The root in the top is the first page of the textbook. It is better to read more about it on this short document.

To add a notebook or amend the structure, the author must communicate with the admin to change the table of contents, otherwise, the content won’t be published. Usually the admin will changes the table of contents after submission of a pull request. The purpose of this is to avoid any major structural conflict which can probably occur when working in a team.