mirror of
https://github.com/TeachBooks/manual.git
synced 2026-11-12 22:35:51 +00:00
Merge branch 'main' of gitlab.tudelft.nl:interactivetextbooks-citg/jupyter-book-manual
This commit is contained in:
Tom van Woudenberg
commit
d1c0109539
43 changed files with 511 additions and 158 deletions
|
|
@ -111,7 +111,7 @@ And type the following command to set the email address:
|
|||
|
||||
## 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.
|
||||
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.
|
||||
|
||||
## Terminology
|
||||
This is a (non-exhaustive) list of terminology that will be used in Git for local use.
|
||||
|
|
|
|||
|
|
@ -5,7 +5,7 @@
|
|||
This page is useful for user type 3-5.
|
||||
```
|
||||
|
||||
You'll need to interact with Git to collaborate on TeachBooks, but what is that thing?
|
||||
You'll need to interact with Git to collaborate on TeachBooks, but what is this thing?
|
||||
|
||||
## What is Git?
|
||||
|
||||
|
|
@ -13,11 +13,11 @@ Git is a version control system (VCS), used by a wide variety of engineers and s
|
|||
|
||||
### What is GitLab?
|
||||
|
||||
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.
|
||||
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.
|
||||
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.
|
||||
|
||||
### 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)
|
||||
|
|
@ -6,7 +6,7 @@ The following table will link the relevant installation and setup steps for you.
|
|||
|
||||
|User Types|Required actions|<div style="width:200px">Installation</div>|
|
||||
|:---:|:---|:---|
|
||||
| Type 1<br>Type 2 | Review book | No software needed! Just open your interactive book online and give review in the way you're asked to do|
|
||||
| Type 1<br>Type 2 | Review book | No software needed! Just open your interactive book online and give a review in the way you're asked to |
|
||||
| Type 3 | Edit single files online | No software needed! But you'll interact with Git, which might be a new thing for you |
|
||||
| Type 4 | Editing text<br>Git| VS Code<br>GitHub Desktop / Git in VS Code |
|
||||
| Type 5 | Editing text<br>Git<br>Managing code-related software<br>Build your book | VS Code<br>GitHub Desktop / Git in VS Code<br>Anaconda<br>Jupyter Book |
|
||||
| Type 5 | Editing text<br>Git<br>Managing code-related software<br>Build your book | VS Code<br>GitHub Desktop / Git in VS Code<br>Anaconda<br>Jupyter Book |
|
||||
|
|
|
|||
|
|
@ -2,14 +2,7 @@
|
|||
|
||||
Different types of users will interact with the website or the Jupyter Books differently and will therefore need to know more or less about the composition of the book. For now we will differentiate 6 types of users.
|
||||
|
||||
1. **Students providing feedback on the published website**. <br>
|
||||
<img src="figures/type 1.jpg" alt="Example Image" align="left" width="120" style="margin: 10px;">
|
||||
|
||||
There are multiple tools of providing feedback in the build book:
|
||||
- Using the [hypothesis](https://jupyterbook.org/en/stable/interactive/comments/hypothesis.html)-extension which allows public/private highlighting and annotating parts of the book. An example can be seen on the [MUDE website](https://mude.citg.tudelft.nl/book/intro.html)
|
||||
- Using the [Utterances](https://jupyterbook.org/en/stable/interactive/comments/utterances.html)-extension which allows commenting on pages for books which are hosted on GitHub. Those comments are converted to issues on GitHub for the editors to handle.
|
||||
|
||||
<br style="clear:both;">
|
||||
1. **Students providing feedback on the published website**.<br> <img src="figures/type 1.jpg" alt="Example Image" align="right" width="130" style="margin: 10px;"> There are multiple tools of providing feedback in the built book: a) Using the [hypothesis](https://jupyterbook.org/en/stable/interactive/comments/hypothesis.html)-extension which allows public/private highlighting and annotating parts of the book. An example can be seen on the [MUDE website](https://mude.citg.tudelft.nl/book/intro.html). b) Using the [Utterances](https://jupyterbook.org/en/stable/interactive/comments/utterances.html)-extension which allows commenting on pages for books which are hosted on GitHub. Those comments are converted to issues on GitHub for the editors to handle.
|
||||
|
||||
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.
|
||||
|
|
@ -21,7 +14,7 @@ Different types of users will interact with the website or the Jupyter Books dif
|
|||
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 code (especially Python) adjustments to multiple files at the same time locally**. <br>
|
||||
<img src="figures/type 5.jpg" alt="Example Image" align="left" width="120" style="margin: 10px;">
|
||||
<img src="figures/type 5.jpg" alt="Example Image" align="right" width="120" style="margin: 10px;">
|
||||
|
||||
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.
|
||||
|
||||
|
|
|
|||
|
|
@ -9,16 +9,19 @@ 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.
|
||||
|
||||
**Create your own version by ...**
|
||||
**Create your own version as ...**
|
||||
|
||||
`````````{tab-set}
|
||||
````````{tab-item} ... user type 3
|
||||
|
||||
**... by directly creating your own version (branching) or selecting existing version in ...**
|
||||
````````{tab-item} ... user type 3 ...
|
||||
|
||||
**... by directly creating your own version of the book (branching) or by selecting an existing version in ...**
|
||||
|
||||
`````{tab-set}
|
||||
|
||||
````{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".
|
||||
|
||||
1. 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
|
||||
:name: new-branch-button
|
||||
|
|
@ -41,30 +44,42 @@ We're making a new branch called `chapter-2` from the `main` branch.
|
|||
|
||||
The circled menu is the branch selection menu.
|
||||
```
|
||||
|
||||
````
|
||||
|
||||
````{tab-item} ... GitHub
|
||||
|
||||
```{error} To be written
|
||||
1. Open the repository in which you want to work in. In the top bar you will see your current branch `main` and next to that there is a tab called `Branches`.
|
||||
|
||||
```{figure} ../figures/NewBranch_GitHub.PNG
|
||||
```
|
||||
2. Clicking on `Branches` will bring you to an overview of all the branches in the repository. Click on the green `Create Branch` button.
|
||||
|
||||
```{figure} ../figures/NewBranch_GitHub2.PNG
|
||||
```
|
||||
3. Finally, give your branch a name and specifiy the source branch. <br>
|
||||
Tip: It makes sense to give the branch a name related to the content you will be creating or altering.
|
||||
|
||||
```{figure} ../figures/NewBranch_GitHub3.PNG
|
||||
```
|
||||
````
|
||||
`````
|
||||
````````
|
||||
|
||||
````````{tab-item} ... user type 4 and 5
|
||||
````````{tab-item} ... user type 4 and 5 ...
|
||||
|
||||
|
||||
**... for ...**
|
||||
**Select the statement that applies to you.**
|
||||
|
||||
```````{tab-set}
|
||||
``````{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) from ...**
|
||||
``````{tab-item} I am opening the repositery for the first time (Cloning)
|
||||
|
||||
**I would like to open the repository locally (cloning) using ...**
|
||||
|
||||
`````{tab-set}
|
||||
````{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".
|
||||
````{tab-item} ... GitLab ...
|
||||
|
||||
1. Navigate to the repository of your book. Click on the blue button that says "Clone" ({numref}`gitlab-clone`), and copy the link under "Clone with SSH".
|
||||
|
||||
```{figure} ../images/gitlab-clone.png
|
||||
:name: gitlab-clone
|
||||
|
|
@ -73,26 +88,51 @@ The cloning menu.
|
|||
```
|
||||
````
|
||||
|
||||
````{tab-item} ... GitHub
|
||||
````{tab-item} ... GitHub ...
|
||||
|
||||
```{error} To be written
|
||||
```
|
||||
1. Open the repository that you would like to clone. In the top bar on the right, you will a green button called `<> Code`.
|
||||
|
||||
<figure align="center">
|
||||
<img src="figures/NewBranch_GitHub.PNG" alt="Example Image" width="650">
|
||||
</figure>
|
||||
|
||||
2. Clicking on the button will display the following screen. Make sure the option `SSH` is selected and copy the link.
|
||||
|
||||
<figure align="center">
|
||||
<img src="figures/Clone_GitHub.PNG" alt="Example Image" width="400">
|
||||
</figure>
|
||||
````
|
||||
|
||||
````{tab-item} ... GitHub using GitHub Desktop
|
||||
````{tab-item} ... GitHub through GitHub Desktop ...
|
||||
|
||||
```{error} To be written
|
||||
```
|
||||
1. Open the repository that you would like to clone. In the top bar on the right, you will a green button called `<> Code`.
|
||||
|
||||
<figure align="center">
|
||||
<img src="figures/NewBranch_GitHub.PNG" alt="Example Image" width="650">
|
||||
</figure>
|
||||
|
||||
2. Clicking on the button will display the following screen. Click on `Open with GitHub Desktop`.
|
||||
|
||||
<figure align="center">
|
||||
<img src="figures/Clone_GitHub.PNG" alt="Example Image" width="400">
|
||||
</figure>
|
||||
|
||||
3. The Browser should then automatically open GitHub Desktop. Customize the path to the location where you would like to save to files locally. Finally, click on `Clone`.
|
||||
|
||||
<figure align="center">
|
||||
<img src="figures/CloneRepo_TroughGithubdesk.PNG" alt="Example Image" width="400">
|
||||
</figure>
|
||||
|
||||
You've cloned the repository now directly, so you can skip the next step.
|
||||
````
|
||||
`````
|
||||
|
||||
**... with ...**
|
||||
**... and I would like to clone the local repositery with ...**
|
||||
|
||||
`````{tab-set}
|
||||
````{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".
|
||||
````{tab-item} ... VS Code
|
||||
|
||||
1. Open a new VS Code window. You should be greeted with a welcome page ({numref}`vscode-welcome`). On this page, click "Clone Git Repository". Alternatively, open the Source Control menu from the left side bar, and click on "Clone Repository".
|
||||
|
||||
```{figure} ../images/vscode-welcome.png
|
||||
:name: vscode-welcome
|
||||
|
|
@ -100,11 +140,42 @@ The cloning menu.
|
|||
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".
|
||||
2. 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.
|
||||
3. You now have a local copy of the repository.
|
||||
4. Now you can start branching. Have a look at the other section!
|
||||
````
|
||||
|
||||
````{tab-item} ... GitHub Desktop
|
||||
|
||||
1. You have previously copied the link of the repositery you would like to clone from GitLab or GitHub. In GitHub Desktop, navigate to the top bar, click on `File` and then on `Clone repositery`.
|
||||
|
||||
```{figure} ../figures/CloneRepo_Githubdesk.PNG
|
||||
```
|
||||
2. In the top bar click on `URL`.
|
||||
|
||||
```{figure} ../figures/CloneRepo_TroughGithubdesk.PNG
|
||||
```
|
||||
3. Simply paste the link, specify the working directory (location where you would like to save the folder locally) and click on 'Clone'.
|
||||
|
||||
````
|
||||
`````
|
||||
``````
|
||||
|
||||
``````{tab-item} I have previously opened the repository (Branching)
|
||||
|
||||
**I want to (1) update my repository (pulling) and <br>
|
||||
(2) create my own version (branching) or select an existing version (checkout branch) using ...**
|
||||
|
||||
`````{tab-set}
|
||||
````{tab-item} ... Git in VS Code
|
||||
|
||||
1. The next 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
|
||||
|
||||
|
|
@ -115,42 +186,37 @@ 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} ... GitHub Desktop
|
||||
```{error} To be written
|
||||
```
|
||||
|
||||
````
|
||||
`````
|
||||
2. It can be that multiple people ar making changes to one branch. We have to make sure that we are using the most up to date version of the branch. Therefore, we need to pull all the changes from the remote repositery to our local repositery. Simply click the Icon with the two arrows.
|
||||
|
||||
``````
|
||||
```{figure} ../figures/Pull_VS.png
|
||||
:name: Pull_VS
|
||||
|
||||
``````{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
|
||||
Location of the branch menu.
|
||||
```
|
||||
|
||||
````
|
||||
````{tab-item} ... GitHub Desktop
|
||||
|
||||
```{error} To be written
|
||||
1. The next 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 GitHub Desktop, the top bar has a menu called `Current Branch`. By clicking on it you can see all the branches you created on the remote repositery.
|
||||
|
||||
```{figure} ../figures/CheckOutBranch_GitHubDesktop.PNG
|
||||
```
|
||||
2. Check out the branch by simply clicking on it. The following window will pop up.
|
||||
|
||||
```{figure} ../figures/CheckOutBranch_GitHubDesktop2.PNG
|
||||
```
|
||||
Leave your changes (stashed) on your working branch, in this case I was working in the branch called `collaboration git`.
|
||||
|
||||
3. Check that the branch is indeed checked out by looking at the branch menu at the the top left again; the current branch should say the name.
|
||||
|
||||
````
|
||||
`````
|
||||
``````
|
||||
|
||||
```````
|
||||
|
||||
|
||||
|
||||
````````
|
||||
`````````
|
||||
|
||||
|
|
|
|||
|
|
@ -1,17 +1,36 @@
|
|||
# Check changes online
|
||||
|
||||
```{Note}
|
||||
|
||||
This page is relevant for user type 4 and 5. When making changes to the book it can be useful to get an idea on how they will be realized in the online book. Whereas user type 5 can also build the book locally, user type 4 is more focused on the changes to the content.
|
||||
|
||||
However both users would certainly benefit from checking whether their changes look good in the book!
|
||||
```
|
||||
|
||||
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
|
||||
```
|
||||
|
||||
1. Enable GitHub Pages on your repositery. Note that if you use the Teachbooks template this is probably already done!
|
||||
|
||||
2. Once your book files are pushed to your GitHub repository you can view the book. Make sure you wait for the action to finish (GitHub Desktop shows progress if its part of a pull request, VS Code shows progress with the GitHub Actions addon).
|
||||
|
||||
3. Viewing the Book: Once GitHub Pages is enabled and your book is published, you can view it by visiting the GitHub Pages URL for your repository. The URL will typically be in the format https://<username>.github.io/<repository-name>.
|
||||
|
||||
Alternatively you can find it in the settings
|
||||
|
||||
- Go to your GitHub repository's settings.
|
||||
- Scroll down to the "GitHub Pages" section (left side-bar: pages)
|
||||
- Copy the link or click on `Visit site`
|
||||
|
||||
<figure align="center">
|
||||
<img src="figures/GitHubPages.PNG" alt="Example Image" width="650">
|
||||
</figure>
|
||||
`````
|
||||
|
||||
You can keep on [editing](edit_book) and checking your changes until you're satisfied and ready for a review by a colleague.
|
||||
|
|
@ -5,11 +5,12 @@
|
|||
This page is useful for user type 3, 4 and 5.
|
||||
```
|
||||
|
||||
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.
|
||||
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.
|
||||
|
||||
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 (milestones, issues)**
|
||||
2. **Create your own version of the book by**
|
||||
```````{tab-set}
|
||||
|
|
@ -89,4 +90,4 @@ The steps involved are as follows:
|
|||
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)**
|
||||
7. **Publish changes to student version of the book (merge request)**
|
||||
|
|
|
|||
|
|
@ -2,56 +2,107 @@
|
|||
|
||||
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 ...**
|
||||
**Edit files as ...**
|
||||
`````````{tab-set}
|
||||
````````{tab-item} ... user type 3
|
||||
**... by directly adding changes on a single file to Git-timeline (committing) in ...**
|
||||
````````{tab-item} ... user type 3 ...
|
||||
|
||||
**... by directly adding changes on a single file to the Git-timeline (committing) in ...**
|
||||
|
||||
`````{tab-set}
|
||||
````{tab-item} ... GitLab
|
||||
|
||||
Make changes to file in text editor...
|
||||
or add new file by text or upload
|
||||
In GitLab, you can directly make changes in the files on the remote repositery. You can make changes to the files already in the repositery using the text editor but you can also upload new files!
|
||||
|
||||
```{error} To be written
|
||||
```
|
||||
1. Navigate to the repositery you want to work in.
|
||||
|
||||
click commit in single text editor ...
|
||||
```{error} To be written
|
||||
```
|
||||
2. Create a new file by clicking on the plus button in the top bar. You can either create an entirely new file by clicking `New File` or if you already have created a file you can upload it by clicking `Upload File`.
|
||||
|
||||
<figure align="center">
|
||||
<img src="figures/User3_NewFile.PNG" alt="Example Image" width="500">
|
||||
</figure>
|
||||
|
||||
3. In the new window, you can start typing your content. Give your file a name and make sure to use the markdown extension: `Chapter1.md`. Once you are done, commit the new file to the repositery by clicking the blue button `Commit changes`.
|
||||
|
||||
<figure align="center">
|
||||
<img src="figures/User3_NewFile2.PNG" alt="Example Image" width="700">
|
||||
</figure>
|
||||
|
||||
4. In case you want to make changes to an existing file, navigate to the file in your remote repositery. Then click the blue button called `Edit` and select the option `Edit single file`.
|
||||
|
||||
<figure align="center">
|
||||
<img src="figures/User3_EditFile.PNG" alt="Example Image" width="700">
|
||||
</figure>
|
||||
|
||||
5. Make your changes in the text editor and when you are ready, commit your changes to the remote repositery by clicking on the blue `Commit changes` button.
|
||||
|
||||
<figure align="center">
|
||||
<img src="figures/User3_EditFile2.PNG" alt="Example Image" width="700">
|
||||
</figure>
|
||||
|
||||
6. In case you added a new file, you also need to include it table of contents of your book! The table of contents is specified in a file called `toc.yml` and it is already included in your repositery if you used the teachbooks template.
|
||||
|
||||
<figure align="center">
|
||||
<img src="figures/User3_toc.PNG" alt="Example Image" width="500">
|
||||
</figure>
|
||||
|
||||
You can edit it and commit the changes in the same manner as with markdown (.md) files.
|
||||
````
|
||||
````{tab-item} ... GitHub
|
||||
|
||||
Make changes to file in text editor...
|
||||
or add new file by text or upload
|
||||
In GitHub, you can directly make changes in the files on the remote repositery. You can make changes to the files already in the repositery using the text editor but you can also upload new files!
|
||||
|
||||
```{error} To be written
|
||||
```
|
||||
1. Navigate to the repositery you want to work in.
|
||||
|
||||
click commit in single text editor ...
|
||||
```{error} To be written
|
||||
```
|
||||
2. Create a new file by clicking on the button called `Add file` in the top bar. You can either create an entirely new file by clicking `Create new File` or if you already have created a file you can upload it by clicking `Upload files`.
|
||||
|
||||
<figure align="center">
|
||||
<img src="figures/HubUser3_NewFile.PNG" alt="Example Image" width="500">
|
||||
</figure>
|
||||
|
||||
3. In the new window, you can start typing your content. Give your file a name and make sure to use the markdown extension: `Chapter1.md`. Once you are done, commit the new file to the repositery by clicking the green button `Commit changes`.
|
||||
|
||||
<figure align="center">
|
||||
<img src="figures/HubUser3_NewFile2.PNG" alt="Example Image" width="700">
|
||||
</figure>
|
||||
|
||||
4. In case you want to make changes to an existing file, navigate to the file in your remote repositery. Then click the downward pointing arrow on the very left in the top bar. Select the option `Edit in place`.
|
||||
|
||||
<figure align="center">
|
||||
<img src="figures/HubUser3_EditFile.PNG" alt="Example Image" width="700">
|
||||
</figure>
|
||||
|
||||
5. Make your changes in the text editor and when you are ready, commit your changes to the remote repositery by clicking on the green `Commit changes` button.
|
||||
|
||||
<figure align="center">
|
||||
<img src="figures/HubUser3_EditFile2.PNG" alt="Example Image" width="700">
|
||||
</figure>
|
||||
|
||||
6. In case you added a new file, you also need to include it table of contents of your book! The table of contents is specified in a file called `toc.yml` and it is already included in your repositery if you used the teachbooks template.
|
||||
|
||||
<figure align="center">
|
||||
<img src="figures/HubUser3_toc.PNG" alt="Example Image" width="500">
|
||||
</figure>
|
||||
|
||||
You can edit it and commit the changes in the same manner as with markdown (.md) files.
|
||||
````
|
||||
`````
|
||||
|
||||
````````
|
||||
````````{tab-item} ... user type 4
|
||||
````````{tab-item} ... user type 4 ...
|
||||
|
||||
**... for ...**
|
||||
```````{tab-set}
|
||||
``````{tab-item} ... brand new version (branch)
|
||||
``````{tab-item} ... for a 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 ...**
|
||||
**... by (1) making changes on a single or multiple file(s) <br>
|
||||
(2) selecting changes to be added to the Git-timeline (staging) <br>
|
||||
(3) adding changes to the Git-timeline (committing) and <br>
|
||||
(4) adding changes to GitLab/GitHub (pushing) with ...**
|
||||
|
||||
`````{tab-set}
|
||||
````{tab-item} ... Git in VS Code
|
||||
|
||||
1. Make some changes to a file in for example VS Code and save them.
|
||||
|
||||
```{error} To be written
|
||||
```
|
||||
Make some changes in for example VS Code and save them.
|
||||
|
||||
|
||||
Select files ready to be added to Git-timeline (staging)
|
||||
2. Select the 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:
|
||||
|
||||
|
|
@ -62,14 +113,14 @@ 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.
|
||||
|
||||
3. Adding changes to the Git-timeline (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
|
||||
|
||||
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.
|
||||
|
|
@ -81,78 +132,195 @@ After committing, click the 🔄 button to push our changes to the remote reposi
|
|||
````
|
||||
````{tab-item} ... GitHub Desktop
|
||||
|
||||
```{error} To be written
|
||||
```
|
||||
Make some changes in for example VS Code and save them.
|
||||
1. Make some changes to a file 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
|
||||
```
|
||||
2. The staging GitHub Desktop assumes you want to stage all files. These files will show up on the left side bar when you open GitHub Desktop. You can unselect some of them (unstaging them) by clicking on the *check*.
|
||||
|
||||
Add changes to Git-timeline locally (committing)
|
||||
<figure align="center">
|
||||
<img src="figures/Stage_GitHubDekstop.PNG" alt="Example Image" width="400">
|
||||
</figure>
|
||||
|
||||
```{error} To be written
|
||||
```
|
||||
3. Add changes to Git-timeline locally (committing). In the field that says `Summary(Required)`, write a short description of the changes you have made. This message is what is called the *Commit Message*. After we've done this, click the blue button `Commit to Repositery`.
|
||||
|
||||
Add changes to GitHub/GitLab (pushing)
|
||||
4. Now we need to add changes to GitHub/GitLab. This is called pushing to the local repositery. After committing, the following screen will pop up. Click on `Push Origin`.
|
||||
|
||||
```{error} To be written
|
||||
```
|
||||
<figure align="center">
|
||||
<img src="figures/Push_GitHubDesktop.PNG" alt="Example Image" width="650">
|
||||
</figure>
|
||||
|
||||
Alternatively, you can also click on `Push origin` in the top bar.
|
||||
|
||||
<figure align="center">
|
||||
<img src="figures/Push_GitHubDesktop2.PNG" alt="Example Image" width="650">
|
||||
</figure>
|
||||
````
|
||||
`````
|
||||
``````
|
||||
|
||||
``````{tab-item} ... existing version (branch)
|
||||
``````{tab-item} ... for an 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 ...**
|
||||
**... by (1) regularly obtaining updates from colleagues from GitLab/GitHub (pulling), <br>
|
||||
(2) solving potential incompatible changes (merging conflicts), <br>
|
||||
(3) making changes on a single / multiple file(s), <br>
|
||||
(4) selecting changes to be added to the Git-timeline (staging), <br>
|
||||
(5) adding those to the Git-timeline (committing) and <br>
|
||||
(6) adding 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)**
|
||||
1. If you collaborate with colleagues on your branch, you can get the updates from your colleagues as well by pulling from GitLab/GitHub. This synchronizes the remote repositery with your local repositery on your machine. On the left side-bar click on the icon that looks like a branch.
|
||||
|
||||
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?
|
||||
<figure align="center">
|
||||
<img src="figures/VSCode_Pull.PNG" alt="Example Image" width="650">
|
||||
</figure>
|
||||
|
||||
```{error} To be written
|
||||
By clicking on the 🔄 button, you will pull your colleages' changes.
|
||||
|
||||
2. When multiple people work on one chapter, it is possible that conflicts will arise if you and your colleagues have made incompatible changes in the same branch. In that case, when pulling from the remote repositery, Git in VS Code will recognize conflicts and help you to solve potential incompatible changes (merging conflicts). Open the files that are marked as conflicitng.
|
||||
|
||||
<figure align="center">
|
||||
<img src="figures/Conflicts2.PNG" alt="Example Image" width="650">
|
||||
</figure>
|
||||
|
||||
The figure above shows the conflicts. If you look closely you can see that the last couple of words of the paragraph are different in the main branch than in the branch we were working in. There are a couple of options in the top bar:
|
||||
|
||||
- `Accept Current Change` will keep the change in your branch
|
||||
- `Accept Incoming Change` will keep the change from the main branch (the branch you are merging into your branch)
|
||||
- `Accept Both Changes` will retain both paragraphs
|
||||
|
||||
Choose one of the options to resolve the merge conflict. You now have updated your work with work from your colleagues and resolved potential conlicts. You are now ready to continue working on the content.
|
||||
|
||||
3. Make some further changes to a file in for example VS Code and save them.
|
||||
|
||||
4. Select the 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.
|
||||
|
||||
5. Adding changes to the Git-timeline (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
|
||||
|
||||
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
|
||||
|
||||
text..
|
||||
```{error} To be written
|
||||
```
|
||||
1. If you collaborate with colleagues on your branch, you can get the updates from your colleagues as well by pulling from GitLab/GitHub. This synchronizes the remote repositery with your local repositery on your machine. Click on `Fetch` in the top bar. Then on the same place, click on 'Pull'.
|
||||
|
||||
<figure align="center">
|
||||
<img src="figures/Fetch.PNG" alt="Example Image" width="650">
|
||||
</figure>
|
||||
|
||||
2. When multiple people work on one chapter, it is possible that conflicts will arise if you and your colleagues have made incompatible changes in the same branch. In that case, when pulling from the remote repositery, GitHub Desktop will recognize conflicts and help you to solve potential incompatible changes (merging conflicts).
|
||||
|
||||
<figure align="center">
|
||||
<img src="figures/Conflicts1.PNG" alt="Example Image" width="650">
|
||||
</figure>
|
||||
|
||||
In this case there are two conflicted files. GitHub Desktop is suggesting to resolve the changes in VS Code. Click on `Open in Visual Studio Code`.
|
||||
|
||||
<figure align="center">
|
||||
<img src="figures/Conflicts2.PNG" alt="Example Image" width="650">
|
||||
</figure>
|
||||
|
||||
The figure above shows the conflicts. If you look closely you can see that the last couple of words of the paragraph are different in the main branch than in the branch we were working in. There are a couple of options in the top bar:
|
||||
|
||||
- `Accept Current Change` will keep the change in your branch
|
||||
- `Accept Incoming Change` will keep the change from the main branch (the branch you are merging into your branch)
|
||||
- `Accept Both Changes` will retain both paragraphs
|
||||
|
||||
Choose one of the options to resolve the merge conflict. You now have updated your work with work from your colleagues and resolved potential conlicts. You are now ready to continue working on the content.
|
||||
|
||||
3. Make some further changes to a file in for example VS Code and save them.
|
||||
|
||||
4. The staging GitHub Desktop assumes you want to stage all files. These files will show up on the left side bar when you open GitHub Desktop. You can unselect some of them (unstaging them) by clicking on the *check*.
|
||||
|
||||
<figure align="center">
|
||||
<img src="figures/Stage_GitHubDekstop.PNG" alt="Example Image" width="400">
|
||||
</figure>
|
||||
|
||||
5. Add changes to Git-timeline locally (committing). In the field that says `Summary(Required)`, write a short description of the changes you have made. This message is what is called the *Commit Message*. After we've done this, click the blue button `Commit to Repositery`.
|
||||
|
||||
6. Now we need to add changes to GitHub/GitLab. This is called pushing to the local repositery. After committing, the following screen will pop up. Click on `Push Origin`.
|
||||
|
||||
<figure align="center">
|
||||
<img src="figures/Push_GitHubDesktop.PNG" alt="Example Image" width="650">
|
||||
</figure>
|
||||
|
||||
Alternatively, you can also click on `Push origin` in the top bar.
|
||||
|
||||
<figure align="center">
|
||||
<img src="figures/Push_GitHubDesktop2.PNG" alt="Example Image" width="650">
|
||||
</figure>
|
||||
|
||||
````
|
||||
`````
|
||||
|
||||
|
||||
``````
|
||||
```````
|
||||
|
||||
````````
|
||||
|
||||
````````{tab-item} User type 5
|
||||
|
||||
````````{tab-item} ... User type 5 ...
|
||||
|
||||
```````{tab-set}
|
||||
``````{tab-item} ... brand new version (branch)
|
||||
``````{tab-item} ... for 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 ...**
|
||||
**... by (1) making changes on a single or multiple file(s) <br>
|
||||
(2) checking changes locally, <br>
|
||||
(3) selecting changes to be added to the Git-timeline (staging) <br>
|
||||
(4) adding changes to the Git-timeline (committing) and <br>
|
||||
(5) adding changes to GitLab/GitHub (pushing) with ...**
|
||||
|
||||
`````{tab-set}
|
||||
````{tab-item} ... Git in VS Code
|
||||
|
||||
1. Make some changes to a file in for example VS Code and save them.
|
||||
|
||||
```{error} To be written
|
||||
2. Once all the changes are made, it can be useful to check the changes locally on your device in order to see how it will look on the website. If all the required environments and packages are downloaded, checking changes locally is fairly easy!
|
||||
|
||||
Navigate to the terminal in VS code, located at the bottom of the window or by clicking on `Terminal` in the top bar.
|
||||
You will firstly need to actiavte the right environment. Type the following command:
|
||||
|
||||
`conda activate jupyter-book-env`
|
||||
|
||||
(or the environment in which you have installed the TeachBooks package)
|
||||
|
||||
Then we can build the book locally. Make sure you are in the right repositery in VS code and type the folloing command:
|
||||
|
||||
`jupyter-book build book`
|
||||
|
||||
Where book is the name of the folder containing all the files that make up your book. After `jupyter-book` is done running you will get the following:
|
||||
|
||||
```{figure} ../figures/buildbook.PNG
|
||||
|
||||
Output.
|
||||
```
|
||||
Make some changes in for example VS Code and save them.
|
||||
Paste the last line into your browser to see the updated changes.
|
||||
|
||||
build book locally and eventually startup python server...
|
||||
```{error} To be written
|
||||
```
|
||||
```{Note}
|
||||
|
||||
Select files ready to be added to Git-timeline (staging)
|
||||
Sometimes there are problems building the book. It could be that the building requires extensions that are not present in your environment. To prevent issues, make sure to update your environment by routinely updating your packages. You can do this by executing the following line in your environment in the command line.
|
||||
|
||||
`pip install -r requirements.txt --upgrade`
|
||||
|
||||
```jup
|
||||
3. If you are satisfied with your changes, you can select the 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:
|
||||
|
||||
|
|
@ -163,14 +331,14 @@ 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.
|
||||
|
||||
4. Adding changes to the Git-timeline (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
|
||||
|
||||
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.
|
||||
|
|
@ -179,34 +347,59 @@ 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.
|
||||
|
||||
```{Error}
|
||||
|
||||
5. startup python server...
|
||||
|
||||
````
|
||||
|
||||
````{tab-item} ... GitHub Desktop
|
||||
|
||||
```{error} To be written
|
||||
```
|
||||
Make some changes in for example VS Code and save them.
|
||||
1. Obtain updates from colleagues from GitLab/GitHub (pulling). This synchronizes the remote repositery with your local repositery on your machine. Click on `Fetch` in the top bar. Then on the same place, click on 'Pull'.
|
||||
|
||||
The staging GitHub Desktop assumes you want to stage all files. You can unselect some of them (unstaging them)...
|
||||
```{error} To be written
|
||||
```
|
||||
<figure align="center">
|
||||
<img src="figures/Fetch.PNG" alt="Example Image" width="650">
|
||||
</figure>
|
||||
|
||||
Add changes to Git-timeline locally (committing)
|
||||
2. When multiple people work on one chapter, it is possible that conflicts will arise. This means that two users might have cheanged the same sections. GitHub Desktop will recognize this Solve potential incompatible changes (merging conflicts)
|
||||
|
||||
```{error} To be written
|
||||
```
|
||||
3. Make some changes to a file in for example VS Code and save them.
|
||||
|
||||
Add changes to GitHub/GitLab (pushing)
|
||||
4. The staging GitHub Desktop assumes you want to stage all files. These files will show up on the left side bar when you open GitHub Desktop. You can unselect some of them (unstaging them) by clicking on the *check*.
|
||||
|
||||
```{error} To be written
|
||||
```
|
||||
<figure align="center">
|
||||
<img src="figures/Stage_GitHubDekstop.PNG" alt="Example Image" width="400">
|
||||
</figure>
|
||||
|
||||
5. Add changes to Git-timeline locally (committing). In the field that says `Summary(Required)`, write a short description of the changes you have made. This message is what is called the *Commit Message*. After we've done this, click the blue button `Commit to Repositery`.
|
||||
|
||||
6. Now we need to add changes to GitHub/GitLab. This is called pushing to the local repositery. After committing, the following screen will pop up. Click on `Push Origin`.
|
||||
|
||||
<figure align="center">
|
||||
<img src="figures/Push_GitHubDesktop.PNG" alt="Example Image" width="650">
|
||||
</figure>
|
||||
|
||||
Alternatively, you can also click on `Push origin` in the top bar.
|
||||
|
||||
<figure align="center">
|
||||
<img src="figures/Push_GitHubDesktop2.PNG" alt="Example Image" width="650">
|
||||
</figure>
|
||||
|
||||
Python stuff?
|
||||
|
||||
````
|
||||
`````
|
||||
``````
|
||||
|
||||
``````{tab-item} ... existing version (branch)
|
||||
``````{tab-item} ... for an 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 ...**
|
||||
**... by (1) regularly obtaining updates from colleagues from GitLab/GitHub (pulling), <br>
|
||||
(2) solving potential incompatible changes (merging conflicts), <br>
|
||||
(3) making changes on a single / multiple file(s), <br>
|
||||
(4) checking changes locally, <br>
|
||||
(5) selecting changes to be added to the Git-timeline (staging), <br>
|
||||
(6) adding those to the Git-timeline (committing) and <br>
|
||||
(7) adding changes to GitLab/GitHub (pushing) with ...**
|
||||
|
||||
`````{tab-set}
|
||||
````{tab-item} ... Git in VS Code
|
||||
|
|
@ -224,15 +417,8 @@ text..
|
|||
```{error} To be written
|
||||
```
|
||||
````
|
||||
|
||||
`````
|
||||
|
||||
|
||||
``````
|
||||
```````
|
||||
|
||||
|
||||
|
||||
````````
|
||||
|
||||
`````````
|
||||
BIN
book/workflows/figures/CheckOutBranch_GitHubDesktop.PNG
Normal file
BIN
book/workflows/figures/CheckOutBranch_GitHubDesktop.PNG
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 31 KiB |
BIN
book/workflows/figures/CheckOutBranch_GitHubDesktop2.PNG
Normal file
BIN
book/workflows/figures/CheckOutBranch_GitHubDesktop2.PNG
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 20 KiB |
BIN
book/workflows/figures/CloneGitHubDesktop.PNG
Normal file
BIN
book/workflows/figures/CloneGitHubDesktop.PNG
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 16 KiB |
BIN
book/workflows/figures/CloneRepo_Githubdesk.png
Normal file
BIN
book/workflows/figures/CloneRepo_Githubdesk.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 14 KiB |
BIN
book/workflows/figures/CloneRepo_TroughGithubdesk.PNG
Normal file
BIN
book/workflows/figures/CloneRepo_TroughGithubdesk.PNG
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 19 KiB |
BIN
book/workflows/figures/Clone_GitHub.PNG
Normal file
BIN
book/workflows/figures/Clone_GitHub.PNG
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 38 KiB |
BIN
book/workflows/figures/Conflicts1.PNG
Normal file
BIN
book/workflows/figures/Conflicts1.PNG
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 20 KiB |
BIN
book/workflows/figures/Conflicts2.PNG
Normal file
BIN
book/workflows/figures/Conflicts2.PNG
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 38 KiB |
BIN
book/workflows/figures/Fetch.PNG
Normal file
BIN
book/workflows/figures/Fetch.PNG
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 27 KiB |
BIN
book/workflows/figures/GitHubPages.PNG
Normal file
BIN
book/workflows/figures/GitHubPages.PNG
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 75 KiB |
BIN
book/workflows/figures/HubUser3_EditFile.PNG
Normal file
BIN
book/workflows/figures/HubUser3_EditFile.PNG
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 38 KiB |
BIN
book/workflows/figures/HubUser3_EditFile2.PNG
Normal file
BIN
book/workflows/figures/HubUser3_EditFile2.PNG
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 23 KiB |
BIN
book/workflows/figures/HubUser3_NewFile.PNG
Normal file
BIN
book/workflows/figures/HubUser3_NewFile.PNG
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 22 KiB |
BIN
book/workflows/figures/HubUser3_NewFile2.PNG
Normal file
BIN
book/workflows/figures/HubUser3_NewFile2.PNG
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 11 KiB |
BIN
book/workflows/figures/HubUser3_toc.PNG
Normal file
BIN
book/workflows/figures/HubUser3_toc.PNG
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 41 KiB |
BIN
book/workflows/figures/Issue_GitHub.PNG
Normal file
BIN
book/workflows/figures/Issue_GitHub.PNG
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 50 KiB |
BIN
book/workflows/figures/NewBranch_GitHub.PNG
Normal file
BIN
book/workflows/figures/NewBranch_GitHub.PNG
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 30 KiB |
BIN
book/workflows/figures/NewBranch_GitHub2.PNG
Normal file
BIN
book/workflows/figures/NewBranch_GitHub2.PNG
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 21 KiB |
BIN
book/workflows/figures/NewBranch_GitHub3.PNG
Normal file
BIN
book/workflows/figures/NewBranch_GitHub3.PNG
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 24 KiB |
BIN
book/workflows/figures/New_Issue_GitHub.PNG
Normal file
BIN
book/workflows/figures/New_Issue_GitHub.PNG
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 35 KiB |
BIN
book/workflows/figures/New_Issue_GitHub2.PNG
Normal file
BIN
book/workflows/figures/New_Issue_GitHub2.PNG
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 47 KiB |
BIN
book/workflows/figures/Pull_VS.PNG
Normal file
BIN
book/workflows/figures/Pull_VS.PNG
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 14 KiB |
BIN
book/workflows/figures/Push_GitHubDesktop.PNG
Normal file
BIN
book/workflows/figures/Push_GitHubDesktop.PNG
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 9.8 KiB |
BIN
book/workflows/figures/Push_GitHubDesktop2.PNG
Normal file
BIN
book/workflows/figures/Push_GitHubDesktop2.PNG
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 12 KiB |
BIN
book/workflows/figures/Stage_GitHubDekstop.PNG
Normal file
BIN
book/workflows/figures/Stage_GitHubDekstop.PNG
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 11 KiB |
BIN
book/workflows/figures/User3_EditFile.PNG
Normal file
BIN
book/workflows/figures/User3_EditFile.PNG
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 44 KiB |
BIN
book/workflows/figures/User3_EditFile2.PNG
Normal file
BIN
book/workflows/figures/User3_EditFile2.PNG
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 92 KiB |
BIN
book/workflows/figures/User3_NewFile.PNG
Normal file
BIN
book/workflows/figures/User3_NewFile.PNG
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 19 KiB |
BIN
book/workflows/figures/User3_NewFile2.PNG
Normal file
BIN
book/workflows/figures/User3_NewFile2.PNG
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 19 KiB |
BIN
book/workflows/figures/User3_toc.PNG
Normal file
BIN
book/workflows/figures/User3_toc.PNG
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 50 KiB |
BIN
book/workflows/figures/VSCode_Pull.PNG
Normal file
BIN
book/workflows/figures/VSCode_Pull.PNG
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 26 KiB |
BIN
book/workflows/figures/buildbook.PNG
Normal file
BIN
book/workflows/figures/buildbook.PNG
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 14 KiB |
|
|
@ -16,11 +16,12 @@ Every team member can create issues when they think of a task that would improve
|
|||
`````{tab-set}
|
||||
````{tab-item} ... GitLab
|
||||
|
||||
The issues in GitLab can be found on this page:
|
||||
The issues in GitLab can be found in your repositery in the left bar.
|
||||
|
||||
|
||||
|
||||
You can create an issue by clicking on the blue `New Issue` button in the top right corner.
|
||||
You can create an issue by clicking on the blue `New Issue` button in the top right corner. <br>
|
||||
This will lead you to this window where you can specify all attributes we mentioned before!
|
||||
|
||||
|
||||
|
||||
|
|
@ -28,9 +29,17 @@ You can create an issue by clicking on the blue `New Issue` button in the top ri
|
|||
|
||||
````{tab-item} ... GitHub
|
||||
|
||||
```{error} To be written
|
||||
```
|
||||
The issues in GitHub can be found in your repositery in the top bar.
|
||||
|
||||
<img src="figures/Issue_GitHub.png" alt="New Issue" width="1000" style="display:block; margin-left:auto; margin-right:auto;"> <br>
|
||||
|
||||
Clicking on `Issues` will open up the page with all the issues on this repositery.
|
||||
|
||||
<img src="figures/New_Issue_GitHub.png" alt="New Issue" width="1000" style="display:block; margin-left:auto; margin-right:auto;"> <br>
|
||||
|
||||
Finally, by clicking the green `New Issue` button you can create a new issue and specify all the attributes we mentioned before!
|
||||
|
||||
<img src="figures/New_Issue_GitHub2.png" alt="New Issue" width="1000" style="display:block; margin-left:auto; margin-right:auto;"> <br>
|
||||
````
|
||||
`````
|
||||
|
||||
|
|
|
|||
79
book/workflows/repositories.md
Normal file
79
book/workflows/repositories.md
Normal file
|
|
@ -0,0 +1,79 @@
|
|||
# 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`.
|
||||
|
||||
If you'd like to work on your book locally (on your device, perhaps using Jupyter Lab or VS Code), you need to clone your repositery from the remote to your device. In familiar words, this means you need to make a copy of your book on your laptop.
|
||||
|
||||
### Cloning a repository
|
||||
|
||||
You can clone a repositery from GitLab and GitHub using GitHub Desktop or you can clone it with Git in VS Code.
|
||||
|
||||
`````{tab-set}
|
||||
````{tab-item} Clone from GitLab using GitHub Desktop
|
||||
|
||||
1. On GitLab, go to the repository of your book. Click on the blue button that says "Clone" or "Code", and copy the link under "Clone with SSH".
|
||||
|
||||
```{figure} ../images/gitlab-clone.png
|
||||
:name: gitlab-clone
|
||||
|
||||
The cloning menu.
|
||||
```
|
||||
2. Navigate to GitHub Desktop (which you've previously installed using [this tutorial](/book/installation-and-setup/git-setup_local.md)).
|
||||
|
||||
3. Click on `File` in the top menu.
|
||||
4. Click on `Clone Repositery`. You should see the following window appear.
|
||||
|
||||
```{figure} ../figures/CloneGitHubDesktop.png
|
||||
:name: CloneGitHubDesktop
|
||||
|
||||
Cloning in GitHub Desktop.
|
||||
```
|
||||
5. Paste the link you've just copied and define the location on your device.
|
||||
````
|
||||
|
||||
````{tab-item} Clone from GitLab using GitHub Desktop
|
||||
1. On GitLab, go to the repository of your book. Click on the blue button that says "Clone" ({numref}`gitlab-clone`), and copy the link under "Clone with SSH".
|
||||
|
||||
```{figure} ../images/gitlab-clone.png
|
||||
:name: gitlab-clone
|
||||
|
||||
The cloning menu.
|
||||
```
|
||||
2. Navigate to GitHub Desktop (which you've previously installed using [this tutorial](/book/installation-and-setup/git-setup_local.md)).
|
||||
|
||||
3. Click on `File` in the top menu.
|
||||
4. Click on `Clone Repositery`. You should see the following window appear.
|
||||
|
||||
```{figure} ../figures/CloneGitHubDesktop.png
|
||||
:name: CloneGitHubDesktop
|
||||
|
||||
Cloning in GitHub Desktop.
|
||||
```
|
||||
5. Paste the link you've just copied and define the location on your device.
|
||||
````
|
||||
|
||||
````{tab-item} Cloning repository with Git in VS Code
|
||||
...
|
||||
````
|
||||
`````
|
||||
|
||||
Now that we've obtained the source, we can set up the files locally:
|
||||
|
||||
`````{tab-set}
|
||||
````{tab-item} Cloning repository with Git in VS Code
|
||||
2. Open a new VS Code window. You should be greeted with a welcome page ({numref}`vscode-welcome`). On this page, click "Clone Git Repository". Alternatively, open the Source Control menu from the left side bar, and click on "Clone Repository".
|
||||
|
||||
```{figure} ../images/vscode-welcome.png
|
||||
:name: vscode-welcome
|
||||
|
||||
The VS Code welcome screen.
|
||||
```
|
||||
|
||||
3. On the top of your screen, you should get a prompt asking you for a URL. In this field, paste the link you copied from GitLab and press enter. It will ask you to choose the location of the repository. After you've chosen a location, a final prompt will show up asking if you want to open the repository. Click on "Open".
|
||||
|
||||
4. You now have a local copy of the repository.
|
||||
````
|
||||
|
||||
````{tab-item} Cloning repository with GitHub Desktop
|
||||
....
|
||||
````
|
||||
`````
|
||||
Loading…
Add table
Add a link
Reference in a new issue