mirror of
https://github.com/TeachBooks/manual.git
synced 2026-11-12 22:35:51 +00:00
Merge branch 'main' into publish
This commit is contained in:
Tom van Woudenberg
commit
954d8d68ae
8 changed files with 290 additions and 192 deletions
|
|
@ -6,5 +6,5 @@ This section is useful for user type 5-6.
|
|||
```
|
||||
|
||||
In general, there are two option to include python-enabled interactivity embedded in your book:
|
||||
- Using our [own sphinx-thebe extension](live_code.md) which makes code cells in your `.ipynb` book pages editable and executable by the reader! Opposed to the original sphinx-thebe extensions, our extension runs python in the reader's browser and doesn't rely on an external webserver for the python kernel. We highly recommend this extension as it allows you to use the strength of combining text/figures and code of a jupyter book with interactivity!
|
||||
- Using our [own sphinx-thebe extension](./live_code.md) which makes code cells in your `.ipynb` book pages editable and executable by the reader! Opposed to the original sphinx-thebe extensions, our extension runs python in the reader's browser and doesn't rely on an external webserver for the python kernel. We highly recommend this extension as it allows you to use the strength of combining text/figures and code of a jupyter book with interactivity!
|
||||
- Using [JupyterLite](jupyterlite/jupyterlite.md) to create 'iframe-like' Ipython consoles / jupyterbook / jupyter lab environments in your book. As these 'iframes' are separate modules added to your page, the integration with the other content in your book is less flexible as with our sphinx-thebe extension.
|
||||
|
|
@ -49,11 +49,11 @@ Now everytime you want to work on your jupyter-book, you need to activate the en
|
|||
|
||||
As mentioned before, python packages can be downloaded in the environments you create. Both NumPy and pandas are popular Python packages used for data manipulation and analysis. For the creation of Jupyter Books, we will use the package `jupyter-book`. More information about this package [here](jupyter-book-setup.md).
|
||||
|
||||
### Text-based files
|
||||
### Import environments
|
||||
|
||||
Working on larger projects (with many cool interactive features) may require you to install a lot of python packages. It can be useful to specify the required packages in a text-based file (for example `environment.yml`) and then telling `conda` to create the environment based on the contents of the file!
|
||||
|
||||
Moreover, if you are joining a team that is working on complex projects, it can be useful for you to create a new environment based on use such a text-based file in order to create an up-to-date environment that will give you a flying start. The team might also provide a `requirements.txt` file which specifies all the packages you need to download in order to work on the project. Now it should also become clear why its preferrable to create new environment for each project/book that you work on because they might require you to use different packages!
|
||||
Moreover, if you are joining a team that is working on complex projects, it can be useful for you to create a new environment based on use such a text-based file in order to create an up-to-date environment that will give you a flying start. The team might also provide a `requirements.txt` file which specifies all the packages you need to download in order to work on the project. Now it should also become clear why its preferable to create new environment for each project/book that you work on because they might require you to use different packages!
|
||||
|
||||
Here's an example of what a `requirements.txt` file might look like.
|
||||
|
||||
|
|
@ -95,7 +95,7 @@ You can do this by navigating your command line interface to the folder with `re
|
|||
|
||||
Now you can install the required packages with: `pip install -r requirements.txt`. The TeachBooks team works with these `requirements.txt` files which makes this an essential step in the set-up of your environment!
|
||||
|
||||
### Create an environment from text-based file
|
||||
### Export environment
|
||||
|
||||
If you want to create a file listing the required packages yourself, you can do it by creating a file with the following file extension: the `*.yml` file (pronounced "yah-mul"). It is a text-readable file, that stands for "Yet another Markup Language." This is one of _many_ types of files that use a particular type of text formatting to give a computer specific instructions. It is very similar to the way Markdown formatting works.
|
||||
|
||||
|
|
|
|||
|
|
@ -1,4 +1,4 @@
|
|||
# Create your own version
|
||||
# Create your own version (branching, cloning, pulling)
|
||||
|
||||
Branches are a very useful feature of Git. Branches allow you to work on multiple versions of your codebase simultaneously; you create a copy of your codebase, on which you can work independently of the main codebase. The main branch is the default branch. The content on this branch will be the most up to date version of the book. Therefore, new branches, which are made to add or fix some content in the book, are usually cloned from the main branch. This has many advantages compared to making the edits immediately in the main branch. Some advantages of working with branches are:
|
||||
|
||||
|
|
@ -9,13 +9,15 @@ This systematic workflow guarantees that editing the book goes smoothly.
|
|||
|
||||
The act of making a new branch from an existing one is called *branching*. Usually, you want to branch from the `main` branch, but you can of course also choose to branch from another branch. The branch from which you create a new branch is called the *source* branch.
|
||||
|
||||
`````````{tab-set}
|
||||
````````{tab-item} User type 3
|
||||
**Create your own version by ...**
|
||||
|
||||
**Directly create your own version (branching) or select existing version**
|
||||
`````````{tab-set}
|
||||
````````{tab-item} ... user type 3
|
||||
|
||||
**... by directly creating your own version (branching) or selecting existing version in ...**
|
||||
|
||||
`````{tab-set}
|
||||
````{tab-item} In GitLab
|
||||
````{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".
|
||||
|
||||
```{figure} ../images/gitlab-branch.png
|
||||
|
|
@ -41,7 +43,7 @@ The circled menu is the branch selection menu.
|
|||
```
|
||||
|
||||
````
|
||||
````{tab-item} In GitHub
|
||||
````{tab-item} ... GitHub
|
||||
|
||||
```{error} To be written
|
||||
```
|
||||
|
|
@ -49,15 +51,18 @@ The circled menu is the branch selection menu.
|
|||
`````
|
||||
````````
|
||||
|
||||
````````{tab-item} User type 4 and 5
|
||||
````````{tab-item} ... user type 4 and 5
|
||||
|
||||
|
||||
**... for ...**
|
||||
|
||||
```````{tab-set}
|
||||
``````{tab-item} First time opening (cloning) repository
|
||||
``````{tab-item} ... repository opened for first time
|
||||
|
||||
**Find source link online repository**
|
||||
**... by opening the repository locally (cloning) and creating your own version (branching) or select existing version (checkout branch) from ...**
|
||||
|
||||
`````{tab-set}
|
||||
````{tab-item} From GitLab
|
||||
````{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".
|
||||
|
||||
|
|
@ -68,14 +73,14 @@ The cloning menu.
|
|||
```
|
||||
````
|
||||
|
||||
````{tab-item} From GitHub
|
||||
````{tab-item} ... GitHub
|
||||
|
||||
```{error} To be written
|
||||
```
|
||||
|
||||
````
|
||||
|
||||
````{tab-item} From GitHub using GitHub Desktop
|
||||
````{tab-item} ... GitHub using GitHub Desktop
|
||||
|
||||
```{error} To be written
|
||||
```
|
||||
|
|
@ -83,10 +88,10 @@ The cloning menu.
|
|||
````
|
||||
`````
|
||||
|
||||
**Open repository locally (cloning)**
|
||||
**... with ...**
|
||||
|
||||
`````{tab-set}
|
||||
````{tab-item} With Git in VS Code
|
||||
````{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".
|
||||
|
||||
```{figure} ../images/vscode-welcome.png
|
||||
|
|
@ -98,48 +103,8 @@ 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} With GitHub Desktop
|
||||
```{error} To be written
|
||||
```
|
||||
|
||||
````
|
||||
`````
|
||||
|
||||
``````
|
||||
|
||||
``````{tab-item} Using previously opened (cloned) repository
|
||||
|
||||
**Obtain newest version from online repository (pulling)**
|
||||
|
||||
If you're working on your local version of the repository, you've to make sure you're working on the most up-to-date version of your branch. you can do so by `pull` changes from the remote repository on GitHub / GitLab into your local folder.
|
||||
`````{tab-set}
|
||||
````{tab-item} With Git in VS Code
|
||||
|
||||
```{error} To be written
|
||||
```
|
||||
|
||||
````
|
||||
````{tab-item} With GitHub Desktop
|
||||
|
||||
```{error} To be written
|
||||
```
|
||||
|
||||
````
|
||||
`````
|
||||
``````
|
||||
|
||||
```````
|
||||
**Create your own version (branching)**
|
||||
|
||||
`````{tab-set}
|
||||
````{tab-item} With Git in VS Code
|
||||
|
||||
```{error} To be written
|
||||
```
|
||||
|
||||
4. The final step is to *check out* our new branch in VS Code. *Checking out* means that we're changing our working branch (i.e., the one to which we will be committing our changes) from one to the other. In VS Code, open the branch menu from the bottom left (see {numref}`git-branch-menu-main`). You'll be be greeted with a menu that looks like the one in {numref}`git-branch-selection-menu`. In this menu, we get an overview of the branches of our repository. Notice that our new branch `chapter-2` appears as `origin/chapter-2`, and has a cloud icon in front of it. This means that the branch only exists on the remote repository. Check out the branch by simply clicking on it. Check that the branch is indeed checked out by looking at the branch menu button in the bottom left again; it should now say the name of your branch instead of `main` (in our case `chapter-2`).
|
||||
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
|
||||
|
||||
|
|
@ -150,13 +115,42 @@ 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} With GitHub Desktop
|
||||
|
||||
````{tab-item} ... GitHub Desktop
|
||||
```{error} To be written
|
||||
```
|
||||
|
||||
````
|
||||
`````
|
||||
|
||||
``````
|
||||
|
||||
``````{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
|
||||
```
|
||||
|
||||
````
|
||||
````{tab-item} ... GitHub Desktop
|
||||
|
||||
```{error} To be written
|
||||
```
|
||||
|
||||
````
|
||||
`````
|
||||
``````
|
||||
|
||||
```````
|
||||
|
||||
|
||||
|
||||
````````
|
||||
`````````
|
||||
|
||||
|
|
|
|||
|
|
@ -10,69 +10,83 @@ A jupyter book is composed out of many files which contain the educational conte
|
|||
We have previously introduced the notions of using Git in the online environment (remote) or locally. All the (text, figures, etc.) files that make up the book are contained on the remote repository on GitLab or GitHub. This could be on an open repository on `gitlab.com` or `github.com`. In the context of creating educational books for students at TU Delft, the repository will most likely be located on `gitlab.tudelft.nl` or `github.com/teachbooks`.
|
||||
|
||||
The steps involved are as follows:
|
||||
1. Assign task to yourself
|
||||
2. Create your own version (branching) of the book by:
|
||||
1. **Assign task to yourself (milestones, issues)**
|
||||
2. **Create your own version of the book by**
|
||||
```````{tab-set}
|
||||
``````{tab-item} User type 3
|
||||
- directly create your own version (branching) or select existing version
|
||||
``````{tab-item} ... user type 3
|
||||
**... by directly creating your own version (branching) or selecting existing version:**
|
||||
- branching
|
||||
``````
|
||||
``````{tab-item} User type 4 and 5
|
||||
``````{tab-item} ... user type 4 and 5
|
||||
**... for ...**
|
||||
`````{tab-set}
|
||||
````{tab-item} First time opening (cloning) repository
|
||||
- Find source link online repository
|
||||
- Open repository locally (cloning)
|
||||
- Create your own version (branching) or select existing version (checkout branch)
|
||||
````{tab-item} ... repository opened for first time
|
||||
**... by opening the repository locally (cloning) and creating your own version (branching) or select existing version (checkout branch):**
|
||||
- cloning
|
||||
- branching / checkout branch
|
||||
````
|
||||
````{tab-item} Using previously opened (cloned) repository
|
||||
- Obtain newest version from online repository (pulling)
|
||||
- Create your own version (branching) or select existing version (checkout branch)
|
||||
````{tab-item} ... previously opened repository
|
||||
**... by updating your repository (pulling) and creating your own version (branching) or select existing version (checkout branch):**
|
||||
- pulling
|
||||
- branching / checkout branch
|
||||
````
|
||||
|
||||
`````
|
||||
``````
|
||||
```````
|
||||
3. Edit the book by:
|
||||
3. **Edit the book by ...**
|
||||
```````{tab-set}
|
||||
``````{tab-item} User type 3
|
||||
- Add or make changes to a file
|
||||
- Add changes to Git-timeline (committing)
|
||||
``````{tab-item} ... user type 3
|
||||
**... by directly adding changes on a single file to Git-timeline (committing):**
|
||||
- adding or making changes to single file
|
||||
- committing
|
||||
``````
|
||||
``````{tab-item} User type 4
|
||||
``````{tab-item} ... user type 4
|
||||
... on ...
|
||||
`````{tab-set}
|
||||
````{tab-item} Brand new version (branch)
|
||||
- Add or make changes to file(s)
|
||||
- Select files ready to be added to Git-timeline (staging)
|
||||
- Add changes to Git-timeline locally (committing)
|
||||
- Add changes to GitHub/GitLab (pushing)
|
||||
````{tab-item} ... 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):**
|
||||
- adding or making changes to file(s)
|
||||
- staging
|
||||
- committing
|
||||
- pushing
|
||||
````
|
||||
````{tab-item} Brand new version (branch)
|
||||
- Eventually solve conflicts with combining versions (merge conflicts, emerges after pulling)
|
||||
- Add or make changes to file(s)
|
||||
- Select files ready to be added to Git-timeline (staging)
|
||||
- Add changes to Git-timeline locally (committing)
|
||||
- Add changes to GitHub/GitLab (pushing)
|
||||
````{tab-item} ... 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):**
|
||||
- pulling
|
||||
- solving merge conflicts
|
||||
- adding or making changes to file(s)
|
||||
- staging
|
||||
- committing
|
||||
- pushing
|
||||
````
|
||||
`````
|
||||
``````
|
||||
``````{tab-item} User type 5
|
||||
``````{tab-item} ... user type 5
|
||||
... on ...
|
||||
`````{tab-set}
|
||||
````{tab-item} Brand new version (branch)
|
||||
- Add or make changes to file(s)
|
||||
- Check changes in book locally
|
||||
- Select files ready to be added to Git-timeline (staging)
|
||||
- Add changes to Git-timeline locally (committing)
|
||||
- Add changes to GitHub/GitLab (pushing)
|
||||
````{tab-item} ... brand new version (branch)
|
||||
**... 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):**
|
||||
- adding or making changes to file(s)
|
||||
- checking changes locally
|
||||
- staging
|
||||
- committing
|
||||
- pushing
|
||||
````
|
||||
````{tab-item} Brand new version (branch)
|
||||
- Eventually solve conflicts with combining versions (merge conflicts, emerges after pulling)
|
||||
- Add or make changes to file(s)
|
||||
- Check changes in book locally
|
||||
- Select files ready to be added to Git-timeline (staging)
|
||||
- Add changes to Git-timeline locally (committing)
|
||||
- Add changes to GitHub/GitLab (pushing)
|
||||
````{tab-item} ... 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):**
|
||||
- pulling
|
||||
- solving merge conflicts
|
||||
- adding or making changes to file(s)
|
||||
- checking changes locally
|
||||
- staging
|
||||
- committing
|
||||
- pushing
|
||||
````
|
||||
`````
|
||||
|
||||
``````
|
||||
```````
|
||||
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)
|
||||
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)**
|
||||
|
|
@ -1,11 +1,13 @@
|
|||
# Edit
|
||||
# Edit (merge conflicts, staging, committing, pushing)
|
||||
|
||||
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 ...**
|
||||
`````````{tab-set}
|
||||
````````{tab-item} User type 3
|
||||
|
||||
**Add or make changes to a file**
|
||||
````````{tab-item} ... user type 3
|
||||
**... by directly adding changes on a single file to Git-timeline (committing) in ...**
|
||||
`````{tab-set}
|
||||
````{tab-item} ... GitLab
|
||||
|
||||
Make changes to file in text editor...
|
||||
or add new file by text or upload
|
||||
|
|
@ -13,89 +15,43 @@ or add new file by text or upload
|
|||
```{error} To be written
|
||||
```
|
||||
|
||||
````````
|
||||
````````{tab-item} User type 4 and 5
|
||||
|
||||
```````{tab-set}
|
||||
``````{tab-item} Brand new version (branch)
|
||||
|
||||
If your branch was build from main, you've the most up-to-date version. So you can just continue with the next step. Next time you come here things might be different!
|
||||
``````
|
||||
``````{tab-item} Existing version (branch)
|
||||
|
||||
**Eventually solve conflicts with combining versions (merge conflicts, emerges after pulling)**
|
||||
|
||||
If you collaborate with colleagues on this branch, you can get the updates from your colleagues as well by pulling from GitLab/GitHub. Now your branch is up-to-date. However, this might lead into a merge conflict if you and colleagues have made incompatible changes. How to solve that?
|
||||
|
||||
`````{tab-set}
|
||||
````{tab-item} With Git in VS Code
|
||||
|
||||
click commit in single text editor ...
|
||||
```{error} To be written
|
||||
```
|
||||
|
||||
````
|
||||
````{tab-item} With GitHub Desktop
|
||||
````{tab-item} ... GitHub
|
||||
|
||||
Make changes to file in text editor...
|
||||
or add new file by text or upload
|
||||
|
||||
```{error} To be written
|
||||
```
|
||||
|
||||
click commit in single text editor ...
|
||||
```{error} To be written
|
||||
```
|
||||
````
|
||||
`````
|
||||
|
||||
``````
|
||||
```````
|
||||
````````
|
||||
````````{tab-item} ... user type 4
|
||||
|
||||
**... for ...**
|
||||
```````{tab-set}
|
||||
``````{tab-item} ... 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 ...**
|
||||
|
||||
`````{tab-set}
|
||||
````{tab-item} ... Git in VS Code
|
||||
|
||||
**Add or make changes to file(s)**
|
||||
|
||||
```{error} To be written
|
||||
```
|
||||
Make some changes in for example VS Code and save them.
|
||||
|
||||
|
||||
````````
|
||||
`````````
|
||||
|
||||
**Check changes in book locally**
|
||||
```````{tab-set}
|
||||
``````{tab-item} User type 3 and 4
|
||||
Not possible, unless you want to be a user type 5. Otherwise you'll see your changes later on online.
|
||||
``````
|
||||
``````{tab-item} User type 5
|
||||
build book locally and eventually startup python server...
|
||||
```{error} To be written
|
||||
```
|
||||
``````
|
||||
```````
|
||||
|
||||
```````{tab-set}
|
||||
``````{tab-item} User type 3
|
||||
|
||||
`````{tab-set}
|
||||
````{tab-item} In GitLab
|
||||
|
||||
**Add changes to Git-timeline (committing)**
|
||||
|
||||
click commit in single text editor ...
|
||||
```{error} To be written
|
||||
```
|
||||
````
|
||||
````{tab-item} In GitHub
|
||||
|
||||
**Add changes to Git-timeline (committing)**
|
||||
|
||||
click commit in single text editor ...
|
||||
```{error} To be written
|
||||
```
|
||||
````
|
||||
|
||||
``````
|
||||
``````{tab-item} User type 4 and 5
|
||||
|
||||
|
||||
`````{tab-set}
|
||||
````{tab-item} Using Git in VS Code
|
||||
|
||||
**Select files ready to be added to Git-timeline (staging)**
|
||||
Select files ready to be added to Git-timeline (staging)
|
||||
|
||||
For demonstration purposes, we have created a new Markdown file called `new-chapter.md`, which we want to add to the book. Since this is a new file, Git has no knowledge about its existence yet. I.e., the file is *untracked*. To add new files to our repository, we need to *stage* and *commit* them. To do this, open the Source Control menu in the left side bar. Our new file should appear in this menu:
|
||||
|
||||
|
|
@ -106,8 +62,6 @@ The new file appears in the Source Control menu.
|
|||
|
||||
Notice that there is a green letter U placed besides the file, meaning that our file is untracked. To add a file to the *staging area*, click on the + that appears when you hover over the file.
|
||||
|
||||
**Add changes to Git-timeline locally (committing)**
|
||||
|
||||
Next, in the field that says "Message", write a short description of the changes you have made. This message is what is called the *Commit Message*. After we've done this, the menu should now look something like this:
|
||||
|
||||
```{figure} ../images/git-file-added.png
|
||||
|
|
@ -115,7 +69,6 @@ Next, in the field that says "Message", write a short description of the changes
|
|||
The new file has been staged, and we've written a Commit Message.
|
||||
```
|
||||
|
||||
**Add changes to GitHub/GitLab (pushing)**
|
||||
|
||||
Now, we are ready to add the changes to the repository. This is done by *committing* the staged changes. To do this, simply press the big, blue "Commit" button in the Source Control menu.
|
||||
|
||||
|
|
@ -126,20 +79,22 @@ 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.
|
||||
|
||||
````
|
||||
````{tab-item} Using GitHub Desktop
|
||||
````{tab-item} ... GitHub Desktop
|
||||
|
||||
**Select files ready to be added to Git-timeline (staging)**
|
||||
```{error} To be written
|
||||
```
|
||||
Make some changes 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
|
||||
```
|
||||
|
||||
**Add changes to Git-timeline locally (committing)**
|
||||
Add changes to Git-timeline locally (committing)
|
||||
|
||||
```{error} To be written
|
||||
```
|
||||
|
||||
**Add changes to GitHub/GitLab (pushing)**
|
||||
Add changes to GitHub/GitLab (pushing)
|
||||
|
||||
```{error} To be written
|
||||
```
|
||||
|
|
@ -147,4 +102,137 @@ The staging GitHub Desktop assumes you want to stage all files. You can unselect
|
|||
````
|
||||
`````
|
||||
``````
|
||||
```````
|
||||
|
||||
``````{tab-item} ... 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 ...**
|
||||
|
||||
`````{tab-set}
|
||||
````{tab-item} ... Git in VS Code
|
||||
|
||||
**Eventually solve conflicts with combining versions (merge conflicts, emerges after pulling)**
|
||||
|
||||
If you collaborate with colleagues on this branch, you can get the updates from your colleagues as well by pulling from GitLab/GitHub. Now your branch is up-to-date. However, this might lead into a merge conflict if you and colleagues have made incompatible changes. How to solve that?
|
||||
|
||||
```{error} To be written
|
||||
```
|
||||
````
|
||||
````{tab-item} ... GitHub Desktop
|
||||
|
||||
text..
|
||||
```{error} To be written
|
||||
```
|
||||
|
||||
````
|
||||
`````
|
||||
|
||||
|
||||
``````
|
||||
```````
|
||||
|
||||
````````
|
||||
|
||||
````````{tab-item} User type 5
|
||||
|
||||
|
||||
```````{tab-set}
|
||||
``````{tab-item} ... 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 ...**
|
||||
|
||||
`````{tab-set}
|
||||
````{tab-item} ... Git in VS Code
|
||||
|
||||
|
||||
```{error} To be written
|
||||
```
|
||||
Make some changes in for example VS Code and save them.
|
||||
|
||||
build book locally and eventually startup python server...
|
||||
```{error} To be written
|
||||
```
|
||||
|
||||
Select files ready to be added to Git-timeline (staging)
|
||||
|
||||
For demonstration purposes, we have created a new Markdown file called `new-chapter.md`, which we want to add to the book. Since this is a new file, Git has no knowledge about its existence yet. I.e., the file is *untracked*. To add new files to our repository, we need to *stage* and *commit* them. To do this, open the Source Control menu in the left side bar. Our new file should appear in this menu:
|
||||
|
||||
```{figure} ../images/git-new-file.png
|
||||
|
||||
The new file appears in the Source Control menu.
|
||||
```
|
||||
|
||||
Notice that there is a green letter U placed besides the file, meaning that our file is untracked. To add a file to the *staging area*, click on the + that appears when you hover over the file.
|
||||
|
||||
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
|
||||
|
||||
```{error} To be written
|
||||
```
|
||||
Make some changes 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
|
||||
```
|
||||
|
||||
Add changes to Git-timeline locally (committing)
|
||||
|
||||
```{error} To be written
|
||||
```
|
||||
|
||||
Add changes to GitHub/GitLab (pushing)
|
||||
|
||||
```{error} To be written
|
||||
```
|
||||
|
||||
````
|
||||
`````
|
||||
``````
|
||||
|
||||
``````{tab-item} ... 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 ...**
|
||||
|
||||
`````{tab-set}
|
||||
````{tab-item} ... Git in VS Code
|
||||
|
||||
**Eventually solve conflicts with combining versions (merge conflicts, emerges after pulling)**
|
||||
|
||||
If you collaborate with colleagues on this branch, you can get the updates from your colleagues as well by pulling from GitLab/GitHub. Now your branch is up-to-date. However, this might lead into a merge conflict if you and colleagues have made incompatible changes. How to solve that?
|
||||
|
||||
```{error} To be written
|
||||
```
|
||||
````
|
||||
````{tab-item} ... GitHub Desktop
|
||||
|
||||
text..
|
||||
```{error} To be written
|
||||
```
|
||||
````
|
||||
|
||||
`````
|
||||
|
||||
|
||||
``````
|
||||
```````
|
||||
|
||||
|
||||
|
||||
````````
|
||||
|
||||
`````````
|
||||
|
Before Width: | Height: | Size: 77 KiB After Width: | Height: | Size: 77 KiB |
|
|
@ -1,4 +1,4 @@
|
|||
# Reviewing and combine versions
|
||||
# Reviewing and combine versions (merge / pull request, merging)
|
||||
|
||||
Merging a branch into the main branch is also good moment to let a team-member review the content. By assigning a colleague to review your branch you can check the quality of your new content.
|
||||
|
||||
|
|
@ -6,7 +6,7 @@ Merging a branch into the main branch is also good moment to let a team-member r
|
|||
There is a slight difference in terminology between GitLab and GitHub. GitLab uses the term *Merge* Request while GitHub uses the term *Pull* Request. Both actions refer to the merging of a branch into the main branch.
|
||||
```
|
||||
|
||||
We're finished with our chapter, and now it's time to include all of our commits in the `main` branch. However, it's good practise to first merge `main` into our branch, so that we can see if there are any merge conflicts. Assuming that those merge conflicts are solved before, we'll now continue this example with the following merge of our branch into `main`.
|
||||
We're finished with our chapter, and now it's time to include all of our commits in the `main` branch. However, it's good practice to first merge `main` into our branch, so that we can see if there are any merge conflicts. Assuming that those merge conflicts are solved before, we'll now continue this example with the following merge of our branch into `main`.
|
||||
|
||||
`````{tab-set}
|
||||
````{tab-item} In GitLab
|
||||
|
|
|
|||
|
|
@ -1,4 +1,4 @@
|
|||
# Assign task to yourself
|
||||
# Assign task to yourself (milestones, issues)
|
||||
|
||||
In a repository, team members can define Milestones and Issues. Milestones are used to track the overall progress of the project to make sure that deadlines are met. A milestone can group many issues, which are individual tasks that need to be finished in order to reach the milestone.
|
||||
|
||||
|
|
@ -11,12 +11,14 @@ An issue is built up of the following attributes:
|
|||
|
||||
Every team member can create issues when they think of a task that would improve the book.
|
||||
|
||||
**Make and assign task to yourself (issues) in ...**
|
||||
|
||||
`````{tab-set}
|
||||
````{tab-item} In GitLab
|
||||
````{tab-item} ... GitLab
|
||||
|
||||
The issues in GitLab can be found on this page:
|
||||
|
||||
|
||||
|
||||
|
||||
You can create an issue by clicking on the blue `New Issue` button in the top right corner.
|
||||
|
||||
|
|
@ -24,7 +26,7 @@ You can create an issue by clicking on the blue `New Issue` button in the top ri
|
|||
|
||||
````
|
||||
|
||||
````{tab-item} In GitHub
|
||||
````{tab-item} ... GitHub
|
||||
|
||||
```{error} To be written
|
||||
```
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue