Merge branch 'main' of gitlab.tudelft.nl:interactivetextbooks-citg/jupyter-book-manual

book/workflows/branches.md

@@ -11,15 +11,15 @@ The act of making a new branch from an existing one is called *branching*. Usual
 
 **Create your own version as ...**
 
-`````````{tab-set}
+```````````{tab-set}
 
-````````{tab-item} ... user type 3 ...
+``````````{tab-item} ... user type 3 ...
 
-**... by directly creating your own version of the book (branching) or by selecting an existing version in ...**
+**... by directly creating your own version of the book (branching) or selecting an existing version in ...**
 
-`````{tab-set}
+```````{tab-set}
 
-````{tab-item} ... GitLab
+``````{tab-item} ... GitLab
 
 1. Navigate to the repository of your project. Under the project description, you should see a menu button with a "+" in it (see {numref}`new-branch-button`). Click this button, then click on "New branch".
 
@@ -37,47 +37,66 @@ Click the highlighted button to make a new branch.
 We're making a new branch called `chapter-2` from the `main` branch.
 ```
 
-3. You should be sent back to an overview page of your repository. In the branch selection menu (see {numref}`new-branch-repo`), it should now say `chapter-2` instead of `main`. Here you can also select another existing branch.
+3. You should be sent back to an overview page of your repository. In the branch selection menu (see {numref}`new-branch-repo`), it should now say `chapter-2` instead of `main`. Here you can also select another existing branch which is what we previously called `selecting an existing version`.
 
 ```{figure} ../images/gitlab-new-branch-repo.png
 :name: new-branch-repo
 
 The circled menu is the branch selection menu. 
 ```
-````
+``````
 
-````{tab-item} ... GitHub
+``````{tab-item} ... GitHub
 
 1. Open the repository in which you want to work in. In the top bar you will see your current branch `main` and next to that there is a tab called `Branches`. 
 
-```{figure} ../figures/NewBranch_GitHub.PNG
-```
+<figure align="center">
+    <img src="figures/NewBranch_GitHub.PNG" alt="Example Image" width="650">
+</figure>
+
 2. Clicking on `Branches` will bring you to an overview of all the branches in the repository. Click on the green `Create Branch` button.
 
-```{figure} ../figures/NewBranch_GitHub2.PNG
-```
+<figure align="center">
+    <img src="figures/NewBranch_GitHub2.PNG" alt="Example Image" width="650">
+</figure>
+
 3. Finally, give your branch a name and specifiy the source branch. <br>
 Tip: It makes sense to give the branch a name related to the content you will be creating or altering.
 
-```{figure} ../figures/NewBranch_GitHub3.PNG
-```
-````
-`````
-````````
+<figure align="center">
+    <img src="figures/NewBranch_GitHub3.PNG" alt="Example Image" width="350">
+</figure>
 
-````````{tab-item} ... user type 4 and 5 ...
+4. You will find your new branch in the drop down menu as seen on the figure below. You can then select your new branch and start working in it (new version) but you can also work in any other branch if you are helping out a colleague with their chapter for example (existing version).
 
-**Select the statement that applies to you.**
+<figure align="center">
+    <img src="figures/NewBranch_GitHub4.PNG" alt="Example Image" width="650">
+</figure>
+``````
+```````
+``````````
+
+``````````{tab-item} ... user type 4 and 5 ...
+
+As user type 4 and 5, you make changes to the book locally on your computer rather than online on GitLab/GitHub. This allows you to create more complex and interactive sections to your book. Before you can start, there are a few preparatory steps you need to take. 
+
+**Cloning**
+
+In order to create your own version, you will first have to open the repositery. Then, you will need to clone the repositery to your computer. This procedure is called cloning.
+
+**Branching**
+
+If your repositery is already cloned on your computer, you are almost ready to start editing the book. However, remember that you are most likely not the only person making changes to the book. To keep an overview of the changes made by you and your colleages, it is important that changes are first made in a 'copy' of the book and are then merged into the final version. This is done through branching! You can create your version of the book by creating a new version (branch) or you can continue the work in an existing version (checkout branch). 
+
+`````````{tab-set}
+
+````````{tab-item} Cloning
+
+**1. Open the repository locally using ...**
 
 ```````{tab-set}
 
-``````{tab-item} I am opening the repositery for the first time (Cloning)
-
-**I would like to open the repository locally (cloning) using ...**
-
-`````{tab-set}
-
-````{tab-item} ... GitLab ...
+``````{tab-item} ... GitLab
 
 1. Navigate to the repository of your book. Click on the blue button that says "Clone" ({numref}`gitlab-clone`), and copy the link under "Clone with SSH".
 
@@ -86,9 +105,9 @@ Tip: It makes sense to give the branch a name related to the content you will be
 
 The cloning menu.
 ```
-````
+``````
 
-````{tab-item} ... GitHub ...
+``````{tab-item} ... GitHub
 
 1. Open the repository that you would like to clone. In the top bar on the right, you will a green button called `<> Code`.
 
@@ -101,9 +120,9 @@ The cloning menu.
 <figure align="center">
     <img src="figures/Clone_GitHub.PNG" alt="Example Image" width="400">
 </figure>
-````
+``````
 
-````{tab-item} ... GitHub through GitHub Desktop ...
+``````{tab-item} ... GitHub through GitHub Desktop
 
 1. Open the repository that you would like to clone. In the top bar on the right, you will a green button called `<> Code`.
 
@@ -123,14 +142,14 @@ The cloning menu.
     <img src="figures/CloneRepo_TroughGithubdesk.PNG" alt="Example Image" width="400">
 </figure>
 
-You've cloned the repository now directly, so you can skip the next step.
-````
-`````
+You have now directly cloned the repository, so you can skip the next step!
+``````
+```````
 
-**... and I would like to clone the local repositery with ...**
+**2. Clone the local repositery with ...**
 
-`````{tab-set}
-````{tab-item} ... VS Code
+```````{tab-set}
+``````{tab-item} ... VS Code
 
 1. Open a new VS Code window. You should be greeted with a welcome page ({numref}`vscode-welcome`). On this page, click "Clone Git Repository". Alternatively, open the Source Control menu from the left side bar, and click on "Clone Repository".
 
@@ -143,34 +162,122 @@ The VS Code welcome screen.
 2. On the top of your screen, you should get a prompt asking you for a URL. In this field, paste the link you copied from GitLab and press enter. It will ask you to choose the location of the repository. After you've chosen a location, a final prompt will show up asking if you want to open the repository. Click on "Open".
 
 3. You now have a local copy of the repository.
-4. Now you can start branching. Have a look at the other section!
-````
+``````
 
-````{tab-item} ... GitHub Desktop
+``````{tab-item} ... GitHub Desktop
 
 1. You have previously copied the link of the repositery you would like to clone from GitLab or GitHub. In GitHub Desktop, navigate to the top bar, click on `File` and then on `Clone repositery`.
 
-```{figure} ../figures/CloneRepo_Githubdesk.PNG
-```
+<figure align="center">
+    <img src="figures/CloneRepo_Githubdesk.PNG" alt="Example Image" width="350">
+</figure>
+
 2. In the top bar click on `URL`.
 
-```{figure} ../figures/CloneRepo_TroughGithubdesk.PNG
-```
+<figure align="center">
+    <img src="figures/CloneRepo_TroughGithubdesk.PNG" alt="Example Image" width="400">
+</figure>
+
 3. Simply paste the link, specify the working directory (location where you would like to save the folder locally) and click on 'Clone'.
 
-````
-`````
+4. You now have a local copy of the repository.
+
 ``````
+```````
+**You have now cloned the repositery to your computer and you can start branching. <br> 
+Have a look at the other section!**
+````````
 
-``````{tab-item} I have previously opened the repository (Branching)
+````````{tab-item} Branching
 
-**I want to (1) update my repository (pulling) and <br>
-            (2) create my own version (branching) or select an existing version (checkout branch) using ...**
+**I want to... <br>
+(a) update my repository (pulling) and <br>
+(b) create my own version (branching) or select an existing version (checkout branch) using ...**
+
+```````{tab-set}
+``````{tab-item} ... Git in VS Code
+
+**1. Update your repositery**
+
+Since you are working in a repositery with multiple colleagues, it is good practice to make sure your local repositery is up to date before you start branching. This is especially important when you want to work in an existing branch. In that case you want to make sure that the existing branch shows in your local repositery. Therefore, you first need to pull all the changes from the remote repositery to your local repositery. Simply click the Icon with the two arrows.
+
+```{figure} ../figures/Pull_VS.PNG
+:name: Pull_VS
+
+Location of the branch menu.
+```
+Once your local repositery is up to date you can start to work either in a new branch (new version) or in an existing branch (exisiting version). 
+
+**2. Create your own version by creating a new branch**
+
+Although it is possible to create new branches in VS Code directly, creating new branches on the remote repositery (on GitLab or GitHub) is better for collaborating because the new branch becomes immediately visible to everyone working in the repositery as opposed to becoming visible after being pushed to the remote repositery.
+
+Create a new branch in...
 
 `````{tab-set}
-````{tab-item} ... Git in VS Code
+````{tab-item} ... GitLab
 
-1. The next step is to *check out* our new branch in VS Code. *Checking out* means that we're changing our working branch (i.e., the one to which we will be committing our changes) from one to the other. 
+1. Navigate to the repository of your project. Under the project description, you should see a menu button with a "+" in it (see {numref}`new-branch-button`). Click this button, then click on "New branch".
+
+```{figure} ../images/gitlab-branch.png
+:name: new-branch-button
+
+Click the highlighted button to make a new branch.
+```
+
+2. A new page opens ({numref}`new-branch-menu`), on which you can specify the name of your branch and the source branch. Try to think of a good name for your branch. For example, `chapter-2` is a suitable name if we're going to be working on Chapter 2 of our book. After you've made sure that the selected source branch is correct, click "Create branch".
+
+```{figure} ../images/gitlab-branch-name.png
+:name: new-branch-menu
+
+We're making a new branch called `chapter-2` from the `main` branch.
+```
+
+3. You should be sent back to an overview page of your repository. In the branch selection menu (see {numref}`new-branch-repo`), it should now say `chapter-2` instead of `main`.
+
+```{figure} ../images/gitlab-new-branch-repo.png
+:name: new-branch-repo
+
+The circled menu is the branch selection menu. 
+```
+
+You have now created a new branch on the remote, make sure to fetch & pull again to see it on the local repositery!
+````
+
+````{tab-item} ... GitHub
+
+1. Open the repository in which you want to work in. In the top bar you will see your current branch `main` and next to that there is a tab called `Branches`. 
+
+<figure align="center">
+    <img src="figures/NewBranch_GitHub.PNG" alt="Example Image" width="650">
+</figure>
+
+2. Clicking on `Branches` will bring you to an overview of all the branches in the repository. Click on the green `Create Branch` button.
+
+<figure align="center">
+    <img src="figures/NewBranch_GitHub2.PNG" alt="Example Image" width="650">
+</figure>
+
+3. Finally, give your branch a name and specifiy the source branch. <br>
+Tip: It makes sense to give the branch a name related to the content you will be creating or altering.
+
+<figure align="center">
+    <img src="figures/NewBranch_GitHub3.PNG" alt="Example Image" width="350">
+</figure>
+
+4. You will find your new branch in the drop down menu as seen on the figure below. You can then select your new branch and start working in it (new version).
+
+<figure align="center">
+    <img src="figures/NewBranch_GitHub4.PNG" alt="Example Image" width="650">
+</figure>
+
+5. jupYou have now created a new branch on the remote, make sure to fetch & pull again to see it on the local repositery!
+````
+`````
+
+**3. Work in an existing branch**
+
+If you want to work in an existing branch you need to *check out* our new branch in VS Code. *Checking out* means that we're changing our working branch (i.e., the one to which we will be committing our changes) from one to the other. 
 
 In VS Code, open the branch menu from the bottom left (see {numref}`git-branch-menu-main`). You'll be be greeted with a menu that looks like the one in {numref}`git-branch-selection-menu`. In this menu, we get an overview of the branches of our repository. Notice that our new branch `chapter-2` appears as `origin/chapter-2`, and has a cloud icon in front of it. This means that the branch only exists on the remote repository. 
 
@@ -187,19 +294,89 @@ Location of the branch menu.
 
 The branch selection menu, where our new branch has shown up. From this menu you can also select (checkout in git terms) another existing branch.
 ```
+``````
+``````{tab-item} ... GitHub Desktop
 
-2. It can be that multiple people ar making changes to one branch. We have to make sure that we are using the most up to date version of the branch. Therefore, we need to pull all the changes from the remote repositery to our local repositery. Simply click the Icon with the two arrows.
+**1. Update your repositery**
 
-```{figure} ../figures/Pull_VS.png
-:name: Pull_VS
+Since you are working in a repositery with multiple colleagues, it is good practice to make sure your local repositery is up to date before you start branching. This is especially important when you want to work in an existing branch. In that case you want to make sure that the existing branch shows in your local repositery. Therefore, you first need to pull all the changes from the remote repositery to your local repositery.  
 
-Location of the branch menu.
+This synchronizes the remote repositery with your local repositery on your computer. Click on `Fetch` in the top bar. Then on the same place, click on 'Pull'. 
+
+<figure align="center">
+    <img src="figures/Fetch.PNG" alt="Example Image" width="650">
+</figure>
+
+**2. Create your own version by creating a new branch.**
+
+Although it is possible to create new branches in GitHub Desktop directly, creating new branches on the remote repositery (on GitLab or GitHub) is better for collaborating because the new branch becomes immediately visible to everyone working in the repositery as opposed to becoming visible after being pushed to the remote repositery.
+
+Create a new branch in...
+
+`````{tab-set}
+````{tab-item} ... GitLab
+
+1. Navigate to the repository of your project. Under the project description, you should see a menu button with a "+" in it (see {numref}`new-branch-button`). Click this button, then click on "New branch".
+
+```{figure} ../images/gitlab-branch.png
+:name: new-branch-button
+
+Click the highlighted button to make a new branch.
 ```
 
-````
-````{tab-item} ... GitHub Desktop
+2. A new page opens ({numref}`new-branch-menu`), on which you can specify the name of your branch and the source branch. Try to think of a good name for your branch. For example, `chapter-2` is a suitable name if we're going to be working on Chapter 2 of our book. After you've made sure that the selected source branch is correct, click "Create branch".
 
-1. The next step is to *check out* our new branch in VS Code. *Checking out* means that we're changing our working branch (i.e., the one to which we will be committing our changes) from one to the other. 
+```{figure} ../images/gitlab-branch-name.png
+:name: new-branch-menu
+
+We're making a new branch called `chapter-2` from the `main` branch.
+```
+
+3. You should be sent back to an overview page of your repository. In the branch selection menu (see {numref}`new-branch-repo`), it should now say `chapter-2` instead of `main`.
+
+```{figure} ../images/gitlab-new-branch-repo.png
+:name: new-branch-repo
+
+The circled menu is the branch selection menu. 
+```
+
+You have now created a new branch on the remote, make sure to fetch & pull again to see it on the local repositery!
+````
+
+````{tab-item} ... GitHub
+
+1. Open the repository in which you want to work in. In the top bar you will see your current branch `main` and next to that there is a tab called `Branches`. 
+
+<figure align="center">
+    <img src="figures/NewBranch_GitHub.PNG" alt="Example Image" width="650">
+</figure>
+
+2. Clicking on `Branches` will bring you to an overview of all the branches in the repository. Click on the green `Create Branch` button.
+
+<figure align="center">
+    <img src="figures/NewBranch_GitHub2.PNG" alt="Example Image" width="650">
+</figure>
+
+3. Finally, give your branch a name and specifiy the source branch. <br>
+Tip: It makes sense to give the branch a name related to the content you will be creating or altering.
+
+<figure align="center">
+    <img src="figures/NewBranch_GitHub3.PNG" alt="Example Image" width="350">
+</figure>
+
+4. You will find your new branch in the drop down menu as seen on the figure below. You can then select your new branch and start working in it (new version).
+
+<figure align="center">
+    <img src="figures/NewBranch_GitHub4.PNG" alt="Example Image" width="650">
+</figure>
+
+5. You have now created a new branch on the remote, make sure to fetch & pull again to see it on the local repositery!
+````
+`````
+
+**3. Work in an existing branch**
+
+The next step is to *check out* our new branch in GitHub Desktop. *Checking out* means that we're changing our working branch (i.e., the one to which we will be committing our changes) from one to the other. 
 
 In GitHub Desktop, the top bar has a menu called `Current Branch`. By clicking on it you can see all the branches you created on the remote repositery. 
 
@@ -213,11 +390,11 @@ Leave your changes (stashed) on your working branch, in this case I was working
 
 3. Check that the branch is indeed checked out by looking at the branch menu at the the top left again; the current branch should say the name. 
 
-````
-`````
 ``````
 ```````
+**Now that you have created and checked out your new branch, you can start {ref}`making and committing changes <stage-commit-push>`.**
+
 ````````
 `````````
-
-Now that we've created and checked out our new branch, we can start {ref}`making and committing changes <stage-commit-push>`.
+``````````
+```````````

book/workflows/collaboration.md

@@ -11,49 +11,74 @@ We have previously introduced the notions of using Git in the online environment
 
 The steps involved are as follows:
 
- 1. **Assign task to yourself (milestones, issues)**
- 2. **Create your own version of the book by**
+ 1. **Assign a task to yourself (milestones, issues)**
+ 2. **Create your own version of the book as...**
 ```````{tab-set}
-``````{tab-item} ... user type 3
-**... by directly creating your own version (branching) or selecting existing version:**
+``````{tab-item} ... user type 3...
+
+**... by creating your own version of the book (branching) or selecting existing version:**
+
  - branching
 ``````
 ``````{tab-item} ... user type 4 and 5
-**... for ...**
+
 `````{tab-set}
-````{tab-item} ... repository opened for first time
-**... by opening the repository locally (cloning) and creating your own version (branching) or select existing version (checkout branch):**
+````{tab-item} Open repository for first time...
+
+**... by <br>
+(a) opening the repository locally (cloning) and <br>
+(b) creating your own version (branching) or selecting existing version (checkout branch):**
+
  - cloning
  - branching / checkout branch
 ````
-````{tab-item} ... previously opened repository
-**... by updating your repository (pulling) and creating your own version (branching) or select existing version (checkout branch):**
+````{tab-item} Work in previously opened repository...
+
+**... by <br>
+(a) updating your repository (pulling) and <br>
+(b) creating your own version (branching) or select existing version (checkout branch):**
+
  - pulling
  - branching / checkout branch
 ````
-
 `````
 ``````
 ```````
- 3. **Edit the book by ...**
+ 3. **Edit the book as ...**
+
 ```````{tab-set}
-``````{tab-item} ... user type 3
+``````{tab-item} ... user type... 3
+
 **... by directly adding changes on a single file to Git-timeline (committing):**
- - adding or making changes to single file
+
+ - adding file or making changes to single file
  - committing
 ``````
-``````{tab-item} ... user type 4
-... on ...
+``````{tab-item} ... user type 4...
+
 `````{tab-set}
-````{tab-item} ... brand new version (branch)
-**... by making changes on a single / multiple file(s), selecting changes to be added to the Git-timeline (staging), adding those to the Git-timeline (committing) and adding those changes to GitLab/GitHub (pushing):**
+````{tab-item} ... on a brand new version (branch)...
+
+**... by <br>
+(a) making changes on a single / multiple file(s), <br>
+(b) selecting changes to be added to the Git-timeline (staging), <br>
+(c) adding those to the Git-timeline (committing) and <br>
+(d) adding those changes to GitLab/GitHub (pushing):**
+
 - adding or making changes to file(s)
 - staging
 - committing
 - pushing
 ````
-````{tab-item} ... existing version (branch)
-**... by regularly obtaining updates from colleagues from GitLab/GitHub (pulling), solving potential incompatible changes (merge conflicts), making changes on a single / multiple file(s), selecting changes to be added to the Git-timeline (staging), adding those to the Git-timeline (committing) and adding those changes to GitLab/GitHub (pushing):**
+````{tab-item} ... on an existing version (branch)...
+
+**... by <br>
+(a) regularly obtaining updates from colleagues from GitLab/GitHub (pulling), <br>
+(b) solving potential incompatible changes (merge conflicts), <br>
+(c) making changes on a single / multiple file(s), <br>
+(d) selecting changes to be added to the Git-timeline (staging), <br>
+(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)
@@ -63,19 +88,34 @@ The steps involved are as follows:
 ````
 `````
 ``````
-``````{tab-item} ... user type 5
-... on ...
+``````{tab-item} ... user type 5...
 `````{tab-set}
-````{tab-item} ... brand new version (branch)
-**... by making changes on a single / multiple file(s), checking changes locally, selecting changes to be added to the Git-timeline (staging), adding those to the Git-timeline (committing) and adding those changes to GitLab/GitHub (pushing):**
+````{tab-item} ... on a brand new version (branch)...
+
+**... by <br>
+(a) making changes on a single / multiple file(s), <br>
+(b) checking changes locally, <br>
+(c) selecting changes to be added to the Git-timeline (staging), <br>
+(d) adding those to the Git-timeline (committing) and <br>
+(e) adding those changes to GitLab/GitHub (pushing):**
+
 - adding or making changes to file(s)
 - checking changes locally 
 - staging
 - committing
 - pushing
 ````
-````{tab-item} ... existing version (branch)
-**... by regularly obtaining updates from colleagues from GitLab/GitHub (pulling), solving potential incompatible changes (merge conflicts), making changes on a single / multiple file(s), checking changes locally,  selecting changes to be added to the Git-timeline (staging), adding those to the Git-timeline (committing) and adding those changes to GitLab/GitHub (pushing):**
+````{tab-item} ... on an existing version (branch)...
+
+**... by <br>
+(a) regularly obtaining updates from colleagues from GitLab/GitHub (pulling), <br>
+(b) solving potential incompatible changes (merge conflicts), <br>
+(c) making changes on a single / multiple file(s), <br>
+(d) checking changes locally,  <br>
+(e) selecting changes to be added to the Git-timeline (staging), <br>
+(f) adding those to the Git-timeline (committing) and <br>
+(g) adding those changes to GitLab/GitHub (pushing):**
+
 - pulling
 - solving merge conflicts
 - adding or making changes to file(s)
@@ -84,10 +124,9 @@ The steps involved are as follows:
 - committing
 - pushing
 ````
-
 ``````
 ```````
- 4. **Check changes online**
+ 4. **Check candles nline**
  5. **Repeat steps 3 and 4 until you're satisfied**
  6. **Reviewing (merge request), (eventually repeat steps 3 and 4) and combine (merging) your version with main draft version of book**
  7. **Publish changes to student version of the book (merge request)**

book/workflows/edit_book.md

@@ -123,7 +123,7 @@ The new file has been staged, and we've written a Commit Message.
 ```
 Now, we are ready to add the changes to the repository. This is done by *committing* the staged changes. To do this, simply press the big, blue "Commit" button in the Source Control menu. 
 
-In the bottom left corner, next to the branch name, click the "Synchronize Changes" button (the one that looks like this: 🔄, highlighted in the image below) to push the changes to GitLab.
+4. In the bottom left corner, next to the branch name, click the "Synchronize Changes" button (the one that looks like this: 🔄, highlighted in the image below) to push the changes to GitLab.
 
 ```{figure} ../images/git-push.png
 
@@ -172,7 +172,7 @@ Alternatively, you can also click on `Push origin` in the top bar.
 1. If you collaborate with colleagues on your branch, you can get the updates from your colleagues as well by pulling from GitLab/GitHub. This synchronizes the remote repositery with your local repositery on your machine. On the left side-bar click on the icon that looks like a branch. 
 
 <figure align="center">
-    <img src="figures/VSCode_Pull.PNG" alt="Example Image" width="650">
+    <img src="figures/VSCode_Pull.PNG" alt="Example Image" width="400">
 </figure>
 
 By clicking on the 🔄 button, you will pull your colleages' changes.
@@ -214,7 +214,7 @@ The new file has been staged, and we've written a Commit Message.
 ```
 Now, we are ready to add the changes to the repository. This is done by *committing* the staged changes. To do this, simply press the big, blue "Commit" button in the Source Control menu. 
 
-In the bottom left corner, next to the branch name, click the "Synchronize Changes" button (the one that looks like this: 🔄, highlighted in the image below) to push the changes to GitLab.
+6. In the bottom left corner, next to the branch name, click the "Synchronize Changes" button (the one that looks like this: 🔄, highlighted in the image below) to push the changes to GitLab.
 
 ```{figure} ../images/git-push.png
 
@@ -234,7 +234,7 @@ After committing, click the 🔄 button to push our changes to the remote reposi
     <img src="figures/Conflicts1.PNG" alt="Example Image" width="650">
 </figure>
 
-In this case there are two conflicted files. GitHub Desktop is suggesting to resolve the changes in VS Code. Click on `Open in Visual Studio Code`. 
+In this case there are two conflicted files. GitHub Desktop is suggesting to resolve the changes in VS Code (in that case have a look at the section treating VS Code). By clicking on the small downwards arrow you can also solve the conflict directly in GitHub Desktop by choosing the branch of the file you want to keep.
 
 <figure align="center">
     <img src="figures/Conflicts2.PNG" alt="Example Image" width="650">
@@ -276,7 +276,7 @@ Alternatively, you can also click on `Push origin` in the top bar.
 ```````
 ````````
 
-````````{tab-item} ... User type 5 ...
+````````{tab-item} ... user type 5 ...
 
 ```````{tab-set}
 ``````{tab-item} ... for brand new version (branch)
@@ -319,7 +319,7 @@ Sometimes there are problems building the book. It could be that the building re
 
 `pip install -r requirements.txt --upgrade`
 
-```jup
+```
 3. If you are satisfied with your changes, you can select the files ready to be added to Git-timeline (staging) 
 
 For demonstration purposes, we have created a new Markdown file called `new-chapter.md`, which we want to add to the book. Since this is a new file, Git has no knowledge about its existence yet. I.e., the file is *untracked*. To add new files to our repository, we need to *stage* and *commit* them. To do this, open the Source Control menu in the left side bar. Our new file should appear in this menu:
@@ -341,39 +341,65 @@ The new file has been staged, and we've written a Commit Message.
 ```
 Now, we are ready to add the changes to the repository. This is done by *committing* the staged changes. To do this, simply press the big, blue "Commit" button in the Source Control menu. 
 
-In the bottom left corner, next to the branch name, click the "Synchronize Changes" button (the one that looks like this: 🔄, highlighted in the image below) to push the changes to GitLab.
+5. Adding changes to GitLab/GitHub (pushing)
+
+In the bottom left corner, next to the branch name, click the "Synchronize Changes" button (the one that looks like this: 🔄, highlighted in the image below) to push the changes to GitLab/GitHub.
 
 ```{figure} ../images/git-push.png
 
 After committing, click the 🔄 button to push our changes to the remote repository.
 
-```{Error}
+```{Note}
 
-5.  startup python server...
+Missing from this chapter: startup python server.
 
+You can read more about it [here](/book/installation-and-setup/jupyter-book-setup.md)
+```
 ````
 
 ````{tab-item} ... GitHub Desktop
 
-1. Obtain updates from colleagues from GitLab/GitHub (pulling). This synchronizes the remote repositery with your local repositery on your machine. Click on `Fetch` in the top bar. Then on the same place, click on 'Pull'. 
+1.. Make some changes to a file in for example VS Code and save them.
 
-<figure align="center">
-    <img src="figures/Fetch.PNG" alt="Example Image" width="650">
-</figure>
+2. Once all the changes are made, it can be useful to check the changes locally on your device in order to see how it will look on the website. If all the required environments and packages are downloaded, checking changes locally is fairly easy! 
 
-2. When multiple people work on one chapter, it is possible that conflicts will arise. This means that two users might have cheanged the same sections. GitHub Desktop will recognize this Solve potential incompatible changes (merging conflicts)
+Navigate to the terminal in VS code, located at the bottom of the window or by clicking on `Terminal` in the top bar.
+You will firstly need to actiavte the right environment. Type the following command:
 
-3. Make some changes to a file in for example VS Code and save them.
+`conda activate jupyter-book-env`
 
-4. The staging GitHub Desktop assumes you want to stage all files. These files will show up on the left side bar when you open GitHub Desktop. You can unselect some of them (unstaging them) by clicking on the *check*. 
+(or the environment in which you have installed the TeachBooks package)
+
+Then we can build the book locally. Make sure you are in the right repositery in VS code and type the folloing command:
+
+`jupyter-book build book` 
+
+Where book is the name of the folder containing all the files that make up your book. After `jupyter-book` is done running you will get the following:
+
+```{figure} ../figures/buildbook.PNG
+
+Output.
+```
+Paste the last line into your browser to see the updated changes. 
+
+```{Note} 
+
+Sometimes there are problems building the book. It could be that the building requires extensions that are not present in your environment. To prevent issues, make sure to update your environment by routinely updating your packages. You can do this by executing the following line in your environment in the command line.
+
+`pip install -r requirements.txt --upgrade`
+
+```
+3. If you are satisfied with your changes, you can select the files ready to be added to Git-timeline (staging) 
+
+The staging GitHub Desktop assumes you want to stage all files. These files will show up on the left side bar when you open GitHub Desktop. You can unselect some of them (unstaging them) by clicking on the *check*. 
 
 <figure align="center">
     <img src="figures/Stage_GitHubDekstop.PNG" alt="Example Image" width="400">
 </figure>
 
-5. Add changes to Git-timeline locally (committing). In the field that says `Summary(Required)`, write a short description of the changes you have made. This message is what is called the *Commit Message*. After we've done this, click the blue button `Commit to Repositery`.
+4. Add changes to Git-timeline locally (committing). In the field that says `Summary(Required)`, write a short description of the changes you have made. This message is what is called the *Commit Message*. After we've done this, click the blue button `Commit to Repositery`.
 
-6. Now we need to add changes to GitHub/GitLab. This is called pushing to the local repositery. After committing, the following screen will pop up. Click on `Push Origin`.
+5. Now we need to add changes to GitHub/GitLab. This is called pushing to the local repositery. After committing, the following screen will pop up. Click on `Push Origin`.
 
 <figure align="center">
     <img src="figures/Push_GitHubDesktop.PNG" alt="Example Image" width="650">
@@ -385,8 +411,12 @@ Alternatively, you can also click on `Push origin` in the top bar.
     <img src="figures/Push_GitHubDesktop2.PNG" alt="Example Image" width="650">
 </figure>
 
-Python stuff?
+```{Note}
 
+Missing from this chapter: startup python server.
+
+You can read more about it [here](/book/installation-and-setup/jupyter-book-setup.html#view-the-book-using-a-local-webserver)
+```
 ````
 `````
 ``````
@@ -404,18 +434,152 @@ Python stuff?
 `````{tab-set}
 ````{tab-item} ... Git in VS Code
 
-**Eventually solve conflicts with combining versions (merge conflicts, emerges after pulling)**
+1. If you collaborate with colleagues on your branch, you can get the updates from your colleagues as well by pulling from GitLab/GitHub. This synchronizes the remote repositery with your local repositery on your machine. On the left side-bar click on the icon that looks like a branch. 
 
-If you collaborate with colleagues on this branch, you can get the updates from your colleagues as well by pulling from GitLab/GitHub. Now your branch is up-to-date. However, this might lead into a merge conflict if you and colleagues have made incompatible changes. How to solve that?
+<figure align="center">
+    <img src="figures/VSCode_Pull.PNG" alt="Example Image" width="400">
+</figure>
 
-```{error} To be written
+By clicking on the 🔄 button, you will pull your colleages' changes.
+
+2. When multiple people work on one chapter, it is possible that conflicts will arise if you and your colleagues have made incompatible changes in the same branch. In that case, when pulling from the remote repositery, Git in VS Code will recognize conflicts and help you to solve potential incompatible changes (merging conflicts). Open the files that are marked as conflicitng. 
+
+<figure align="center">
+    <img src="figures/Conflicts2.PNG" alt="Example Image" width="600">
+</figure>
+
+The figure above shows the conflicts. If you look closely you can see that the last couple of words of the paragraph are different in the main branch than in the branch we were working in. There are a couple of options in the top bar: 
+
+- `Accept Current Change` will keep the change in your branch
+- `Accept Incoming Change` will keep the change from the main branch (the branch you are merging into your branch)
+- `Accept Both Changes` will retain both paragraphs
+
+Choose one of the options to resolve the merge conflict. You now have updated your work with work from your colleagues and resolved potential conlicts. You are now ready to continue working on the content.
+
+3. Make some further changes to a file in for example VS Code and save them.
+
+4. Once all the changes are made, it can be useful to check the changes locally on your device in order to see how it will look on the website. If all the required environments and packages are downloaded, checking changes locally is fairly easy! 
+
+Navigate to the terminal in VS code, located at the bottom of the window or by clicking on `Terminal` in the top bar.
+You will firstly need to actiavte the right environment. Type the following command:
+
+`conda activate jupyter-book-env`
+
+(or the environment in which you have installed the TeachBooks package)
+
+Then we can build the book locally. Make sure you are in the right repositery in VS code and type the folloing command:
+
+`jupyter-book build book` 
+
+Where book is the name of the folder containing all the files that make up your book. After `jupyter-book` is done running you will get the following:
+
+```{figure} ../figures/buildbook.PNG
+
+Output.
 ```
+Paste the last line into your browser to see the updated changes. 
+
+```{Note} 
+
+Sometimes there are problems building the book. It could be that the building requires extensions that are not present in your environment. To prevent issues, make sure to update your environment by routinely updating your packages. You can do this by executing the following line in your environment in the command line.
+
+`pip install -r requirements.txt --upgrade`
+
+```
+5.  Select the files ready to be added to Git-timeline (staging) 
+
+For demonstration purposes, we have created a new Markdown file called `new-chapter.md`, which we want to add to the book. Since this is a new file, Git has no knowledge about its existence yet. I.e., the file is *untracked*. To add new files to our repository, we need to *stage* and *commit* them. To do this, open the Source Control menu in the left side bar. Our new file should appear in this menu:
+
+```{figure} ../images/git-new-file.png
+
+The new file appears in the Source Control menu.
+```
+Notice that there is a green letter U placed besides the file, meaning that our file is untracked. To add a file to the *staging area*, click on the + that appears when you hover over the file. 
+
+6. Adding changes to the Git-timeline (committing)
+
+Next, in the field that says "Message", write a short description of the changes you have made. This message is what is called the *Commit Message*. After we've done this, the menu should now look something like this:
+
+```{figure} ../images/git-file-added.png
+
+The new file has been staged, and we've written a Commit Message.
+```
+Now, we are ready to add the changes to the repository. This is done by *committing* the staged changes. To do this, simply press the big, blue "Commit" button in the Source Control menu. 
+
+7. In the bottom left corner, next to the branch name, click the "Synchronize Changes" button (the one that looks like this: 🔄, highlighted in the image below) to push the changes to GitLab.
+
+```{figure} ../images/git-push.png
+
+After committing, click the 🔄 button to push our changes to the remote repository.
 ````
 ````{tab-item} ... GitHub Desktop
 
-text..
-```{error} To be written
+1. If you collaborate with colleagues on your branch, you can get the updates from your colleagues as well by pulling from GitLab/GitHub. This synchronizes the remote repositery with your local repositery on your machine. Click on `Fetch` in the top bar. Then on the same place, click on 'Pull'. 
+
+<figure align="center">
+    <img src="figures/Fetch.PNG" alt="Example Image" width="650">
+</figure>
+
+2. When multiple people work on one chapter, it is possible that conflicts will arise if you and your colleagues have made incompatible changes in the same branch. In that case, when pulling from the remote repositery, GitHub Desktop will recognize conflicts and help you to solve potential incompatible changes (merging conflicts). 
+
+<figure align="center">
+    <img src="figures/Merge_Conflict_GitHubDesktop2.PNG" alt="Example Image" width="400">
+</figure>
+
+In this case there are two conflicted files. GitHub Desktop is suggesting to resolve the changes in VS Code (in that case have a look at the section treating VS Code). By clicking on the small downwards arrow you can also solve the conflict directly in GitHub Desktop by choosing the branch of the file you want to keep.
+
+Choose one of the options to resolve the merge conflict. You now have updated your work with work from your colleagues and resolved potential conlicts. You are now ready to continue working on the content.
+
+3. Make some further changes to a file in for example VS Code and save them.
+
+4. Once all the changes are made, it can be useful to check the changes locally on your device in order to see how it will look on the website. If all the required environments and packages are downloaded, checking changes locally is fairly easy! 
+
+Navigate to the terminal in VS code, located at the bottom of the window or by clicking on `Terminal` in the top bar.
+You will firstly need to actiavte the right environment. Type the following command:
+
+`conda activate jupyter-book-env`
+
+(or the environment in which you have installed the TeachBooks package)
+
+Then we can build the book locally. Make sure you are in the right repositery in VS code and type the folloing command:
+
+`jupyter-book build book` 
+
+Where book is the name of the folder containing all the files that make up your book. After `jupyter-book` is done running you will get the following:
+
+```{figure} ../figures/buildbook.PNG
+
+Output.
 ```
+Paste the last line into your browser to see the updated changes. 
+
+```{Note} 
+
+Sometimes there are problems building the book. It could be that the building requires extensions that are not present in your environment. To prevent issues, make sure to update your environment by routinely updating your packages. You can do this by executing the following line in your environment in the command line.
+
+`pip install -r requirements.txt --upgrade`
+
+```
+
+5. The staging GitHub Desktop assumes you want to stage all files. These files will show up on the left side bar when you open GitHub Desktop. You can unselect some of them (unstaging them) by clicking on the *check*. 
+
+<figure align="center">
+    <img src="figures/Stage_GitHubDekstop.PNG" alt="Example Image" width="400">
+</figure>
+
+6. Add changes to Git-timeline locally (committing). In the field that says `Summary(Required)`, write a short description of the changes you have made. This message is what is called the *Commit Message*. After we've done this, click the blue button `Commit to Repositery`.
+
+7. Now we need to add changes to GitHub/GitLab. This is called pushing to the local repositery. After committing, the following screen will pop up. Click on `Push Origin`.
+
+<figure align="center">
+    <img src="figures/Push_GitHubDesktop.PNG" alt="Example Image" width="650">
+</figure>
+
+Alternatively, you can also click on `Push origin` in the top bar. 
+
+<figure align="center">
+    <img src="figures/Push_GitHubDesktop2.PNG" alt="Example Image" width="650">
+</figure>   
 ````
 `````
 ``````

book/workflows/merge_request.md

@@ -30,23 +30,85 @@ Creating a new merge request to merge `chapter-2` into `main`.
 
 Example of a filled-in merge request.
 ```
+5. After clicking `create merge request` you should land on the following page. Here, you can track the merge request. Right after your request, GitLab will do some checks to see if you've tried to merge conflicting files. As you can see in the figure below the merge is blocked due to the conflicts. Click on 'Resolve conflicts`. 
 
-5. On the page of our merge request ({numref}`gitlab-finished-merge-request`), we're greeted with some more information. On top, you can read the description we just provided when creating the merge request. We can also see an "Approve" button, which you may or may not see, depending on your repository rights. Next, we can see a green checkmark, with a "Merge" button. This is good news: our changes do not conflict with existing files on the `main` branch, and we can merge our changes directly by clicking the button (if applicable: only after somebody else approved the request). If this isn't the case, you'll see a red cross instead of the green checkmark, and GitLab will tell that you've run into a *merge conflict*. You'll need to figure out which file(s) are causing this, and fix it. You can read more on this in the {ref}`section on merge conflicts <merge-conflicts>`.
+```{figure} ../figures/Merge_Request_GitLab.PNG
+:name: gitlab-merge-request-conflict
 
+Example of a blocked merge.
+```
 
-```{figure} ../images/gitlab-finished-merge-request.png
+Clicking on 'Resolve conflicts`, will open the conflicted files in the text editor. There you can manually edit the files to the version you would like to retain. By clicking on `use ours` or `use theirs` you can select which version you would like to keep.
+
+```{figure} ../figures/Solve_Conflict.PNG
+:name: gitlab-conflict
+
+Solving the conflict.
+```
+Once you are done, click on `Commit to source branch`. Do this for all conflicted files. Note that if your branches do not have conflicting changes you can merge directly and skip this step. In that case you can skip ahead to the next step.
+
+In case you have cloned the repositery you can also resolve the conflicts locally using VS Code for example. You can read more about for [GitHub Dekstop](edit_book.md#... GitHub Desktop) or [VS Code](edit_book.md#... VS Code)
+
+6. On the page of our merge request ({numref}`gitlab-finished-merge-request`), we're greeted with some more information. On top, you can read the description we just provided when creating the merge request. We can also see an "Approve" button, which you may or may not see, depending on your repository rights. Next, we can see a green checkmark, with a "Merge" button. This is good news: our changes do not conflict with existing files on the `main` branch, and we can merge our changes directly by clicking the button (if applicable: only after somebody else approved the request). 
+
+```{figure} ../../images/gitlab-finished-merge-request.png
 :name: gitlab-finished-merge-request
 
 The finished merge request.
 ```
-
 ````
 
 ````{tab-item} In GitHub
 
-```{error} To be written
-```
+1. Make sure that you've committed all your new sections and changes, and that they're pushed to the remote repository.
 
+2. In GitHub, navigate to the repositery you want to work in. In the top bar click `Pull Requests`. Then, in the new window click on `New Pull Request`. 
+
+<figure align="center">
+    <img src="figures/Pull_Request.PNG" alt="Example Image" width="650">
+</figure>
+
+3. You can now choose a base branch and a compare branch. 
+
+- Base Branch: The base branch is the branch into which you want to merge your changes.
+- Compare Branch: The compare branch, also known as the "head" branch, is the branch that contains the changes you want to merge into the base branch.
+
+<figure align="center">
+    <img src="figures/Pull_Request2.PNG" alt="Example Image" width="650">
+</figure>
+
+In the figure, you can see that we want to merge our changes from the branch `merge_conflict` *into* `main`, `merge_conflict` is the compare branch and `main` is the base branch. Note that in the figure it says that the branches cannot be automatically merged. The reason for this is that there are conflicts in the two branches, which you can see when scrollong down. 
+
+You can still create the pull request but you will have to manage the conflicts. Once you've selected the correct branches, click `View Pull Request`.
+
+4. As previously mentioned, before merging the two branches we have to resolve the conflicts. Click on 'Resolve conflicts`. Note that if your branches do not have conflicting changes you can merge directly and skip this step.
+
+<figure align="center">
+    <img src="figures/Pull_Request3.PNG" alt="Example Image" width="650">
+</figure>
+
+Clicking on 'Resolve conflicts`, will open the conflicted files in the text editor. There you can manually edit the files to the version you would like to retain. 
+
+<figure align="center">
+    <img src="figures/Pull_Request4.PNG" alt="Example Image" width="650">
+</figure>
+
+Once you are done, click on `mark as resolved` in the top right of the window. Do this for all conflicted files. 
+In case you have cloned the repositery you can also resolve the conflicts locally using VS Code for example. You can read more about it [here](edit_book.md#... GitHub Desktop)
+
+5. Commit the changes by clicking on `Commit merge`. 
+
+<figure align="center">
+    <img src="figures/Pull_Request5.PNG" alt="Example Image" width="650">
+</figure>
+
+6. You can now complete the pull request by clicking `merge pull request`.
+
+<figure align="center">
+    <img src="figures/Pull_Request6.PNG" alt="Example Image" width="650">
+</figure>
+````
+````{tab-item} Locally with GitHub Desktop for GitHub repositories
+hi
 ````
-
 `````

book/workflows/milestones_issues.md

@@ -31,15 +31,38 @@ This will lead you to this window where you can specify all attributes we mentio
 
 The issues in GitHub can be found in your repositery in the top bar.
 
-<img src="figures/Issue_GitHub.png" alt="New Issue" width="1000" style="display:block; margin-left:auto; margin-right:auto;"> <br>
+
+<figure align="center">
+    <img src="figures/Issue_GitHub.PNG" alt="Example Image" width="650">
+</figure>
 
 Clicking on `Issues` will open up the page with all the issues on this repositery.
 
-<img src="figures/New_Issue_GitHub.png" alt="New Issue" width="1000" style="display:block; margin-left:auto; margin-right:auto;"> <br>
+<figure align="center">
+    <img src="figures/New_Issue_GitHub.PNG" alt="Example Image" width="650">
+</figure>
 
 Finally, by clicking the green `New Issue` button you can create a new issue and specify all the attributes we mentioned before!
 
-<img src="figures/New_Issue_GitHub2.png" alt="New Issue" width="1000" style="display:block; margin-left:auto; margin-right:auto;"> <br>
+<figure align="center">
+    <img src="figures/New_Issue_GitHub2.PNG" alt="Example Image" width="650">
+</figure>
+
+```{Note}
+
+The follwing steps explain how to create a branch from a new issue. By doing this you can create most of the steps described in the section called [branching](branches.md). However, if you are unfamiliar with the term make sure to still read the section to understand the function.
+```
+After creating the issue, the description of the issue will automatically open. On the bottom left there is an option `create a branch` (in yellow) from this issue. This will create a new branch in the repositery which you can use to solve the issue. 
+
+<figure align="center">
+    <img src="figures/New_Issue_GitHub3.PNG" alt="Example Image" width="650">
+</figure>
+
+Clicking on `create a branch` will open the following window in which you can specify the name and the repositery.
+
+<figure align="center">
+    <img src="figures/New_Issue_GitHub4.PNG" alt="Example Image" width="350">
+</figure>
 ````
 `````