admin2/manual_teachbooks
1
0
Fork 0
mirror of https://github.com/TeachBooks/manual.git synced 2026-11-13 06:45:52 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions

Merge branch 'fixing_errors' into 'main'

Browse source 
Fixing errors

See merge request interactivetextbooks-citg/jupyter-book-manual!115
This commit is contained in:
Julie Kirsch 2024-11-05 19:40:33 +01:00
commit 2b50697517
5 changed files with 119 additions and 141 deletions
Download patch file Download diff file Expand all files Collapse all files

179
book/workflows/branches.md
View file

@ -21,66 +21,15 @@ The act of making a new branch from an existing one is called *branching*. Usual
``````{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.
```{include} new_branch_gitlab.md
```
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`. 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
How to branch is demonstrated in the figure below, all steps are elaborated on in the following step-by-step tutorial.
```{figure} figures/branching-github-ezgif.com-optimize.gif
---
name: branching_demo
---
Demonstration, video available [here](https://youtu.be/3ceMSLQpD70)
```{include} new_branch_github.md
```
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) but you can also work in any other branch if you are helping out a colleague with their chapter for example (existing version).
<figure align="center">
<img src="figures/NewBranch_GitHub4.PNG" alt="Example Image" width="650">
</figure>
``````
```````
``````````
@ -103,11 +52,13 @@ If your repository is already cloned on your computer, you are almost ready to s
``````{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".
1. Navigate to the repository of your book. Click on the blue button that says "Clone", and copy the link under "Clone with SSH".
```{figure} ../images/gitlab-clone.png
:name: gitlab-clone
---
name: gitlab-clone
---
The cloning menu.
```
``````
@ -116,36 +67,50 @@ The cloning menu.
1. Open the repository that you would like to clone. In the top bar on the right, you will a green button called `<> Code`.
<figure align="center">
<img src="figures/NewBranch_GitHub.PNG" alt="Example Image" width="650">
</figure>
```{figure} figures/NewBranch_GitHub.PNG
---
name: NewBranch_GitHub1
---
Overview
```
2. Clicking on the button will display the following screen. Make sure the option `SSH` is selected and copy the link.
<figure align="center">
<img src="figures/Clone_GitHub.PNG" alt="Example Image" width="400">
</figure>
``````
```{figure} figures/Clone_GitHub.PNG
---
name: Clone_GitHub
---
Clone using SSH
```
``````{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`.
<figure align="center">
<img src="figures/NewBranch_GitHub.PNG" alt="Example Image" width="650">
</figure>
```{figure} figures/NewBranch_GitHub.PNG
---
name: NewBranch_GitHub2
---
Overview
```
2. Clicking on the button will display the following screen. Click on `Open with GitHub Desktop`.
<figure align="center">
<img src="figures/Clone_GitHub.PNG" alt="Example Image" width="400">
</figure>
```{figure} figures/Clone_GitHub.PNG
---
name: Clone_GitHub1
---
Clone using SSH
```
3. The Browser should then automatically open GitHub Desktop. Customize the path to the location where you would like to save to files locally. Finally, click on `Clone`.
<figure align="center">
<img src="figures/CloneRepo_TroughGithubdesk.PNG" alt="Example Image" width="400">
</figure>
```{figure} figures/CloneRepo_TroughGithubdesk.PNG
---
name: CloneRepo_TroughGithubdesk.PNG
---
Clone through GitHub Desktop
```
You have now directly cloned the repository, so you can skip the next step!
``````
@ -154,9 +119,10 @@ You have now directly cloned the repository, so you can skip the next step!
**(b) ... and opening (cloning) the local repository with ...**
```````{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".
1. Open a new VS Code window. You should be greeted with a welcome page. On this page, click "Clone Git Repository". Alternatively, open the Source Control menu from the left side bar, and click on "Clone Repository".
```{figure} ../images/vscode-welcome.png
:name: vscode-welcome
@ -197,71 +163,20 @@ Have a look at the other section!**
**(a) by creating my own version (branching) or select an existing version (checkout branch) ...**
Although it is possible to create new branches in VS Code directly, creating new branches on the remote repository (on GitLab or GitHub) is better for collaborating because the new branch becomes immediately visible to everyone working in the repository as opposed to becoming visible after being pushed to the remote repository.
Although it is possible to create new branches in VS Code or GitHub Desktop directly, creating new branches on the remote repository (on GitLab or GitHub) is better for collaborating because the new branch becomes immediately visible to everyone working in the repository as opposed to becoming visible after being pushed/published to the remote repository.
`````{tab-set}
````{tab-item} ... in 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.
```{include} new_branch_gitlab.md
```
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.
```
````
````{tab-item} ... GitHub
How to branch is demonstrated in the figure below, followed by a step-by-step tutorial.
```{figure} figures/branching-github-ezgif.com-optimize.gif
---
name: branching_demo
---
Demonstration, video available [here](https://youtu.be/3ceMSLQpD70)
```{include} new_branch_github.md
```
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>
````
`````
@ -279,14 +194,16 @@ In VS Code, open the branch menu from the bottom left (see {numref}`git-branch-m
Check out the branch by simply clicking on it. Check that the branch is indeed checked out by looking at the branch menu button in the bottom left again; it should now say the name of your branch instead of `main` (in our case `chapter-2`).
```{figure} ../images/git-branch-menu-main.png
:name: git-branch-menu-main
---
name: git-branch-menu-main
---
Location of the branch menu.
```
```{figure} ../images/git-branch-selection-menu.png
:name: git-branch-selection-menu
---
name: git-branch-selection-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.
```

BIN
book/workflows/figures/Merge_Request_GitLab.PNG Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 49 KiB

20
book/workflows/merge_request.md
View file

@ -1,4 +1,4 @@
# Reviewing and combine versions (merge / pull request, merging)
# Reviewing and combine versions (merge/pull request, merging)
Merging a branch into the main branch is also good moment to let a team-member review the content. By assigning a colleague to review your branch you can check the quality of your new content.
@ -18,7 +18,7 @@ We're finished with our chapter, and now it's time to include all of our commits
3. You can now choose a source branch and a target branch. Since we want to merge our changes from `chapter-2` *into* `main`, `chapter-2` is the source branch and `main` is the target branch ({numref}`gitlab-merge-request`) . Once you've selected the correct branches, click "Compare branches and continue".
```{figure} ../images/gitlab-merge-request.png
:name: gitlab-merge-request
name: gitlab-merge-request
Creating a new merge request to merge `chapter-2` into `main`.
```
@ -26,22 +26,22 @@ Creating a new merge request to merge `chapter-2` into `main`.
4. On the next page, you can give your merge request a name, and provide a description of your changes ({numref}`gitlab-merge-request-description`). If somebody has to review your changes, you can add them in the "Reviewer menu". They will then be notified via email that they need to review your work. Finally, watch out for the option "Delete source branch when merge request is accepted". If you want to keep working on the same branch, even after your previous work has been merged, make sure you untick the box! Once everything is filled in, click "Create merge request".
```{figure} ../images/gitlab-merge-request-description.png
:name: gitlab-merge-request-description
name: gitlab-merge-request-description
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`.
```{figure} ../figures/Merge_Request_GitLab.PNG
:name: gitlab-merge-request-conflict
```{figure} figures/Merge_Request_GitLab.PNG
name: gitlab-merge-request-conflict
Example of a blocked merge.
```
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.
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. Alternatively, 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
```{figure} figures/Solve_Conflict.PNG
name: gitlab-conflict
Solving the conflict.
```
@ -51,8 +51,8 @@ In case you have cloned the repositery you can also resolve the conflicts locall
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
```{figure} ../images/gitlab-finished-merge-request.png
name: gitlab-finished-merge-request
The finished merge request.
```

39
book/workflows/new_branch_github.md Normal file
View file

@ -0,0 +1,39 @@
How to branch is demonstrated in the figure below, all steps are elaborated on in the following step-by-step tutorial.
```{figure} figures/branching-github-ezgif.com-optimize.gif
---
name: branching_demo
---
Demonstration, video available [here](https://youtu.be/3ceMSLQpD70)
```
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
Overview
```
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
Overview Branches
```
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
---
width: 60%
---
New Branch
```
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).
```{figure} figures/NewBranch_GitHub4.PNG
Select New Branch
```

22
book/workflows/new_branch_gitlab.md Normal file
View file

@ -0,0 +1,22 @@
1. Navigate to the repository of your project. Under the project description, you should see a menu button with a "+" in it. Click this button, then click on "New branch".
```{figure} ../images/gitlab-branch.png
Click the highlighted button to make a new branch.
```
2. A new page opens, 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
---
width: 80%
---
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, it should now say `chapter-2` instead of `main`.
```{figure} ../images/gitlab-new-branch-repo.png
The circled menu is the branch selection menu.
```