admin2/manual_teachbooks
1
0
Fork 0
mirror of https://github.com/TeachBooks/manual.git synced 2026-11-12 22:35:51 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions

Swap GitHub/GitLab

Browse source
This commit is contained in:
Tom van Woudenberg 2025-02-22 10:05:59 +01:00
parent ad6a2a6134
commit a02491e770
5 changed files with 170 additions and 161 deletions
Download patch file Download diff file Expand all files Collapse all files

54
book/workflows/branches.md
View file

@ -19,17 +19,17 @@ The act of making a new branch from an existing one is called *branching*. Usual
```````{tab-set}
``````{tab-item} ... GitLab
```{include} new_branch_gitlab.md
```
``````
``````{tab-item} ... GitHub
```{include} new_branch_github.md
```
``````
``````{tab-item} ... GitLab
```{include} new_branch_gitlab.md
```
``````
```````
``````````
@ -50,19 +50,6 @@ If your repository is already cloned on your computer, you are almost ready to s
```````{tab-set}
``````{tab-item} ... GitLab
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
---
The cloning menu.
```
``````
``````{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`.
@ -115,12 +102,28 @@ Clone through GitHub Desktop
You have now directly cloned the repository, so you can skip the next step!
``````
``````{tab-item} ... GitLab
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
---
The cloning menu.
```
``````
```````
**(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. On this page, click "Clone Git Repository". Alternatively, open the Source Control menu from the left side bar, and click on "Clone Repository".
@ -167,17 +170,18 @@ Have a look at the other section!**
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
```{include} new_branch_gitlab.md
```
````
````{tab-item} ... GitHub
```{include} new_branch_github.md
```
````
````{tab-item} ... in GitLab
```{include} new_branch_gitlab.md
```
````
`````

18
book/workflows/check_changes_online.md
View file

@ -10,14 +10,6 @@ However both users would certainly benefit from checking whether their changes l
Now that you've pushed your changes online, it's time to check the change in the online build book to make sure that your changes are processed correctly. For this step it is assumed you're using TeachBook's GitHub actions or TeachBook's GitLab pipeline.
`````{tab-set}
````{tab-item} In GitLab
At the moment this is not possible.
However, what you can do is 'mirror' your GitLab repository to GitHub. This will copy your content automatically (but maximum once every 5 minutes) to GitHub. This allows you to use the TeachBook's GitHub actions.
Instructions on how to set up mirroring are provided here: https://docs.gitlab.com/ee/user/project/repository/mirror/push.html#set-up-a-push-mirror-from-gitlab-to-github
````
````{tab-item} In GitHub
Once GitHub Pages is enabled and your book is published, you can view it by visiting the GitHub Pages URL for your repository. A summary can be seen under the <svg aria-hidden="true" height="16" viewBox="0 0 16 16" version="1.1" width="16" data-view-component="true" class="octicon octicon-play UnderlineNav-octicon d-none d-sm-inline"> <path d="M8 0a8 8 0 1 1 0 16A8 8 0 0 1 8 0ZM1.5 8a6.5 6.5 0 1 0 13 0 6.5 6.5 0 0 0-13 0Zm4.879-2.773 4.264 2.559a.25.25 0 0 1 0 .428l-4.264 2.559A.25.25 0 0 1 6 10.559V5.442a.25.25 0 0 1 .379-.215Z"></path></svg>`Actions`- `All workflows` - `call-deploy-book` in GitHub. It shows you a descriptive summary.
@ -26,6 +18,16 @@ The summary also provides build error messages, which you might fix in a new com
If this is not activated yet, you can do so as describe [here](../external/deploy-book-workflow/README). Here you can also find more information.
````
````{tab-item} In GitLab
At the moment this is not possible.
However, what you can do is 'mirror' your GitLab repository to GitHub. This will copy your content automatically (but maximum once every 5 minutes) to GitHub. This allows you to use the TeachBook's GitHub actions.
Instructions on how to set up mirroring are provided here: https://docs.gitlab.com/ee/user/project/repository/mirror/push.html#set-up-a-push-mirror-from-gitlab-to-github
````
`````
You can keep on [editing](edit_book) and checking your changes until you're satisfied and ready for a review by a colleague.

134
book/workflows/edit_book.md
View file

@ -9,59 +9,6 @@ Suppose we are writing a new chapter, or are updating an existing chapter for ou
**... by directly adding changes on a single file to the Git-timeline (committing) in ...**
```````{tab-set}
``````{tab-item} ... GitLab
In GitLab, you can directly make changes in the files on the remote repository. You can make changes to the files already in the repository using the text editor but you can also upload new files!
1. Navigate to the repository you want to work in and make sure you're in the correct branch.
2. Create a new file by clicking on the plus button in the top bar. You can either create an entirely new file by clicking `New File` or if you already have created a file you can upload it by clicking `Upload File`.
```{figure} figures/User3_NewFile.PNG
---
width: 60%
align: center
---
Create new file
```
3. In the new window, you can start typing your content. Give your file a name and make sure to use the markdown extension: `Chapter1.md`. Once you are done, commit the new file to the repository by clicking the blue button `Commit changes`.
```{figure} figures/User3_NewFile2.PNG
---
align: center
---
Edit new file
```
4. In case you want to make changes to an existing file, navigate to the file in your remote repository. Then click the blue button called `Edit` and select the option `Edit single file`.
```{figure} figures/User3_EditFile.PNG
---
align: center
---
Web Editor
```
5. Make your changes in the text editor and when you are ready, commit your changes to the remote repository by clicking on the blue `Commit changes` button.
```{figure} figures/User3_NewFile2.PNG
---
align: center
---
Commit changes
```
6. In case you added a new file, you also need to include it table of contents of your book! The table of contents is specified in a file called `toc.yml` and it is already included in your repository if you used the teachbooks template. You can edit it and commit the changes in the same manner as you did with markdown `file.md` files.
```{figure} figures/User3_toc.PNG
---
align: center
---
Table of contents (TOC)
```
``````
``````{tab-item} ... GitHub...
`````{tab-set}
@ -140,6 +87,59 @@ Using this feature, you can open VS Code in your browser and edit the files in y
````
`````
``````
``````{tab-item} ... GitLab
In GitLab, you can directly make changes in the files on the remote repository. You can make changes to the files already in the repository using the text editor but you can also upload new files!
1. Navigate to the repository you want to work in and make sure you're in the correct branch.
2. Create a new file by clicking on the plus button in the top bar. You can either create an entirely new file by clicking `New File` or if you already have created a file you can upload it by clicking `Upload File`.
```{figure} figures/User3_NewFile.PNG
---
width: 60%
align: center
---
Create new file
```
3. In the new window, you can start typing your content. Give your file a name and make sure to use the markdown extension: `Chapter1.md`. Once you are done, commit the new file to the repository by clicking the blue button `Commit changes`.
```{figure} figures/User3_NewFile2.PNG
---
align: center
---
Edit new file
```
4. In case you want to make changes to an existing file, navigate to the file in your remote repository. Then click the blue button called `Edit` and select the option `Edit single file`.
```{figure} figures/User3_EditFile.PNG
---
align: center
---
Web Editor
```
5. Make your changes in the text editor and when you are ready, commit your changes to the remote repository by clicking on the blue `Commit changes` button.
```{figure} figures/User3_NewFile2.PNG
---
align: center
---
Commit changes
```
6. In case you added a new file, you also need to include it table of contents of your book! The table of contents is specified in a file called `toc.yml` and it is already included in your repository if you used the teachbooks template. You can edit it and commit the changes in the same manner as you did with markdown `file.md` files.
```{figure} figures/User3_toc.PNG
---
align: center
---
Table of contents (TOC)
```
``````
```````
````````
@ -152,7 +152,7 @@ Using this feature, you can open VS Code in your browser and edit the files in y
**... by (a) making changes on a single or multiple file(s) <br>
(b) selecting changes to be added to the Git-timeline (staging) <br>
(c) adding changes to the Git-timeline (committing) and <br>
(d) adding changes to GitLab/GitHub (pushing) with ...**
(d) adding changes to GitHub/GitLab (pushing) with ...**
`````{tab-set}
````{tab-item} ... Git in VS Code
@ -185,19 +185,19 @@ Demonstration, video available [here](https://youtu.be/bThimdDRXTc)
``````{tab-item} ... for an existing version (branch)...
**... by (a) regularly obtaining updates from colleagues from GitLab/GitHub (pulling), <br>
**... by (a) regularly obtaining updates from colleagues from GitHub/GitLab (pulling), <br>
(b) solving potential incompatible changes (merging 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 <br>
(f) adding changes to GitLab/GitHub (pushing) with ...**
(f) adding changes to GitHub/GitLab (pushing) with ...**
`````{tab-set}
````{tab-item} ... Git in VS Code
**Regularly obtain updates from colleagues from GitLab/GitHub (pulling)**
**Regularly obtain updates from colleagues from GitHub/GitLab (pulling)**
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 repository with your local repository on your machine. On the left side-bar click on the icon that looks like a branch.
If you collaborate with colleagues on your branch, you can get the updates from your colleagues as well by pulling from GitHub/GitLab. This synchronizes the remote repository with your local repository 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="400">
@ -229,9 +229,9 @@ Choose one of the options to resolve the merge conflict. You now have updated yo
````
````{tab-item} ... GitHub Desktop
**Regularly obtain updates from colleagues from GitLab/GitHub (pulling)**
**Regularly obtain updates from colleagues from GitHub/GitLab (pulling)**
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 repository with your local repository on your machine. Click on `Fetch` in the top bar. Then on the same place, click on 'Pull'.
If you collaborate with colleagues on your branch, you can get the updates from your colleagues as well by pulling from GitHub/GitLab. This synchronizes the remote repository with your local repository 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">
@ -287,7 +287,7 @@ Using this feature, you can open VS Code in your browser and edit the files in y
(b) checking changes locally <br>
(c) selecting changes to be added to the Git-timeline (staging) <br>
(d) adding changes to the Git-timeline (committing) and <br>
(e) adding changes to GitLab/GitHub (pushing) with ...**
(e) adding changes to GitHub/GitLab (pushing) with ...**
`````{tab-set}
````{tab-item} ... Git in VS Code
@ -326,20 +326,20 @@ Demonstration, video available [here](https://youtu.be/2ttjBevkEP8)
``````{tab-item} ... for an existing version (branch)
**... by (a) regularly obtaining updates from colleagues from GitLab/GitHub (pulling), <br>
**... by (a) regularly obtaining updates from colleagues from GitHub/GitLab (pulling), <br>
(b) solving potential incompatible changes (merging 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 changes to GitLab/GitHub (pushing) with ...**
(g) adding changes to GitHub/GitLab (pushing) with ...**
`````{tab-set}
````{tab-item} ... Git in VS Code
**Regularly obtain updates from colleagues from GitLab/GitHub (pulling)**
**Regularly obtain updates from colleagues from GitHub/GitLab (pulling)**
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 repository with your local repository on your machine. On the left side-bar click on the icon that looks like a branch.
If you collaborate with colleagues on your branch, you can get the updates from your colleagues as well by pulling from GitHub/GitLab. This synchronizes the remote repository with your local repository 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="400">
@ -374,9 +374,9 @@ Choose one of the options to resolve the merge conflict. You now have updated yo
````
````{tab-item} ... GitHub Desktop
**Regularly obtain updates from colleagues from GitLab/GitHub (pulling)**
**Regularly obtain updates from colleagues from GitHub/GitLab (pulling)**
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 repository with your local repository on your machine. Click on `Fetch` in the top bar. Then on the same place, click on 'Pull'.
If you collaborate with colleagues on your branch, you can get the updates from your colleagues as well by pulling from GitHub/GitLab. This synchronizes the remote repository with your local repository 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">

98
book/workflows/merge_request.md
View file

@ -9,54 +9,6 @@ There is a slight difference in terminology between GitLab and GitHub. GitLab us
We're finished with our chapter, and now it's time to include all of our commits in the `main` branch. However, it's good practice to first merge `main` into our branch, so that we can see if there are any merge conflicts. Assuming that those merge conflicts are solved before, we'll now continue this example with the following merge of our branch into `main`.
`````{tab-set}
````{tab-item} In GitLab
1. Make sure that you've committed all your new sections and changes, and that they're pushed to the remote repository.
2. Go the repository overview on GitLab. In the left menu bar, go to "Merge requests". On the Merge requests page, click "New merge request".
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. Once you've selected the correct branches, click "Compare branches and continue".
```{figure} ../images/gitlab-merge-request.png
name: gitlab-merge-request
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. 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
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
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. 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
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, 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
@ -132,4 +84,54 @@ Clicking it will pop up to the following window, where you can select which bran
3. Finally click on `create a merge commit`. Tip: The green check indicates that there are no merge conflicts however if there is a red cross you'll have to deal with those first.
````
````{tab-item} In GitLab
1. Make sure that you've committed all your new sections and changes, and that they're pushed to the remote repository.
2. Go the repository overview on GitLab. In the left menu bar, go to "Merge requests". On the Merge requests page, click "New merge request".
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. Once you've selected the correct branches, click "Compare branches and continue".
```{figure} ../images/gitlab-merge-request.png
name: gitlab-merge-request
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. 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
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
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. 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
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, 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.
```
````
`````

27
book/workflows/milestones_issues.md
View file

@ -14,19 +14,6 @@ Every team member can create issues when they think of a task that would improve
**Make and assign task to yourself (issues) in ...**
`````{tab-set}
````{tab-item} ... GitLab
The issues in GitLab can be found in your repositery in the left bar.
![issues](figures/issues_new.png)
You can create an issue by clicking on the blue `New Issue` button in the top right corner. <br>
This will lead you to this window where you can specify all attributes we mentioned before!
![new issue](figures/New_Issue_GitLab.png)
````
````{tab-item} ... GitHub
The issues in GitHub can be found in your repositery in the top bar.
@ -64,6 +51,20 @@ Clicking on `create a branch` will open the following window in which you can sp
<img src="figures/New_Issue_GitHub4.PNG" alt="Example Image" width="350">
</figure>
````
````{tab-item} ... GitLab
The issues in GitLab can be found in your repositery in the left bar.
![issues](figures/issues_new.png)
You can create an issue by clicking on the blue `New Issue` button in the top right corner. <br>
This will lead you to this window where you can specify all attributes we mentioned before!
![new issue](figures/New_Issue_GitLab.png)
````
`````
When the task is completed, the issue can be closed and you can move on to the next!