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

Added full steps to overview as well

Browse source
This commit is contained in:
Tom van Woudenberg 2024-04-11 16:56:56 +02:00
parent 93378a1270
commit b107b47d06
4 changed files with 132 additions and 68 deletions
Download patch file Download diff file Expand all files Collapse all files

21
book/workflows/branches.md
View file

@ -12,6 +12,8 @@ The act of making a new branch from an existing one is called *branching*. Usual
`````````{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".
@ -30,13 +32,14 @@ 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
@ -49,10 +52,9 @@ The circled menu is the branch selection menu.
````````{tab-item} User type 4 and 5
```````{tab-set}
``````{tab-item} First time opening repository
``````{tab-item} First time opening (cloning) repository
(cloning)=
## Find source in online repository
**Find source link online repository**
`````{tab-set}
````{tab-item} From GitLab
@ -81,7 +83,7 @@ The cloning menu.
````
`````
## Open repository locally
**Open repository locally (cloning)**
`````{tab-set}
````{tab-item} With Git in VS Code
@ -107,10 +109,9 @@ The VS Code welcome screen.
``````
``````{tab-item} Using previously opened repository
``````{tab-item} Using previously opened (cloned) repository
(pulling)=
### 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. you can do so by `pull` changes from the remote repository on GitHub / GitLab into your local folder.
`````{tab-set}
@ -130,7 +131,7 @@ 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
@ -148,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

78
book/workflows/collaboration.md
View file

@ -11,30 +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. Create your own version of the book
3. 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
- Add changes to 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
- Add changes to Git-timeline locally
- Add changes to GitHub/GitLab
````
````{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
- Add changes to Git-timeline locally
- Add changes to GitHub/GitLab
````{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)
````
`````
``````
``````{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, (eventually repeat steps 3 and 4) and combine your version with main draft version of book
7. Publish changes to student version of the book
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
If you collaborate with colleagues on this branch, you 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?
**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 @@ If you collaborate with colleagues on this branch, you get the updates from your
````
`````
### 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...
``````
```````
## Add changes to 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. 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 aren't there, we'll now continue this example with the following merge of our branch into `main`.
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