mirror of
https://github.com/TeachBooks/manual.git
synced 2026-11-13 14:55:51 +00:00
Added user types, restructured sollaborative book-editing
This commit is contained in:
Tom van Woudenberg
parent
87c5cfc910
commit
f44ac6bbdd
17 changed files with 332 additions and 115 deletions
|
|
@ -22,6 +22,7 @@ parts:
|
|||
- file: workflows/repositories
|
||||
- file: workflows/branches
|
||||
- file: workflows/edit_book
|
||||
- file: workflows/check_changes_online
|
||||
- file: workflows/merge_request
|
||||
- file: workflows/publish
|
||||
- caption: Features
|
||||
|
|
|
|||
|
|
@ -1,5 +1,10 @@
|
|||
# Page download options
|
||||
|
||||
```{admonition} User types
|
||||
:class: tip
|
||||
This section is useful for user type 4-6.
|
||||
```
|
||||
|
||||
You can control the download option of the book in two ways:
|
||||
- Disabling downloading using cell tags `disable-download-page`
|
||||
- Add / replace download link with custom link using `spinhx-download-link-replacer`
|
||||
|
|
|
|||
|
|
@ -1,5 +1,10 @@
|
|||
# Exclude parts of book from published book
|
||||
|
||||
```{admonition} User types
|
||||
:class: tip
|
||||
This section is useful for user type 3-6.
|
||||
```
|
||||
|
||||
A new feature is added to enable testing of all interactive features on the web server (i.e., in the draft book) while preventing students from seeing it. Pages in the draft book (`main` branch) can be manually stripped out of the table of contents when a merge request from `main` to `publish` is made using a tag `REMOVE-FROM-PUBLISH`. Pages marked with this feature are still visible in the draft book and books build from source on personal computers. The tag is applied as follows:
|
||||
|
||||
```
|
||||
|
|
|
|||
|
|
@ -1,5 +1,10 @@
|
|||
# Python-enabled interactivity
|
||||
|
||||
```{admonition} User types
|
||||
:class: tip
|
||||
This section is useful for user type 5-6.
|
||||
```
|
||||
|
||||
In general, there are two option to include python-enabled interactivity embedded in your book:
|
||||
- Using our [own sphinx-thebe extension](live_code.md) which makes code cells in your `.ipynb` book pages editable and executable by the reader! Opposed to the original sphinx-thebe extensions, our extension runs python in the reader's browser and doesn't rely on an external webserver for the python kernel. We highly recommend this extension as it allows you to use the strength of combining text/figures and code of a jupyter book with interactivity!
|
||||
- Using [JupyterLite](jupyterlite/jupyterlite.md) to create 'iframe-like' Ipython consoles / jupyterbook / jupyter lab environments in your book. As these 'iframes' are separate modules added to your page, the integration with the other content in your book is less flexible as with our sphinx-thebe extension.
|
||||
|
|
@ -15,10 +15,17 @@ Git is a version control system (VCS), used by a wide variety of engineers and s
|
|||
|
||||
GitLab is a cloud-based version control system built around git. It provides a lot more features such as Issues, Merge Requests, CI/CD pipelines, etc. TU Delft has a license to use GitLab on our own local webservers—this means that all of the files are stored digitally on the TU Delft campus, rather than some unkown webserver that could be physically located in an unsafe location. This is also why we have our “own” GitLab located at gitlab.tudelft.nl, rather than the “normal” GitLab at gitlab.com.
|
||||
|
||||
## What is GitHub?
|
||||
|
||||
GitHub is the same service as GitLab, but it's part of a commercial company (Microsoft). It's the most well-known cloud-based git provider and provides a lot of functionalities for free for education. It also allows you to host websites on `github.io` eliminating the need for your own / TU Delft webserver, although you don't have full servercontrol.
|
||||
|
||||
## Terminology
|
||||
This is a (non-exhaustive) list of terminology that will be used in GitLab.
|
||||
This is a (non-exhaustive) list of terminology that will be used in Git.
|
||||
|
||||
- Repository: a collection of files and folders, along with a history of their changes and who made them.
|
||||
- Commit: a snapshot of the current state of the repository.
|
||||
- Branch: a development line.
|
||||
- Pushing: uploading new commits to the remote repository.
|
||||
- Pushing: uploading new commits to the remote repository.
|
||||
|
||||
## Additional lessons
|
||||
Software carpentry offers git-lessons if you'd like to learn more than just it's specific use for TeachBooks. The lessons are available [online](https://swcarpentry.github.io/git-novice/) and TU Delft offers these as part of a [Software Carpentry workshop](https://www.tudelft.nl/library/research-data-management/r/training-evenementen/training-voor-onderzoekers/software-carpentry-workshops)
|
||||
|
|
@ -7,12 +7,6 @@ This page is useful for user type 4-6.
|
|||
|
||||
In this section you will learn how to perform basic Git actions in VS Code / GitHub Desktop. Courses on Git usually make use of the command line interface to do these actions, but this introduces a steep learning curve. Instead, using Git from VS Code / GitHub Desktop is much more visual (i.e., more "clicky"), and therefore easier to use for those inexperienced with the command line.
|
||||
|
||||
## GitHub Desktop
|
||||
|
||||
GitHub is a competitor company to GitLab. It provides very similar services, but they are often called different names, or have slightly different features. GitHub provides a free software that is very useful: GitHub Desktop!
|
||||
|
||||
While GitLab is a cloud-based version control system built around git, GitHub Desktop makes it possible to manage our git repositories locally on our computers, even though they are stored on GitLab. This is very useful for working with the jupyter-book more extensively and work on interactive features. GitHub Desktop provides an alternative to Git in VS Code, and will be described on a later stage.
|
||||
|
||||
## Terminology
|
||||
This is a (non-exhaustive) list of terminology that will be used in Git for local use.
|
||||
|
||||
|
|
@ -29,25 +23,25 @@ This is a (non-exhaustive) list of terminology that will be used in Git for loca
|
|||
|
||||
## Installing Git
|
||||
|
||||
First, we need to install Git itself.
|
||||
First, we need to install Git itself. Although this isn't strictly required when using GitHub Desktop
|
||||
|
||||
````{tab} Windows
|
||||
````{tab} git on Windows
|
||||
1. Go to [this webpage](https://git-scm.com/download/win) and download the correct version of Git for your system.
|
||||
2. Execute the installer and go through it. You can leave all options to the default values, **but make sure the option "Git from the command line and also from 3rd-party software" is selected**. Without this option, we won't be able to use Git from VS Code.
|
||||
3. Once the installation is finished, check if everything works. Open the start menu, then type `git`. From the search results, open the application `Git Bash`. This will open a terminal window, in which you can execute commands. Type in the command `git`, and execute it by pressing enter. If Git is installed correctly, you should see some sort of help page. If it outputs an error, then something may went wrong with the installation (you may have selected a wrong option).
|
||||
````
|
||||
````{tab} MacOS
|
||||
````{tab} git on MacOS
|
||||
Open up a terminal window (*Command + Space*, type in `terminal`). Then, type the command `git`. If Git has been installed already, it will output some help. If Git has not been installed, you will get a pop-up that looks something like this:
|
||||
|
||||
```{figure} ../images/install-Xcode-CLT.png
|
||||
```
|
||||
|
||||
Click on `install`. The installation may take a couple of minutes. Once it's finished, check if everything has been installed correctly by exectuting `git` again.
|
||||
Click on `install`. The installation may take a couple of minutes. Once it's finished, check if everything has been installed correctly by executing `git` again.
|
||||
````
|
||||
|
||||
## Setting up SSH-keys
|
||||
|
||||
When we want to visit repositories on GitLab, we need to log in. The same holds if we want to interact with these repositories with Git from VS Code. This means that everytime we make a commit, pull, et cetera, we need to provide our password, which becomes very tedious. Alternatively, we can provide GitLab with an SSH-key of our sytem, so that GitLab knows it is indeed us that are making the changes to the repository, removing the need to provide a password.
|
||||
When we want to visit repositories on GitLab or GitHub, we need to log in. The same holds if we want to interact with these repositories with Git from VS Code. This means that everytime we make a commit, pull, et cetera, we need to provide our password, which becomes very tedious. Alternatively, we can provide GitLab/GitHub with an SSH-key of our system, so that GitLab/GitHub knows it is indeed us that are making the changes to the repository, removing the need to provide a password. If you're only using GitHub and GitHub desktop, SSH-keys aren't strictly required, but it's still advised you set these up.
|
||||
|
||||
1. Open up a terminal window (Git Bash on Windows). Next, type (or copy and paste) the following command:
|
||||
|
||||
|
|
@ -62,6 +56,8 @@ When we want to visit repositories on GitLab, we need to log in. The same holds
|
|||
|
||||
3. You will now be asked to enter a passphrase. You can give one, but you will be asked for it everytime you make a commit, so it's better to leave this field emtpy and use this key only for GitLab. After the command is done executing, it will generate two files: `id_ed25519` and `id_ed25519.pub`. The `.pub` file is the public part of the SSH-Key which we need.
|
||||
|
||||
`````{tab-set}
|
||||
````{tab-item} continue on GitLab
|
||||
|
||||
4. Go to [GitLab](https://gitlab.tudelft.nl) and log in using your NetID. Click on your profile icon on the top-right of the page, then go to Preferences. In the menu on the left, go to SSH-Keys. You are now greeted with a screen that looks like this:
|
||||
|
||||
|
|
@ -82,6 +78,41 @@ When we want to visit repositories on GitLab, we need to log in. The same holds
|
|||
|
||||
Welcome to GitLab, <netid>!
|
||||
|
||||
````
|
||||
````{tab-item} continue on GitHub
|
||||
|
||||
4. Go to [GitHub](https://github.com/) and log in. In the upper-right corner of any page, click your profile photo, then click Settings.
|
||||
|
||||
```{figure} https://docs.github.com/assets/cb-45016/mw-1440/images/help/settings/userbar-account-settings-global-nav-update.webp
|
||||
:width: 200px
|
||||
```
|
||||
|
||||
5. In the "Access" section of the sidebar, click SSH and GPG keys.
|
||||
|
||||
6. Click New SSH key or Add SSH key.
|
||||
|
||||
7. In the "Title" field, add a descriptive label for the new key. For example, if you're using a personal laptop, you might call this key "Personal laptop".
|
||||
|
||||
8. Select the type of key: authentication
|
||||
|
||||
9. Navigate to the `id_ed25519.pub` file that we generated in step 2. Open the file with a text editor (Notepad on Windows, textEdit on Mac). Copy its contents and paste it in the 'Key' field.
|
||||
|
||||
```{note}
|
||||
On MacOS, the `.ssh/` folder is hidden by default, so you won't be able to find it in finder. To show hidden files and folders, press **Command + Shift + .**
|
||||
```
|
||||
10. Click Add SSH key.
|
||||
|
||||
11. Now test the connection. Go to the terminal (Git Bash on windows) and type:
|
||||
|
||||
ssh -vT git@github.com
|
||||
|
||||
You should get a huge output, but somewhere at the end of that output it should say something like:
|
||||
|
||||
Welcome to GitLab, <username>!
|
||||
|
||||
````
|
||||
`````
|
||||
|
||||
## Updating the local Git environment
|
||||
|
||||
The final step is to provide a username and email address to Git, so our commits can be identified. To do this, in the terminal (Git Bash on Windows) type in the following command for the username:
|
||||
|
|
@ -92,8 +123,11 @@ And type the following command to set the email address:
|
|||
|
||||
git config --global user.email "<your TU Delft email>"
|
||||
|
||||
## Configuring Git Bash
|
||||
## GitHub Desktop
|
||||
|
||||
GitHub is a competitor company to GitLab. It provides very similar services, but they are often called different names, or have slightly different features. GitHub provides a free software that is very useful: [GitHub Desktop](https://desktop.github.com/)! While GitLab is a cloud-based version control system built around git, GitHub Desktop makes it possible to manage our git repositories locally on our computers, even though they are stored on GitLab. This is very useful for working with the jupyter-book more extensively and work on interactive features. GitHub Desktop provides an alternative to Git in VS Code, and will be described on a later stage.
|
||||
|
||||
## Configuring Git Bash
|
||||
Git Bash is a shell (also referred to as "the terminal") that is automatically installed with git. It provides Unix-like commands on a Windows OS, and is recommended for working with open source projects like Jupyter (for example `pip install`, building Jupyter books, using Git Bash in VS Code, etc). To do this, `conda` needs to be setup properly; this is described in the {ref}`Getting Anaconda to work in terminal <vscode-setup-bash>`.
|
||||
|
||||
## More on GitLab
|
||||
|
|
|
|||
|
|
@ -14,13 +14,13 @@ Different types of users will interact with the website or the Jupyter Books dif
|
|||
2. **Colleague providing feedback on the draft website**. <br>
|
||||
In a similar manner as students, colleages and team members can leave content related comments on the website through extensions. In this way, multiple teachers can give input in the draft of the textbook and course material without requiring and exact understanding of Jupyter Books or GitLab/GitHub. The responsible teacher (or student assistants) can then make the adaptations to the book as recommended by their colleagues.
|
||||
|
||||
3. **Colleague making adjustments in GitLab/GitHub using single text editor**. <br>
|
||||
3. **Colleague making adjustments to single files in GitLab/GitHub using single text editor**. <br>
|
||||
This type of user requires only very basic knowledge in GitLab/GitHub in order to make changes to the website themselves without needing to install any software! Making adjustments using single text editor only requires the user to be able to login into GitLab/GitHub and edit .md or .ipynb files. The changes can be done directly in the main or publish branch and if a new branch is needed for the changes then the set-up and merging can be taken care of by someone more familiar in GitLab/GitHub.
|
||||
|
||||
4. **Colleague making text adjustments locally**. <br>
|
||||
4. **Colleague making text adjustments to multiple files at the same time locally**. <br>
|
||||
User 4 is a hybrid between type 3 and 5. Basically this user is making changes by editing the .md files locally using, for example, VS Code. Therefore, this user requires a little bit more knowledge on git (think of pulling and pushing changes) but their main focus remains to make adjustments to the content of the book by editing .md files whereas user type 4 has more knowledge to make changes to python files the book as well. This user can build the book online.
|
||||
|
||||
5. **Colleague making text and python adjustments to non-interactive content locally**. <br>
|
||||
5. **Colleague making text and python adjustments to multiple non-interactive content locally**. <br>
|
||||
This user has more knowledge in GitLab/GitHub than the previous user and can basically take care of branching and merging by themselves. They know how to work with software for editing .md and .ipynb files. They can use the draft book online to view their changed in the book, or build the book locally. The tricky part however is implementing interactive features in the book as they definitely require more knowledge on implementation and testing using a local python server or in the draft version online.
|
||||
|
||||
6. **Colleague making adjustments to all content locally**. <br>
|
||||
|
|
|
|||
|
|
@ -15,12 +15,16 @@ VS Code can be downloaded from [here](https://code.visualstudio.com). The instal
|
|||
|
||||
When working with Jupyter Book (or Notebooks in general), these extensions are highly recommended:
|
||||
|
||||
- [Python](https://marketplace.visualstudio.com/items?itemName=ms-python.python) - for obvious reasons. Also includes Jupyter Notebook rendering.
|
||||
- [MyST-Markdown](https://marketplace.visualstudio.com/items?itemName=ExecutableBookProject.myst-highlight) - adds support for MyST markdown, including previews.
|
||||
- [YAML](https://marketplace.visualstudio.com/items?itemName=redhat.vscode-yaml) - enables validation of `.yml` files (the format of the Jupyter Book configuration files).
|
||||
|
||||
## Using the Terminal in VS Code (Windows only)
|
||||
- User type 4-6:
|
||||
- [MyST-Markdown](https://marketplace.visualstudio.com/items?itemName=ExecutableBookProject.myst-highlight) - adds support for MyST markdown, including previews.
|
||||
- [Spell checker](https://marketplace.visualstudio.com/items?itemName=streetsidesoftware.code-spell-checker) - Spelling checker for source code and text
|
||||
- User type 5-6
|
||||
- [YAML](https://marketplace.visualstudio.com/items?itemName=redhat.vscode-yaml) - enables validation of `.yml` files (the format of the Jupyter Book configuration files).
|
||||
- [Python](https://marketplace.visualstudio.com/items?itemName=ms-python.python) - for obvious reasons. Also includes Jupyter Notebook rendering.
|
||||
- [GitHub Copilot](https://marketplace.visualstudio.com/items?itemName=GitHub.copilot) - Your AI pair progammer
|
||||
- [Jupyter Cell Tags](https://marketplace.visualstudio.com/items?itemName=ms-toolsai.vscode-jupyter-cell-tags) - Jupyter Cell Tags support
|
||||
|
||||
## Using the Terminal in VS Code (Windows only), user type 5-6 only
|
||||
By default, Powershell is the default terminal used in VS Code. However, Git Bash is recommended because it provides Unix-like commands, making it much easier to find help on sites like Stack Exchange. It also works better with open source projects like Jupyter. Git Bash installs automatically with git which you'll learn in the next chapter; to set as default:
|
||||
* Type `Ctrk+Shift+P` to open the command palette (it's also the top item in the "View" menu list)
|
||||
* Start type "terminal default" and you will soon see and be able to select the setting "Terminal: Select Default Profile" (hit `Enter`)
|
||||
|
|
|
|||
|
|
@ -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
17
book/workflows/check_changes_online.md
Normal 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.
|
||||
|
|
@ -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
|
||||
|
|
@ -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
|
||||
...
|
||||
|
||||
````
|
||||
`````
|
||||
`````
|
||||
|
||||
``````
|
||||
```````
|
||||
|
|
@ -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
|
||||
```
|
||||
````
|
||||
`````
|
||||
|
||||
|
|
|
|||
|
|
@ -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
|
||||
```
|
||||
|
||||
````
|
||||
|
||||
`````
|
||||
|
|
|
|||
|
|
@ -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>
|
||||
|
||||
|
||||
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>
|
||||
|
||||
|
||||
````
|
||||
|
||||
````{tab-item} Issues in GitHub
|
||||
...
|
||||
````{tab-item} In GitHub
|
||||
|
||||
```{error} To be written
|
||||
```
|
||||
|
||||
````
|
||||
`````
|
||||
|
|
|
|||
|
|
@ -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`
|
||||
|
|
@ -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
|
||||
```
|
||||
|
||||
````
|
||||
`````
|
||||
`````
|
||||
|
||||
``````
|
||||
```````
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue