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 rahim/chapter-4.

1. 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 and 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 more oftenly rather than resisting to push a large set of changes. You will do that using the manage promote command. 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 using the promote command to deploy it 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/content/ folder. The structure has been kept simple where each folder is a chapter whereas every subfolder within the numbered folder is the sub-chapter. To add a notebook or amend the structure, the author must email the admin to change the table of contents, otherwise, the content won’t be published. The purpose of this is to avoid any major structural conflict which can probably occur when working in a team.