finalchanges

book/workflows/branches.md

@@ -15,7 +15,8 @@ The act of making a new branch from an existing one is called *branching*. Usual
 
 ````````{tab-item} ... user type 3 ...
 
-**... by directly creating your own version of the book (branching) or by selecting an existing version in ...**
+**... by (1) directly creating your own version of the book (branching) or <br> 
+      by (2) selecting an existing version in ...**
 
 `````{tab-set}
 
@@ -150,12 +151,16 @@ The VS Code welcome screen.
 
 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="400">
+</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'.
 
 ````
@@ -203,6 +208,7 @@ Location of the branch menu.
 
 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. 
 
+
 ```{figure} ../figures/CheckOutBranch_GitHubDesktop.PNG
 ```
 2. Check out the branch by simply clicking on it. The following window will pop up.

book/workflows/edit_book.md

@@ -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.
@@ -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:
@@ -349,8 +349,8 @@ After committing, click the 🔄 button to push our changes to the remote reposi
 
 ```{Error}
 
-5.  startup python server...
-
+Missing from this chapter: startup python server.
+```
 ````
 
 ````{tab-item} ... GitHub Desktop
@@ -385,7 +385,10 @@ 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?
+```{Error}
+
+Missing from this chapter: startup python server.
+```
 
 ````
 `````
@@ -404,18 +407,162 @@ 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="650">
+</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/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`. 
+
+<figure align="center">
+    <img src="figures/Conflicts2.PNG" alt="Example Image" width="650">
+</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. 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

@@ -39,14 +39,55 @@ Example of a filled-in 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. 
+
+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>
 ````
-
 `````

book/workflows/milestones_issues.md

@@ -31,15 +31,15 @@ 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>
+<img src="figures/Issue_GitHub.PNG" alt="New Issue" width="1000" style="display:block; margin-left:auto; margin-right:auto;"> <br>
 
 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>
+<img src="figures/New_Issue_GitHub.PNG" alt="New Issue" width="1000" style="display:block; margin-left:auto; margin-right:auto;"> <br>
 
 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>
+<img src="figures/New_Issue_GitHub2.PNG" alt="New Issue" width="1000" style="display:block; margin-left:auto; margin-right:auto;"> <br>
 ````
 `````