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 CollaborationGit

Browse source
This commit is contained in:
Tom van Woudenberg 2024-04-12 09:41:37 +02:00
commit 619d2d68ee
4 changed files with 280 additions and 182 deletions
Download patch file Download diff file Expand all files Collapse all files

106
book/workflows/branches.md
View file

@ -9,13 +9,15 @@ 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
**Create your own version by ...**
**Directly create your own version (branching) or select existing version**
`````````{tab-set}
````````{tab-item} ... user type 3
**... by directly creating your own version (branching) or selecting existing version in ...**
`````{tab-set}
````{tab-item} In GitLab
````{tab-item} ... 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
@ -41,7 +43,7 @@ The circled menu is the branch selection menu.
```
````
````{tab-item} In GitHub
````{tab-item} ... GitHub
```{error} To be written
```
@ -49,15 +51,18 @@ The circled menu is the branch selection menu.
`````
````````
````````{tab-item} User type 4 and 5
````````{tab-item} ... user type 4 and 5
**... for ...**
```````{tab-set}
``````{tab-item} First time opening (cloning) repository
``````{tab-item} ... repository opened for first time
**Find source link online repository**
**... by opening the repository locally (cloning) and creating your own version (branching) or select existing version (checkout branch) from ...**
`````{tab-set}
````{tab-item} From GitLab
````{tab-item} ... 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".
@ -68,14 +73,14 @@ The cloning menu.
```
````
````{tab-item} From GitHub
````{tab-item} ... GitHub
```{error} To be written
```
````
````{tab-item} From GitHub using GitHub Desktop
````{tab-item} ... GitHub using GitHub Desktop
```{error} To be written
```
@ -83,10 +88,10 @@ The cloning menu.
````
`````
**Open repository locally (cloning)**
**... with ...**
`````{tab-set}
````{tab-item} With Git in VS Code
````{tab-item} ... 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
@ -98,48 +103,8 @@ 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} Using previously opened (cloned) 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. 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
```{error} To be written
```
````
````{tab-item} With GitHub Desktop
```{error} To be written
```
````
`````
``````
```````
**Create your own version (branching)**
`````{tab-set}
````{tab-item} With Git in VS Code
```{error} To be written
```
4. The final 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. 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. 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`).
5. The final 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. 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. 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
@ -150,13 +115,42 @@ Location of the branch 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.
```
````
````{tab-item} With GitHub Desktop
````{tab-item} ... GitHub Desktop
```{error} To be written
```
````
`````
``````
``````{tab-item} ... previously opened repository
**by updating your repository (pulling) and creating your own version (branching) or select existing version (checkout branch) with ...**
`````{tab-set}
````{tab-item} ... Git in VS Code
```{error} To be written
```
````
````{tab-item} ... GitHub Desktop
```{error} To be written
```
````
`````
``````
```````
````````
`````````

108
book/workflows/collaboration.md
View file

@ -10,69 +10,83 @@ A jupyter book is composed out of many files which contain the educational conte
We have previously introduced the notions of using Git in the online environment (remote) or locally. All the (text, figures, etc.) files that make up the book are contained on the remote repository on GitLab or GitHub. This could be on an open repository on `gitlab.com` or `github.com`. In the context of creating educational books for students at TU Delft, the repository will most likely be located on `gitlab.tudelft.nl` or `github.com/teachbooks`.
The steps involved are as follows:
1. Assign task to yourself
2. Create your own version (branching) of the book by:
1. **Assign task to yourself (milestones, issues)**
2. **Create your own version 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 3
**... by directly creating your own version (branching) or selecting existing version:**
- branching
``````
``````{tab-item} User type 4 and 5
``````{tab-item} ... user type 4 and 5
**... for ...**
`````{tab-set}
````{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} ... repository opened for first time
**... by opening the repository locally (cloning) and creating your own version (branching) or select existing version (checkout branch):**
- cloning
- branching / 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)
````{tab-item} ... previously opened repository
**... by updating your repository (pulling) and creating your own version (branching) or select existing version (checkout branch):**
- pulling
- branching / checkout branch
````
`````
``````
```````
3. Edit the book by:
3. **Edit the book by ...**
```````{tab-set}
``````{tab-item} User type 3
- Add or make changes to a file
- Add changes to Git-timeline (committing)
``````{tab-item} ... user type 3
**... by directly adding changes on a single file to Git-timeline (committing):**
- adding or making changes to single file
- committing
``````
``````{tab-item} User type 4
``````{tab-item} ... user type 4
... on ...
`````{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} ... 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):**
- adding or making changes to file(s)
- staging
- committing
- pushing
````
````{tab-item} Existing 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)
````{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):**
- pulling
- solving merge conflicts
- adding or making changes to file(s)
- staging
- committing
- pushing
````
`````
``````
``````{tab-item} User type 5
``````{tab-item} ... user type 5
... on ...
`````{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)
**... 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):**
- adding or making changes to file(s)
- checking changes locally
- staging
- committing
- pushing
````
````{tab-item} Existing 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)
````{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):**
- pulling
- solving merge conflicts
- adding or making changes to file(s)
- checking changes locally
- staging
- committing
- 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)
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)**

242
book/workflows/edit_book.md
View file

@ -2,10 +2,12 @@
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.
**Edit files by ...**
`````````{tab-set}
````````{tab-item} User type 3
**Add or make changes to a file**
````````{tab-item} ... user type 3
**... by directly adding changes on a single file to Git-timeline (committing) in ...**
`````{tab-set}
````{tab-item} ... GitLab
Make changes to file in text editor...
or add new file by text or upload
@ -13,89 +15,43 @@ 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} Existing version (branch)
**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
click commit in single text editor ...
```{error} To be written
```
````
````{tab-item} With GitHub Desktop
````{tab-item} ... GitHub
Make changes to file in text editor...
or add new file by text or upload
```{error} To be written
```
click commit in single text editor ...
```{error} To be written
```
````
`````
``````
```````
````````
````````{tab-item} ... user type 4
**... for ...**
```````{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) with ...**
`````{tab-set}
````{tab-item} ... Git in VS Code
**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.
``````
``````{tab-item} User type 5
build book locally and eventually startup python server...
```{error} To be written
```
``````
```````
```````{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
```
````
``````
``````{tab-item} User type 4 and 5
`````{tab-set}
````{tab-item} Using Git in VS Code
**Select files ready to be added to Git-timeline (staging)**
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:
@ -106,8 +62,6 @@ 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
@ -115,7 +69,6 @@ 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.
@ -126,20 +79,22 @@ In the bottom left corner, next to the branch name, click the "Synchronize Chang
After committing, click the 🔄 button to push our changes to the remote repository.
````
````{tab-item} Using GitHub Desktop
````{tab-item} ... GitHub Desktop
**Select files ready to be added to Git-timeline (staging)**
```{error} To be written
```
Make some changes in for example VS Code and save them.
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)**
Add changes to Git-timeline locally (committing)
```{error} To be written
```
**Add changes to GitHub/GitLab (pushing)**
Add changes to GitHub/GitLab (pushing)
```{error} To be written
```
@ -147,4 +102,137 @@ The staging GitHub Desktop assumes you want to stage all files. You can unselect
````
`````
``````
```````
``````{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) with ...**
`````{tab-set}
````{tab-item} ... Git in VS Code
**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?
```{error} To be written
```
````
````{tab-item} ... GitHub Desktop
text..
```{error} To be written
```
````
`````
``````
```````
````````
````````{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) with ...**
`````{tab-set}
````{tab-item} ... Git in VS Code
```{error} To be written
```
Make some changes in for example VS Code and save them.
build book locally and eventually startup python server...
```{error} To be written
```
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.
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.
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
```{error} To be written
```
Make some changes in for example VS Code and save them.
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
```
````
`````
``````
``````{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) with ...**
`````{tab-set}
````{tab-item} ... Git in VS Code
**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?
```{error} To be written
```
````
````{tab-item} ... GitHub Desktop
text..
```{error} To be written
```
````
`````
``````
```````
````````
`````````

6
book/workflows/milestones_issues.md
View file

@ -11,8 +11,10 @@ An issue is built up of the following attributes:
Every team member can create issues when they think of a task that would improve the book.
**Make and assign task to yourself (issues) in ...**
`````{tab-set}
````{tab-item} In GitLab
````{tab-item} ... GitLab
The issues in GitLab can be found on this page:
@ -24,7 +26,7 @@ You can create an issue by clicking on the blue `New Issue` button in the top ri
````
````{tab-item} In GitHub
````{tab-item} ... GitHub
```{error} To be written
```