mirror of
https://github.com/TeachBooks/manual.git
synced 2026-11-13 06:45:52 +00:00
Merge branch 'main' into CollaborationGit
This commit is contained in:
Julie Kirsch
commit
afff3710eb
23 changed files with 245 additions and 243 deletions
|
|
@ -80,19 +80,15 @@ Tip: It makes sense to give the branch a name related to the content you will be
|
|||
|
||||
As user type 4 and 5, you make changes to the book locally on your computer rather than online on GitLab/GitHub. This allows you to create more complex and interactive sections to your book. Before you can start, there are a few preparatory steps you need to take.
|
||||
|
||||
**Cloning**
|
||||
In order to create your own version, you will first have to open the repository. Then, you will need to clone the repository to your computer. This procedure is called cloning.
|
||||
|
||||
In order to create your own version, you will first have to open the repositery. Then, you will need to clone the repositery to your computer. This procedure is called cloning.
|
||||
|
||||
**Branching**
|
||||
|
||||
If your repositery is already cloned on your computer, you are almost ready to start editing the book. However, remember that you are most likely not the only person making changes to the book. To keep an overview of the changes made by you and your colleages, it is important that changes are first made in a 'copy' of the book and are then merged into the final version. This is done through branching! You can create your version of the book by creating a new version (branch) or you can continue the work in an existing version (checkout branch).
|
||||
If your repository is already cloned on your computer, you are almost ready to start editing the book. However, remember that you are most likely not the only person making changes to the book. To keep an overview of the changes made by you and your colleages, it is important that changes are first made in a 'copy' of the book and are then merged into the final version. This is done through branching! You can create your version of the book by creating a new version (branch) or you can continue the work in an existing version (checkout branch).
|
||||
|
||||
`````````{tab-set}
|
||||
|
||||
````````{tab-item} Cloning
|
||||
````````{tab-item} ... when opening repository for first time…
|
||||
|
||||
**1. Open the repository locally using ...**
|
||||
**(a) ... by finding the repository url from ...**
|
||||
|
||||
```````{tab-set}
|
||||
|
||||
|
|
@ -146,7 +142,7 @@ You have now directly cloned the repository, so you can skip the next step!
|
|||
``````
|
||||
```````
|
||||
|
||||
**2. Clone the local repositery with ...**
|
||||
**(b) ... and opening (cloning) the local repository with ...**
|
||||
|
||||
```````{tab-set}
|
||||
``````{tab-item} ... VS Code
|
||||
|
|
@ -166,10 +162,10 @@ The VS Code welcome screen.
|
|||
|
||||
``````{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`.
|
||||
1. You have previously copied the link of the repository you would like to clone from GitLab or GitHub. In GitHub Desktop, navigate to the top bar, click on `File` and then on `Clone repository`.
|
||||
|
||||
<figure align="center">
|
||||
<img src="figures/CloneRepo_Githubdesk.PNG" alt="Example Image" width="350">
|
||||
<img src="figures/CloneRepo_Githubdesk.png" alt="Example Image" width="350">
|
||||
</figure>
|
||||
|
||||
2. In the top bar click on `URL`.
|
||||
|
|
@ -184,38 +180,18 @@ The VS Code welcome screen.
|
|||
|
||||
``````
|
||||
```````
|
||||
**You have now cloned the repositery to your computer and you can start branching. <br>
|
||||
**You have now cloned the repository to your computer and you can start branching. <br>
|
||||
Have a look at the other section!**
|
||||
````````
|
||||
|
||||
````````{tab-item} Branching
|
||||
````````{tab-item} ... when working in previously opened repository…
|
||||
|
||||
**I want to... <br>
|
||||
(a) update my repository (pulling) and <br>
|
||||
(b) create my own version (branching) or select an existing version (checkout branch) using ...**
|
||||
**(a) by creating my own version (branching) or select an existing version (checkout branch) ...**
|
||||
|
||||
```````{tab-set}
|
||||
``````{tab-item} ... Git in VS Code
|
||||
|
||||
**1. Update your repositery**
|
||||
|
||||
Since you are working in a repositery with multiple colleagues, it is good practice to make sure your local repositery is up to date before you start branching. This is especially important when you want to work in an existing branch. In that case you want to make sure that the existing branch shows in your local repositery. Therefore, you first need to pull all the changes from the remote repositery to your local repositery. Simply click the Icon with the two arrows.
|
||||
|
||||
```{figure} ../figures/Pull_VS.png
|
||||
:name: Pull_VS
|
||||
|
||||
Location of the branch menu.
|
||||
```
|
||||
Once your local repositery is up to date you can start to work either in a new branch (new version) or in an existing branch (exisiting version).
|
||||
|
||||
**2. Create your own version by creating a new branch**
|
||||
|
||||
Although it is possible to create new branches in VS Code directly, creating new branches on the remote repositery (on GitLab or GitHub) is better for collaborating because the new branch becomes immediately visible to everyone working in the repositery as opposed to becoming visible after being pushed to the remote repositery.
|
||||
|
||||
Create a new branch in...
|
||||
Although it is possible to create new branches in VS Code directly, creating new branches on the remote repository (on GitLab or GitHub) is better for collaborating because the new branch becomes immediately visible to everyone working in the repository as opposed to becoming visible after being pushed to the remote repository.
|
||||
|
||||
`````{tab-set}
|
||||
````{tab-item} ... GitLab
|
||||
````{tab-item} ... in GitLab
|
||||
|
||||
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".
|
||||
|
||||
|
|
@ -240,10 +216,7 @@ We're making a new branch called `chapter-2` from the `main` branch.
|
|||
|
||||
The circled menu is the branch selection menu.
|
||||
```
|
||||
|
||||
You have now created a new branch on the remote, make sure to fetch & pull again to see it on the local repositery!
|
||||
````
|
||||
|
||||
````{tab-item} ... GitHub
|
||||
|
||||
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`.
|
||||
|
|
@ -271,11 +244,15 @@ Tip: It makes sense to give the branch a name related to the content you will be
|
|||
<img src="figures/NewBranch_GitHub4.PNG" alt="Example Image" width="650">
|
||||
</figure>
|
||||
|
||||
5. jupYou have now created a new branch on the remote, make sure to fetch & pull again to see it on the local repositery!
|
||||
````
|
||||
`````
|
||||
|
||||
**3. Work in an existing branch**
|
||||
**(b) and updating my local repository (checking out and pulling) ...**
|
||||
|
||||
```````{tab-set}
|
||||
``````{tab-item} ... with Git in VS Code
|
||||
|
||||
1. Open own version (checking out)
|
||||
|
||||
If you want to work in an existing branch you need 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.
|
||||
|
||||
|
|
@ -294,91 +271,25 @@ Location of the branch 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.
|
||||
```
|
||||
|
||||
2. Update your local repository
|
||||
|
||||
Since you are working in a repository with multiple colleagues, it is good practice to make sure your local repository is up to date. This is especially important when you want to work in an existing branch. In that case you want to make sure that the existing branch shows in your local repository. Therefore, you first need to pull all the changes from the remote repository to your local repository. Simply click the Icon with the two arrows.
|
||||
|
||||
```{figure} ../figures/Pull_VS.PNG
|
||||
:name: Pull_VS
|
||||
|
||||
Location of the branch menu.
|
||||
```
|
||||
|
||||
``````
|
||||
``````{tab-item} ... GitHub Desktop
|
||||
``````{tab-item} ... with GitHub Desktop
|
||||
|
||||
**1. Update your repositery**
|
||||
|
||||
Since you are working in a repositery with multiple colleagues, it is good practice to make sure your local repositery is up to date before you start branching. This is especially important when you want to work in an existing branch. In that case you want to make sure that the existing branch shows in your local repositery. Therefore, you first need to pull all the changes from the remote repositery to your local repositery.
|
||||
|
||||
This synchronizes the remote repositery with your local repositery on your computer. 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. Create your own version by creating a new branch.**
|
||||
|
||||
Although it is possible to create new branches in GitHub Desktop directly, creating new branches on the remote repositery (on GitLab or GitHub) is better for collaborating because the new branch becomes immediately visible to everyone working in the repositery as opposed to becoming visible after being pushed to the remote repositery.
|
||||
|
||||
Create a new branch in...
|
||||
|
||||
`````{tab-set}
|
||||
````{tab-item} ... GitLab
|
||||
|
||||
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
|
||||
|
||||
Click the highlighted button to make a new branch.
|
||||
```
|
||||
|
||||
2. A new page opens ({numref}`new-branch-menu`), on which you can specify the name of your branch and the source branch. Try to think of a good name for your branch. For example, `chapter-2` is a suitable name if we're going to be working on Chapter 2 of our book. After you've made sure that the selected source branch is correct, click "Create branch".
|
||||
|
||||
```{figure} ../images/gitlab-branch-name.png
|
||||
:name: new-branch-menu
|
||||
|
||||
We're making a new branch called `chapter-2` from the `main` branch.
|
||||
```
|
||||
|
||||
3. You should be sent back to an overview page of your repository. In the branch selection menu (see {numref}`new-branch-repo`), it should now say `chapter-2` instead of `main`.
|
||||
|
||||
```{figure} ../images/gitlab-new-branch-repo.png
|
||||
:name: new-branch-repo
|
||||
|
||||
The circled menu is the branch selection menu.
|
||||
```
|
||||
|
||||
You have now created a new branch on the remote, make sure to fetch & pull again to see it on the local repositery!
|
||||
````
|
||||
|
||||
````{tab-item} ... GitHub
|
||||
|
||||
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 align="center">
|
||||
<img src="figures/NewBranch_GitHub.PNG" alt="Example Image" width="650">
|
||||
</figure>
|
||||
|
||||
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 align="center">
|
||||
<img src="figures/NewBranch_GitHub2.PNG" alt="Example Image" width="650">
|
||||
</figure>
|
||||
|
||||
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 align="center">
|
||||
<img src="figures/NewBranch_GitHub3.PNG" alt="Example Image" width="350">
|
||||
</figure>
|
||||
|
||||
4. You will find your new branch in the drop down menu as seen on the figure below. You can then select your new branch and start working in it (new version).
|
||||
|
||||
<figure align="center">
|
||||
<img src="figures/NewBranch_GitHub4.PNG" alt="Example Image" width="650">
|
||||
</figure>
|
||||
|
||||
5. You have now created a new branch on the remote, make sure to fetch & pull again to see it on the local repositery!
|
||||
````
|
||||
`````
|
||||
|
||||
**3. Work in an existing branch**
|
||||
1. Open own version (checking out)
|
||||
|
||||
The next step is to *check out* our new branch in GitHub Desktop. *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.
|
||||
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 repository.
|
||||
|
||||
```{figure} ../figures/CheckOutBranch_GitHubDesktop.PNG
|
||||
```
|
||||
|
|
@ -390,6 +301,17 @@ Leave your changes (stashed) on your working branch, in this case I was working
|
|||
|
||||
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.
|
||||
|
||||
4. Update your repository**
|
||||
|
||||
Since you are working in a repository with multiple colleagues, it is good practice to make sure your local repository is up to date. This is especially important when you want to work in an existing branch. In that case you want to make sure that the existing branch shows in your local repository. Therefore, you first need to pull all the changes from the remote repository to your local repository.
|
||||
|
||||
This synchronizes the remote repository with your local repository on your computer. 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>
|
||||
|
||||
|
||||
``````
|
||||
```````
|
||||
**Now that you have created and checked out your new branch, you can start {ref}`making and committing changes <stage-commit-push>`.**
|
||||
|
|
|
|||
|
|
@ -12,25 +12,20 @@ Now that you've pushed your changes online, it's time to check the change in the
|
|||
`````{tab-set}
|
||||
````{tab-item} In GitLab
|
||||
|
||||
At the moment this is not possible, but the workflow will soon be the same as for GitHub.
|
||||
At the moment this is not possible.
|
||||
However, what you can do is 'mirror' your GitLab repository to GitHub. This will copy your content automatically (but maximum once every 5 minutes) to GitHub. This allows you to use the TeachBook's GitHub actions.
|
||||
|
||||
Instructions on how to set up mirroring are provided here: https://docs.gitlab.com/ee/user/project/repository/mirror/push.html#set-up-a-push-mirror-from-gitlab-to-github
|
||||
|
||||
````
|
||||
````{tab-item} In GitHub
|
||||
|
||||
1. Enable GitHub Pages on your repositery. Note that if you use the Teachbooks template this is probably already done!
|
||||
Once GitHub Pages is enabled and your book is published, you can view it by visiting the GitHub Pages URL for your repository. A summary can be seen under the <svg aria-hidden="true" height="16" viewBox="0 0 16 16" version="1.1" width="16" data-view-component="true" class="octicon octicon-play UnderlineNav-octicon d-none d-sm-inline"> <path d="M8 0a8 8 0 1 1 0 16A8 8 0 0 1 8 0ZM1.5 8a6.5 6.5 0 1 0 13 0 6.5 6.5 0 0 0-13 0Zm4.879-2.773 4.264 2.559a.25.25 0 0 1 0 .428l-4.264 2.559A.25.25 0 0 1 6 10.559V5.442a.25.25 0 0 1 .379-.215Z"></path></svg>`Actions`- `All workflows` - `call-deploy-book` in GitHub. It shows you a descriptive summary.
|
||||
The summary also provides build error messages, which you might fix in a new commit.
|
||||
|
||||
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).
|
||||
If this is not activated yet, you can do so as describe [here](../external/deploy-book-workflow/README). Here you can also find more information.
|
||||
|
||||
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.
|
||||
|
|
@ -7,7 +7,7 @@ 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.
|
||||
|
||||
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`.
|
||||
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`. If this is the first time you interact with books, you're advise to use `github.com`.
|
||||
|
||||
The steps involved are as follows:
|
||||
|
||||
|
|
@ -26,18 +26,20 @@ The steps involved are as follows:
|
|||
````{tab-item} Open repository for first time...
|
||||
|
||||
**... by <br>
|
||||
(a) opening the repository locally (cloning) and <br>
|
||||
(b) creating your own version (branching) or selecting existing version (checkout branch):**
|
||||
(a) creating your own version (branching)
|
||||
(b) opening the repository locally (cloning) and selecting correct version (checkout branch):**<br>
|
||||
|
||||
- branching
|
||||
- cloning
|
||||
- branching / checkout branch
|
||||
- checkout branch
|
||||
````
|
||||
````{tab-item} Work in previously opened repository...
|
||||
|
||||
**... by <br>
|
||||
(a) updating your repository (pulling) and <br>
|
||||
(b) creating your own version (branching) or select existing version (checkout branch):**
|
||||
|
||||
(a) creating your own version (branching) <br>
|
||||
(b) updating your repository (pulling) and select correct version (checkout branch):**
|
||||
|
||||
- branching
|
||||
- pulling
|
||||
- branching / checkout branch
|
||||
````
|
||||
|
|
@ -126,7 +128,6 @@ The steps involved are as follows:
|
|||
````
|
||||
``````
|
||||
```````
|
||||
4. **Check candles nline**
|
||||
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)**
|
||||
6. **Reviewing (merge request), (eventually repeat steps 3 and 4) and combine (merging) your version with main draft version of book**
|
||||
|
|
@ -11,9 +11,9 @@ Suppose we are writing a new chapter, or are updating an existing chapter for ou
|
|||
`````{tab-set}
|
||||
````{tab-item} ... GitLab
|
||||
|
||||
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!
|
||||
In GitLab, you can directly make changes in the files on the remote repository. You can make changes to the files already in the repository using the text editor but you can also upload new files!
|
||||
|
||||
1. Navigate to the repositery you want to work in.
|
||||
1. Navigate to the repository you want to work in and make sure you're in the correct branch.
|
||||
|
||||
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`.
|
||||
|
||||
|
|
@ -21,25 +21,25 @@ In GitLab, you can directly make changes in the files on the remote repositery.
|
|||
<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`.
|
||||
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 repository 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`.
|
||||
4. In case you want to make changes to an existing file, navigate to the file in your remote repository. 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.
|
||||
5. Make your changes in the text editor and when you are ready, commit your changes to the remote repository 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.
|
||||
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 repository if you used the teachbooks template.
|
||||
|
||||
<figure align="center">
|
||||
<img src="figures/User3_toc.PNG" alt="Example Image" width="500">
|
||||
|
|
@ -49,9 +49,9 @@ You can edit it and commit the changes in the same manner as with markdown (.md)
|
|||
````
|
||||
````{tab-item} ... GitHub
|
||||
|
||||
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!
|
||||
In GitHub, you can directly make changes in the files on the remote repository. You can make changes to the files already in the repository using the text editor but you can also upload new files!
|
||||
|
||||
1. Navigate to the repositery you want to work in.
|
||||
1. Navigate to the repository you want to work in and make sure you're in the correct branch.
|
||||
|
||||
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`.
|
||||
|
||||
|
|
@ -59,25 +59,25 @@ In GitHub, you can directly make changes in the files on the remote repositery.
|
|||
<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`.
|
||||
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 repository 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`.
|
||||
4. In case you want to make changes to an existing file, navigate to the file in your remote repository. 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.
|
||||
5. Make your changes in the text editor and when you are ready, commit your changes to the remote repository 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.
|
||||
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 repository if you used the teachbooks template.
|
||||
|
||||
<figure align="center">
|
||||
<img src="figures/HubUser3_toc.PNG" alt="Example Image" width="500">
|
||||
|
|
@ -92,10 +92,10 @@ You can edit it and commit the changes in the same manner as with markdown (.md)
|
|||
```````{tab-set}
|
||||
``````{tab-item} ... for a brand new version (branch)...
|
||||
|
||||
**... 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 ...**
|
||||
**... by (a) making changes on a single or multiple file(s) <br>
|
||||
(b) selecting changes to be added to the Git-timeline (staging) <br>
|
||||
(c) adding changes to the Git-timeline (committing) and <br>
|
||||
(d) adding changes to GitLab/GitHub (pushing) with ...**
|
||||
|
||||
`````{tab-set}
|
||||
````{tab-item} ... Git in VS Code
|
||||
|
|
@ -123,7 +123,7 @@ 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.
|
||||
4. 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
|
||||
|
||||
|
|
@ -140,9 +140,9 @@ After committing, click the 🔄 button to push our changes to the remote reposi
|
|||
<img src="figures/Stage_GitHubDekstop.PNG" alt="Example Image" width="400">
|
||||
</figure>
|
||||
|
||||
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`.
|
||||
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 repository`.
|
||||
|
||||
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`.
|
||||
4. Now we need to add changes to GitHub/GitLab. This is called pushing to the local repository. 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">
|
||||
|
|
@ -159,17 +159,17 @@ Alternatively, you can also click on `Push origin` in the top bar.
|
|||
|
||||
``````{tab-item} ... for an existing version (branch)...
|
||||
|
||||
**... 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 ...**
|
||||
**... by (a) regularly obtaining updates from colleagues from GitLab/GitHub (pulling), <br>
|
||||
(b) solving potential incompatible changes (merging conflicts), <br>
|
||||
(c) making changes on a single / multiple file(s), <br>
|
||||
(d) selecting changes to be added to the Git-timeline (staging), <br>
|
||||
(e) adding those to the Git-timeline (committing) and <br>
|
||||
(f) adding changes to GitLab/GitHub (pushing) with ...**
|
||||
|
||||
`````{tab-set}
|
||||
````{tab-item} ... Git in VS Code
|
||||
|
||||
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.
|
||||
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 repository with your local repository on your machine. On the left side-bar click on the icon that looks like a branch.
|
||||
|
||||
<figure align="center">
|
||||
<img src="figures/VSCode_Pull.PNG" alt="Example Image" width="400">
|
||||
|
|
@ -177,7 +177,7 @@ Alternatively, you can also click on `Push origin` in the top bar.
|
|||
|
||||
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.
|
||||
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 repository, 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">
|
||||
|
|
@ -214,7 +214,7 @@ 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.
|
||||
6. 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
|
||||
|
||||
|
|
@ -222,19 +222,19 @@ After committing, click the 🔄 button to push our changes to the remote reposi
|
|||
````
|
||||
````{tab-item} ... GitHub Desktop
|
||||
|
||||
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'.
|
||||
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 repository with your local repository 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).
|
||||
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 repository, 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`.
|
||||
In this case there are two conflicted files. GitHub Desktop is suggesting to resolve the changes in VS Code (in that case have a look at the section treating VS Code). By clicking on the small downwards arrow you can also solve the conflict directly in GitHub Desktop by choosing the branch of the file you want to keep.
|
||||
|
||||
<figure align="center">
|
||||
<img src="figures/Conflicts2.PNG" alt="Example Image" width="650">
|
||||
|
|
@ -256,9 +256,9 @@ Choose one of the options to resolve the merge conflict. You now have updated yo
|
|||
<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`.
|
||||
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 repository`.
|
||||
|
||||
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`.
|
||||
6. Now we need to add changes to GitHub/GitLab. This is called pushing to the local repository. 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">
|
||||
|
|
@ -281,11 +281,11 @@ Alternatively, you can also click on `Push origin` in the top bar.
|
|||
```````{tab-set}
|
||||
``````{tab-item} ... for brand new version (branch)
|
||||
|
||||
**... 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 ...**
|
||||
**... by (a) making changes on a single or multiple file(s) <br>
|
||||
(b) checking changes locally, <br>
|
||||
(c) selecting changes to be added to the Git-timeline (staging) <br>
|
||||
(d) adding changes to the Git-timeline (committing) and <br>
|
||||
(e) adding changes to GitLab/GitHub (pushing) with ...**
|
||||
|
||||
`````{tab-set}
|
||||
````{tab-item} ... Git in VS Code
|
||||
|
|
@ -301,7 +301,7 @@ You will firstly need to actiavte the right environment. Type the following comm
|
|||
|
||||
(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:
|
||||
Then we can build the book locally. Make sure you are in the right repository in VS code and type the folloing command:
|
||||
|
||||
`jupyter-book build book`
|
||||
|
||||
|
|
@ -370,7 +370,7 @@ You will firstly need to actiavte the right environment. Type the following comm
|
|||
|
||||
(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:
|
||||
Then we can build the book locally. Make sure you are in the right repository in VS code and type the folloing command:
|
||||
|
||||
`jupyter-book build book`
|
||||
|
||||
|
|
@ -397,9 +397,9 @@ The staging GitHub Desktop assumes you want to stage all files. These files will
|
|||
<img src="figures/Stage_GitHubDekstop.PNG" alt="Example Image" width="400">
|
||||
</figure>
|
||||
|
||||
4. 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`.
|
||||
4. 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 repository`.
|
||||
|
||||
5. 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`.
|
||||
5. Now we need to add changes to GitHub/GitLab. This is called pushing to the local repository. 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">
|
||||
|
|
@ -423,18 +423,18 @@ You can read more about it [here](/book/installation-and-setup/jupyter-book-setu
|
|||
|
||||
``````{tab-item} ... for an existing version (branch)
|
||||
|
||||
**... 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 ...**
|
||||
**... by (a) regularly obtaining updates from colleagues from GitLab/GitHub (pulling), <br>
|
||||
(b) solving potential incompatible changes (merging conflicts), <br>
|
||||
(c) making changes on a single / multiple file(s), <br>
|
||||
(d) checking changes locally, <br>
|
||||
(e) selecting changes to be added to the Git-timeline (staging), <br>
|
||||
(f) adding those to the Git-timeline (committing) and <br>
|
||||
(g) adding changes to GitLab/GitHub (pushing) with ...**
|
||||
|
||||
`````{tab-set}
|
||||
````{tab-item} ... Git in VS Code
|
||||
|
||||
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.
|
||||
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 repository with your local repository on your machine. On the left side-bar click on the icon that looks like a branch.
|
||||
|
||||
<figure align="center">
|
||||
<img src="figures/VSCode_Pull.PNG" alt="Example Image" width="400">
|
||||
|
|
@ -442,7 +442,7 @@ You can read more about it [here](/book/installation-and-setup/jupyter-book-setu
|
|||
|
||||
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.
|
||||
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 repository, 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="600">
|
||||
|
|
@ -467,7 +467,7 @@ You will firstly need to actiavte the right environment. Type the following comm
|
|||
|
||||
(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:
|
||||
Then we can build the book locally. Make sure you are in the right repository in VS code and type the folloing command:
|
||||
|
||||
`jupyter-book build book`
|
||||
|
||||
|
|
@ -514,19 +514,19 @@ After committing, click the 🔄 button to push our changes to the remote reposi
|
|||
````
|
||||
````{tab-item} ... GitHub Desktop
|
||||
|
||||
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'.
|
||||
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 repository with your local repository 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).
|
||||
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 repository, GitHub Desktop will recognize conflicts and help you to solve potential incompatible changes (merging conflicts).
|
||||
|
||||
<figure align="center">
|
||||
<img src="figures/Merge_Conflict_GitHubDesktop2.PNG" alt="Example Image" width="400">
|
||||
</figure>
|
||||
|
||||
In this case there are two conflicted files. GitHub Desktop is suggesting to resolve the changes in VS Code (in that case have a look at the section treating VS Code). By clicking on the small downwards arrow you can also solve the conlict directly in GitHub Dekstop by choosing the branch of the file you want to keep.
|
||||
In this case there are two conflicted files. GitHub Desktop is suggesting to resolve the changes in VS Code (in that case have a look at the section treating VS Code). By clicking on the small downwards arrow you can also solve the conflict directly in GitHub Desktop by choosing the branch of the file you want to keep.
|
||||
|
||||
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.
|
||||
|
||||
|
|
@ -541,7 +541,7 @@ You will firstly need to actiavte the right environment. Type the following comm
|
|||
|
||||
(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:
|
||||
Then we can build the book locally. Make sure you are in the right repository in VS code and type the folloing command:
|
||||
|
||||
`jupyter-book build book`
|
||||
|
||||
|
|
@ -567,9 +567,9 @@ Sometimes there are problems building the book. It could be that the building re
|
|||
<img src="figures/Stage_GitHubDekstop.PNG" alt="Example Image" width="400">
|
||||
</figure>
|
||||
|
||||
6. 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. 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 repository`.
|
||||
|
||||
7. 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`.
|
||||
7. Now we need to add changes to GitHub/GitLab. This is called pushing to the local repository. 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">
|
||||
|
|
|
|||
|
|
@ -51,7 +51,7 @@ In case you have cloned the repositery you can also resolve the conflicts locall
|
|||
|
||||
6. On the page of our merge request ({numref}`gitlab-finished-merge-request`), we're greeted with some more information. On top, you can read the description we just provided when creating the merge request. We can also see an "Approve" button, which you may or may not see, depending on your repository rights. Next, we can see a green checkmark, with a "Merge" button. This is good news: our changes do not conflict with existing files on the `main` branch, and we can merge our changes directly by clicking the button (if applicable: only after somebody else approved the request).
|
||||
|
||||
```{figure} ../images/gitlab-finished-merge-request.png
|
||||
```{figure} ../../images/gitlab-finished-merge-request.png
|
||||
:name: gitlab-finished-merge-request
|
||||
|
||||
The finished merge request.
|
||||
|
|
@ -108,7 +108,7 @@ In case you have cloned the repositery you can also resolve the conflicts locall
|
|||
<img src="figures/Pull_Request6.PNG" alt="Example Image" width="650">
|
||||
</figure>
|
||||
````
|
||||
````{tab-item} Locally with GitHub Desktop
|
||||
````{tab-item} Locally with GitHub Desktop for GitHub repositories
|
||||
hi
|
||||
````
|
||||
`````
|
||||
|
|
|
|||
|
|
@ -1,8 +0,0 @@
|
|||
(publish_students)=
|
||||
# Publish to students
|
||||
|
||||
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`
|
||||
Loading…
Add table
Add a link
Reference in a new issue