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

Merge branch 'main' into publish

Browse source
This commit is contained in:
Tom van Woudenberg 2024-04-11 16:57:04 +02:00
commit f73e234b07
6 changed files with 199 additions and 138 deletions
Download patch file Download diff file Expand all files Collapse all files

1
book/_toc.yml
View file

@ -17,7 +17,6 @@ parts:
- file: workflows/collaboration
sections:
- file: workflows/milestones_issues
- file: workflows/repositories
- file: workflows/branches
- file: workflows/edit_book
- file: workflows/check_changes_online

87
book/workflows/branches.md
View file

@ -9,12 +9,13 @@ This systematic workflow guarantees that editing the book goes smoothly.
The act of making a new branch from an existing one is called *branching*. Usually, you want to branch from the `main` branch, but you can of course also choose to branch from another branch. The branch from which you create a new branch is called the *source* branch.
```````{tab-set}
``````{tab-item} User type 3
`````````{tab-set}
````````{tab-item} User type 3
**Directly create your own version (branching) or select existing version**
`````{tab-set}
````{tab-item} In GitLab
1. On GitLab, 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
@ -31,26 +32,88 @@ 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`.
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.
```{figure} ../images/gitlab-new-branch-repo.png
:name: new-branch-repo
The circled menu is the branch selection menu.
```
````
````{tab-item} In GitHub
```{error} To be written
```
````
`````
````````
````````{tab-item} User type 4 and 5
```````{tab-set}
``````{tab-item} First time opening (cloning) repository
**Find source link online repository**
`````{tab-set}
````{tab-item} From GitLab
1. On GitLab, go 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".
```{figure} ../images/gitlab-clone.png
:name: gitlab-clone
The cloning menu.
```
````
````{tab-item} From GitHub
```{error} To be written
```
````
````{tab-item} From GitHub using GitHub Desktop
```{error} To be written
```
````
`````
**Open repository locally (cloning)**
`````{tab-set}
````{tab-item} With Git in VS Code
2. 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".
```{figure} ../images/vscode-welcome.png
:name: vscode-welcome
The VS Code welcome screen.
```
3. 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".
4. You now have a local copy of the repository.
````
````{tab-item} With GitHub Desktop
```{error} To be written
```
````
`````
``````
``````{tab-item} User type 4 and 5
``````{tab-item} Using previously opened (cloned) repository
### Obtain newest version from online repository
**Obtain newest version from online repository (pulling)**
If you're working on your local version of the repository, you've to make sure you're working on the most up-to-date version of your branch, pull changes from the remote repository on GitHub / GitLab into your local folder.
If you're working on your local version of the repository, you've to make sure you're working on the most up-to-date version of your branch. you can do so by `pull` changes from the remote repository on GitHub / GitLab into your local folder.
`````{tab-set}
````{tab-item} With Git in VS Code
@ -65,8 +128,10 @@ If you're working on your local version of the repository, you've to make sure y
````
`````
``````
### Create your own version
```````
**Create your own version (branching)**
`````{tab-set}
````{tab-item} With Git in VS Code
@ -84,7 +149,7 @@ Location of the branch menu.
```{figure} ../images/git-branch-selection-menu.png
:name: git-branch-selection-menu
The branch selection menu, where our new branch has shown up.
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} With GitHub Desktop
@ -92,7 +157,7 @@ The branch selection menu, where our new branch has shown up.
```
````
`````
``````
```````
````````
`````````
Now that we've created and checked out our new branch, we can start {ref}`making and committing changes <stage-commit-push>`.

83
book/workflows/collaboration.md
View file

@ -11,31 +11,68 @@ We have previously introduced the notions of using Git in the online environment
The steps involved are as follows:
1. Assign task to yourself
2. Open the files of the repository online or locally
3. Create your own version of the book
4. Edit the book by:
2. Create your own version (branching) of the book by:
```````{tab-set}
``````{tab-item} User type 3
- directly create your own version (branching) or select existing version
``````
``````{tab-item} User type 4 and 5
`````{tab-set}
````{tab-item} User type 3
````{tab-item} First time opening (cloning) repository
- Find source link online repository
- Open repository locally (cloning)
- Create your own version (branching) or select existing version (checkout branch)
````
````{tab-item} Using previously opened (cloned) repository
- Obtain newest version from online repository (pulling)
- Create your own version (branching) or select existing version (checkout branch)
`````
``````
```````
3. Edit the book by:
```````{tab-set}
``````{tab-item} User type 3
- Add or make changes to a file
- Share changes with others in Git-timeline
- Add changes to Git-timeline (committing)
``````
``````{tab-item} User type 4
`````{tab-set}
````{tab-item} Brand new version (branch)
- Add or make changes to file(s)
- Select files ready to be added to Git-timeline (staging)
- Add changes to Git-timeline locally (committing)
- Add changes to GitHub/GitLab (pushing)
````
````{tab-item} User type 4
- Eventually solve issues with combining versions
- Add or make changes to a file(s)
- Select files ready to be added to Git-Timeline
- Share changes with others in Git-timeline
- Pushing your changes
````
````{tab-item} User type 5
- Eventually solve issues with combining versions
- Add or make changes to a file(s)
- Select files ready to be added to Git-Timeline
- Check changes in book locally
- Share changes with others in Git-timeline
- If working on a repository locally: pushing your changes
````{tab-item} Brand new version (branch)
- Eventually solve conflicts with combining versions (merge conflicts, emerges after pulling)
- Add or make changes to file(s)
- Select files ready to be added to Git-timeline (staging)
- Add changes to Git-timeline locally (committing)
- Add changes to GitHub/GitLab (pushing)
````
`````
5. Check changes online
6. Repeat steps 4 and 5 until you're satisfied
7. Reviewing, (eventually repeat steps 4 and 5) and combine your version with main draft version of book
8. Publish changes to student version of the book
``````
``````{tab-item} User type 5
`````{tab-set}
````{tab-item} Brand new version (branch)
- Add or make changes to file(s)
- Check changes in book locally
- Select files ready to be added to Git-timeline (staging)
- Add changes to Git-timeline locally (committing)
- Add changes to GitHub/GitLab (pushing)
````
````{tab-item} Brand new version (branch)
- Eventually solve conflicts with combining versions (merge conflicts, emerges after pulling)
- Add or make changes to file(s)
- Check changes in book locally
- Select files ready to be added to Git-timeline (staging)
- Add changes to Git-timeline locally (committing)
- Add changes to GitHub/GitLab (pushing)
````
`````
``````
```````
4. Check changes online
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)

99
book/workflows/edit_book.md
View file

@ -2,9 +2,10 @@
Suppose we are writing a new chapter, or are updating an existing chapter for our Jupyter Book. We've created a new branch on which we are going to make the changes.
## Add or make changes to a file(s)
```````{tab-set}
``````{tab-item} User type 3
`````````{tab-set}
````````{tab-item} User type 3
**Add or make changes to a file**
Make changes to file in text editor...
or add new file by text or upload
@ -12,11 +13,19 @@ or add new file by text or upload
```{error} To be written
```
````````
````````{tab-item} User type 4 and 5
```````{tab-set}
``````{tab-item} Brand new version (branch)
If your branch was build from main, you've the most up-to-date version. So you can just continue with the next step. Next time you come here things might be different!
``````
``````{tab-item} User type 4 and 5
``````{tab-item} Existing version (branch)
### Eventually solve issues with combining versions
First make sure you update your branch so that you've the most up-to-date version. If you collaborate on this branch, you get the updates from your colleagues as well. This might lead into a merge conflict. How to solve that?
**Eventually solve conflicts with combining versions (merge conflicts, emerges after pulling)**
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?
`````{tab-set}
````{tab-item} With Git in VS Code
@ -33,38 +42,20 @@ First make sure you update your branch so that you've the most up-to-date versio
````
`````
### Make actual changes
```{error} To be written
```
Make some changes in for example VS Code and save them.
### Select files ready to be added to Git-Timeline
`````{tab-set}
````{tab-item} With Git in VS Code
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.
````
````{tab-item} With GitHub Desktop
The staging GitHub Desktop assumes you want to stage all files. You can unselect some of them (unstaging them)...
```{error} To be written
```
````
`````
``````
```````
## Check changes in book locally
**Add or make changes to file(s)**
```{error} To be written
```
Make some changes in for example VS Code and save them.
````````
`````````
**Check changes in book locally**
```````{tab-set}
``````{tab-item} User type 3 and 4
Not possible, unless you want to be a user type 5. Otherwise you'll see your changes later on online.
@ -76,17 +67,22 @@ build book locally and eventually startup python server...
``````
```````
## Share changes with others in Git-timeline
```````{tab-set}
``````{tab-item} User type 3
`````{tab-set}
````{tab-item} In GitLab
**Add changes to Git-timeline (committing)**
click commit in single text editor ...
```{error} To be written
```
````
````{tab-item} In GitHub
**Add changes to Git-timeline (committing)**
click commit in single text editor ...
```{error} To be written
```
@ -95,10 +91,23 @@ click commit in single text editor ...
``````
``````{tab-item} User type 4 and 5
Now we're going the share our changes in the Git-timeline with a *commit* and to *push* our changes to the *remote* repository (the one that is on the TU Delft GitLab/GitHub), so that others can see our changes and interact with them.
`````{tab-set}
````{tab-item} Using Git in VS Code
**Select 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.
**Add changes to Git-timeline locally (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
@ -106,6 +115,8 @@ Next, in the field that says "Message", write a short description of the changes
The new file has been staged, and we've written a Commit Message.
```
**Add changes to GitHub/GitLab (pushing)**
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.
@ -116,6 +127,20 @@ After committing, click the 🔄 button to push our changes to the remote reposi
````
````{tab-item} Using GitHub Desktop
**Select files ready to be added to Git-timeline (staging)**
The staging GitHub Desktop assumes you want to stage all files. You can unselect some of them (unstaging them)...
```{error} To be written
```
**Add changes to Git-timeline locally (committing)**
```{error} To be written
```
**Add changes to GitHub/GitLab (pushing)**
```{error} To be written
```

2
book/workflows/merge_request.md
View file

@ -6,7 +6,7 @@ Merging a branch into the main branch is also good moment to let a team-member r
There is a slight difference in terminology between GitLab and GitHub. GitLab uses the term *Merge* Request while GitHub uses the term *Pull* Request. Both actions refer to the merging of a branch into the main branch.
```
We're finished with our chapter, and now it's time to include all of our commits in the `main` branch.
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 practise 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

65
book/workflows/repositories.md
View file

@ -1,65 +0,0 @@
# Open files
```````{tab-set}
``````{tab-item} User type 3
Find your file on GitLab/GitHub ...
```{error} To be written
```
``````
``````{tab-item} User type 4 and 5
## Find source in online repository
`````{tab-set}
````{tab-item} From GitLab
1. On GitLab, go 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".
```{figure} ../images/gitlab-clone.png
:name: gitlab-clone
The cloning menu.
```
````
````{tab-item} From GitHub
```{error} To be written
```
````
````{tab-item} From GitHub using GitHub Desktop
```{error} To be written
```
````
`````
## Open the files locally
`````{tab-set}
````{tab-item} With Git in VS Code
2. 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".
```{figure} ../images/vscode-welcome.png
:name: vscode-welcome
The VS Code welcome screen.
```
3. 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".
4. You now have a local copy of the repository.
````
````{tab-item} With GitHub Desktop
```{error} To be written
```
````
`````
``````
```````