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

Added user types, restructured sollaborative book-editing

Browse source
This commit is contained in:
Tom van Woudenberg 2024-04-11 12:28:44 +02:00
parent 87c5cfc910
commit f44ac6bbdd
17 changed files with 332 additions and 115 deletions
Download patch file Download diff file Expand all files Collapse all files

51
book/workflows/branches.md
View file

@ -1,4 +1,4 @@
# Branches
# Create your own version
Branches are a very useful feature of Git. Branches allow you to work on multiple versions of your codebase simultaneously; you create a copy of your codebase, on which you can work independently of the main codebase. The main branch is the default branch. The content on this branch will be the most up to date version of the book. Therefore, new branches, which are made to add or fix some content in the book, are usually cloned from the main branch. This has many advantages compared to making the edits immediately in the main branch. Some advantages of working with branches are:
@ -9,8 +9,11 @@ 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} Branching in GitLab
````{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".
@ -36,10 +39,41 @@ We're making a new branch called `chapter-2` from the `main` branch.
The circled menu is the branch selection menu.
```
````
````{tab-item} Branching in GitHub
...
````{tab-item} In GitHub
```{error} To be written
```
````
````{tab-item} Branching locally with Git in VS Code
`````
``````
``````{tab-item} User type 4, 5 and 6
### Obtain newest version from online repository
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.
`````{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
`````{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`).
```{figure} ../images/git-branch-menu-main.png
:name: git-branch-menu-main
@ -53,9 +87,12 @@ Location of the branch menu.
The branch selection menu, where our new branch has shown up.
```
````
````{tab-item} Branching locally with GitHub Desktop
...
````{tab-item} With GitHub Desktop
```{error} To be written
```
````
`````
``````
```````
Now that we've created and checked out our new branch, we can start {ref}`making and committing changes <stage-commit-push>`.

17
book/workflows/check_changes_online.md Normal file
View file

@ -0,0 +1,17 @@
# Check changes online
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, but the workflow will soon be the same as for GitHub.
````
````{tab-item} In GitHub
- Wait for the action to finish
- Visit the website of your build book
```{error} To be written
```
`````
You can keep on [editing](edit_book) and checking your changes until you're satisfied and ready for a review by a colleague.

43
book/workflows/collaboration.md
View file

@ -5,16 +5,37 @@
This page is useful for user type 3-6.
```
As previously mentioned there are multiple platforms that can host Git repositories which are extremely useful for collaboration on text-based files. Here we will elaborate on two: GitLab and GitHub both in the online environment and locally.
A jupyter book is composed out of many files which contain the educational content produced by you. Through the use of branches it is possible to work on the book at the same time as your team-members. Working on content for the book is mainly individual work, the beauty of git comes in when everybody's changes are merged into the main branch.
Globally, the steps involved are as follows:
1. Define issue to work on
2. Open the files of the repository online or clone the repository to work on it locally
3. Create a branch for your changes
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. Open the files of the repository online or locally
3. Create your own version of the book
4. Edit the book by:
- Pulling remote changes from others
- Staging your changes
- Commit a collection of changes
- If working on a repository locally: pushing your changes
5. Reviewing and merging changes in a merge request
6. Publish changes to published version of book
`````{tab-set}
````{tab-item} User type 3
- Make changes to your file
- Commit a changes
````
````{tab-item} User type 4
- Pulling remote changes from others
- Make changes to your file
- Saving / Staging your changes
- Commit a collection of changes
- Pushing your changes
````
````{tab-item} User type 5 and 6
- Pulling remote changes from others
- Make changes to your file
- Saving / Staging your changes
- Check changes locally
- Commit a collection of changes
- If working on a repository locally: pushing your changes
````
`````
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

143
book/workflows/edit_book.md
View file

@ -1,34 +1,48 @@
# Editing the book
# Edit
A jupyter book is composed out of many markdown files which contain the educational content produced by you. Through the use of branches it is possible to work on the book at the same time as your team-members. Working on content for the book is mainly individual work, the beauty of git comes in when everybody's changes are merged into the main branch.
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.
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, and we've checked out this branch (make sure this is really the case by checking the name of the current branch in the bottom-left corner of your VS Code window!).
## Make changes to your file
```````{tab-set}
``````{tab-item} User type 3
## Pulling
Make changes to file in text editor...
or add new file by text or upload
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.
```{error} To be written
```
``````
``````{tab-item} User type 4, 5 and 6
### 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?
`````{tab-set}
````{tab-item} Pulling changes using Git in VS Code
...
````{tab-item} With Git in VS Code
```{error} To be written
```
````
````{tab-item} Pulling changes using GitHub Desktop
...
````{tab-item} With GitHub Desktop
```{error} To be written
```
````
`````
## Staging
### 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} Staging in GitLab
In GitLab staging doesn't exist, just edit a file and you can directly commit it.
...
````
````{tab-item} Staging in GitHub
In GitHub staging doesn't exist, just edit a file and you can directly commit it.
...
````
````{tab-item} Staging using Git in VS Code
````{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:
@ -39,22 +53,55 @@ 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} Staging using GitHub Desktop
...
````{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
```
````
`````
## Committing
Now that we've made some change, we need to add them to our git-timeline.
``````
```````
## Review 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 ...
```{error} To be written
```
``````
``````{tab-item} User type 6
build book locally and startup python server...
```{error} To be written
```
``````
```````
## Share changes with others in Git-timeline
```````{tab-set}
``````{tab-item} User type 3
`````{tab-set}
````{tab-item} Committing in GitLab
...
````{tab-item} In GitLab
click commit in single text editor ...
```{error} To be written
```
````
````{tab-item} Committing in GitHub
...
````{tab-item} In GitHub
click commit in single text editor ...
```{error} To be written
```
````
````{tab-item} Committing using Git in VS Code
``````
``````{tab-item} User type 4, 5 and 6
`````{tab-set}
````{tab-item} Using Git in VS Code
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
@ -63,29 +110,37 @@ 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.
````
````{tab-item} Committing using GitHub Desktop
...
````
`````
```{tip}
Unlike this example, you do not have to stage and commit every file individually. In a real case, a chapter may consist of multiple files (and images!), and it makes sense to add them in the same commit.
```
## Pushing the changes
Are we done now? Yes, if you've made all your changes on GitLab / GitHub. However, no! if you did that locally! Up to now, we have only made changes and committed to the *local* copy of the repository. We still need to *push* our changes to the *remote* repository (the one that is on the TU Delft GitLab), so that others can see our changes and interact with them.
`````{tab-set}
````{tab-item} Committing using Git in VS Code
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} Using GitHub Desktop
```{error} To be written
```
````
````{tab-item} Committing using GitHub Desktop
`````
Are we done now? Yes, if you've made all your changes on GitLab / GitHub. However, no! if you did that locally! Up to now, we have only made changes and committed to the *local* copy of the repository. We still need to *push* our changes to the *remote* repository (the one that is on the TU Delft GitLab), so that others can see our changes and interact with them.
`````{tab-set}
````{tab-item} Using Git in VS Code
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} Using GitHub Desktop
...
````
`````
`````
``````
```````

3
book/workflows/githubtemplate.md
View file

@ -50,7 +50,8 @@ To learn more about how we do this, please see the [GitHub Actions documentation
````
````{tab-item} GitLab template
Will follow
```{error} To be written
```
````
`````

15
book/workflows/merge_request.md
View file

@ -1,6 +1,6 @@
# Reviewing and merging changes
# Reviewing and combine versions
Merging a branch into the main branch is also good moment to let a team-member review the content. This is done in the merge-request. By assigning a colleague to review your branch you can check the quality of your new content.
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.
```{note}
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.
@ -9,7 +9,7 @@ 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.
`````{tab-set}
````{tab-item} Committing using GitLab
````{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.
@ -41,7 +41,12 @@ The finished merge request.
```
````
````{tab-item} Committing using GitHub
...
````{tab-item} In GitHub
```{error} To be written
```
````
`````

15
book/workflows/milestones_issues.md
View file

@ -1,4 +1,4 @@
# Milestones & Issues
# Assign task to yourself
In a repository, team members can define Milestones and Issues. Milestones are used to track the overall progress of the project to make sure that deadlines are met. A milestone can group many issues, which are individual tasks that need to be finished in order to reach the milestone.
@ -12,19 +12,22 @@ 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.
`````{tab-set}
````{tab-item} Issues in GitLab
````{tab-item} In GitLab
The issues in GitLab can be found on this page:
<img src="figures/Issues.png" alt="New Issue" width="1000" style="display:block; margin-left:auto; margin-right:auto;"> <br>
![issues](figures/Issues.png)
You can create an issue by clicking on the blue `New Issue` button in the top right corner.
<img src="figures/New_Issue_GitLab.png" alt="New Issue" width="600" style="display:block; margin-left:auto; margin-right:auto;"> <br>
![new issue](figures/New_Issue_GitLab.png)
````
````{tab-item} Issues in GitHub
...
````{tab-item} In GitHub
```{error} To be written
```
````
`````

9
book/workflows/publish.md
View file

@ -1,4 +1,7 @@
# Publishing your book
# Publish to students
Once the book is ready to be published, a static website can be created through GitLab. (Need more info on that/Are we using gitlab pages?)
If your repository is located in the [TeachBooks](https://gitlab.tudelft.nl/interactivetextbooks-citg) group on GitLab, you will see that it already has a branch called `publish`. This branch is where the student version of your book should go. The idea behind this is that the student version of your book should only change a few times per year at most (and certainly not right before an exam!) to prevent confusion. This way, you can still make frequent changes to the `main` branch.
For this step it is assumed you’re using TeachBook’s GitHub actions or TeachBook’s GitLab pipeline.
Until now, you merged your changes to branch `main`, but you might see a branch called `publish` as well. This branch is where the student version of your book should go. The idea behind this is that the student version of your book should only change a few times per year at most to prevent confusion. This way, you can still make frequent changes to the `main` branch.
To publish your changes to the student version, simply repeat the next step but now from `main` to `publish`

46
book/workflows/repositories.md
View file

@ -1,14 +1,19 @@
# Open files online / clone files
We have previously introduced the notions of using Git in the online environment (remote) or locally. All the (markdown) 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`.
# Open files
If you'd like to work on your book locally, you need to clone your book.
```````{tab-set}
``````{tab-item} User type 3
Find your file on GitLab/GitHub ...
```{error} To be written
```
### Cloning a repository
``````
``````{tab-item} User type 4, 5 and 6
## Find source in online repository
`````{tab-set}
````{tab-item} Cloning repository from GitLab
Here's how you do it with VS Code:
````{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".
@ -19,19 +24,23 @@ The cloning menu.
```
````
````{tab-item} Cloning repository from GitHub
...
````{tab-item} From GitHub
```{error} To be written
```
````
````{tab-item} Cloning repository from GitHub using GitHub Desktop
...
````{tab-item} From GitHub using GitHub Desktop
```{error} To be written
```
````
`````
Now that we've obtained the source, we can set up the files locally:
## Open the files locally
`````{tab-set}
````{tab-item} Cloning repository with Git in VS Code
````{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
@ -45,7 +54,12 @@ The VS Code welcome screen.
4. You now have a local copy of the repository.
````
````{tab-item} Cloning repository with GitHub Desktop
....
````{tab-item} With GitHub Desktop
```{error} To be written
```
````
`````
`````
``````
```````