diff --git a/book/installation-and-setup/git-setup_local.md b/book/installation-and-setup/git-setup_local.md index 8a463b3..3444fd1 100644 --- a/book/installation-and-setup/git-setup_local.md +++ b/book/installation-and-setup/git-setup_local.md @@ -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. diff --git a/book/installation-and-setup/git.md b/book/installation-and-setup/git.md index 09b93cb..e99f1f7 100644 --- a/book/installation-and-setup/git.md +++ b/book/installation-and-setup/git.md @@ -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) \ No newline at end of file diff --git a/book/installation-and-setup/overview.md b/book/installation-and-setup/overview.md index 3cf6b62..3db5dcc 100644 --- a/book/installation-and-setup/overview.md +++ b/book/installation-and-setup/overview.md @@ -6,7 +6,7 @@ The following table will link the relevant installation and setup steps for you. |User Types|Required actions|
Installation
| |:---:|:---|:---| -| Type 1
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
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
Git| VS Code
GitHub Desktop / Git in VS Code | | Type 5 | Editing text
Git
Managing code-related software
Build your book | VS Code
GitHub Desktop / Git in VS Code
Anaconda
Jupyter Book | diff --git a/book/installation-and-setup/user_types.md b/book/installation-and-setup/user_types.md index 4b9b0c4..df154c0 100644 --- a/book/installation-and-setup/user_types.md +++ b/book/installation-and-setup/user_types.md @@ -3,11 +3,14 @@ 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**.
-Example Image - 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. +Example Image + + There are multiple tools of providing feedback in the built book: + + 1) 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). + + 2) 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.
diff --git a/book/workflows/branches.md b/book/workflows/branches.md index 1a84baa..f934563 100644 --- a/book/workflows/branches.md +++ b/book/workflows/branches.md @@ -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.
+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 ...** +**Please 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,49 @@ 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`. +
+ Example Image +
+ +2. Clicking on the button will display the following screen. Make sure the option `SSH` is selected and copy the link. + +
+ Example Image +
```` -````{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`. +
+ Example Image +
+ +2. Clicking on the button will display the following screen. Click on `Open with GitHub Desktop`. + +
+ Example Image +
+ +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`. + +
+ Example Image +
```` ````` -**... with ...** +**... and I would like to view the local repositery in ...** `````{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 +138,40 @@ 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. The sidebar on the left shows all the repositeries you have cloned. Navigate to the one you would like to work in. + +```{figure} ../figures/Branching_GitHub_Desktop.PNG +``` +2. In the top bar click on `New Branch`. + +```{figure} ../figures/Branching_GitHub_Desktop2.PNG +``` +3. The following window will pop up in which you can specify the name of your branch and the source branch (the branch which you will copy). Tip: it is useful to name the branch according to the additions or changes you want to make. + +```{figure} ../figures/Branching_GitHub_Desktop3.PNG +``` +```` +````` + +`````` + +``````{tab-item} I have previously opened the repository (Branching) + +**I want to update my repository (pulling) and 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 @@ -116,25 +183,12 @@ 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. 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. -````{tab-item} ... GitHub Desktop -```{error} To be written -``` +```{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. ``` ```` diff --git a/book/workflows/collaboration.md b/book/workflows/collaboration.md index 32c3ab2..70e60c8 100644 --- a/book/workflows/collaboration.md +++ b/book/workflows/collaboration.md @@ -1,28 +1,16 @@ # Collaborative book-editing -As previously mentioned there are multiple platforms that can host Git repositories which are extremely useful for collaboration on text-based files. Here we will elaborate on two: GitLab and GitHub both in the online environment and locally on your device. - -Globally, the steps involved are as follows: - 1. Define an issue to work on - 2. Open the files of the repository online or clone the repository to work on it locally - 3. Create a branch for your changes - 4. Edit the book by: - - Pulling remote changes from others - - Staging your changes - - Committing a collection of changes - - If working on a repository locally: pushing your changes - 5. Reviewing and merging changes in a merge request - 6. Publishing the changes to the published version of the book ```{admonition} User types :class: tip 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} diff --git a/book/workflows/figures/Branching_GitHub_Desktop.PNG b/book/workflows/figures/Branching_GitHub_Desktop.PNG new file mode 100644 index 0000000..4fb811e Binary files /dev/null and b/book/workflows/figures/Branching_GitHub_Desktop.PNG differ diff --git a/book/workflows/figures/Branching_GitHub_Desktop2.png b/book/workflows/figures/Branching_GitHub_Desktop2.png new file mode 100644 index 0000000..40f979e Binary files /dev/null and b/book/workflows/figures/Branching_GitHub_Desktop2.png differ diff --git a/book/workflows/figures/Branching_GitHub_Desktop3.PNG b/book/workflows/figures/Branching_GitHub_Desktop3.PNG new file mode 100644 index 0000000..5e12b72 Binary files /dev/null and b/book/workflows/figures/Branching_GitHub_Desktop3.PNG differ diff --git a/book/workflows/figures/CloneRepo_Githubdesk.png b/book/workflows/figures/CloneRepo_Githubdesk.png new file mode 100644 index 0000000..b40b196 Binary files /dev/null and b/book/workflows/figures/CloneRepo_Githubdesk.png differ diff --git a/book/workflows/figures/CloneRepo_TroughGithubdesk.PNG b/book/workflows/figures/CloneRepo_TroughGithubdesk.PNG new file mode 100644 index 0000000..f847d0a Binary files /dev/null and b/book/workflows/figures/CloneRepo_TroughGithubdesk.PNG differ diff --git a/book/workflows/figures/Clone_GitHub.PNG b/book/workflows/figures/Clone_GitHub.PNG new file mode 100644 index 0000000..16c8c0d Binary files /dev/null and b/book/workflows/figures/Clone_GitHub.PNG differ diff --git a/book/workflows/figures/NewBranch_GitHub.PNG b/book/workflows/figures/NewBranch_GitHub.PNG new file mode 100644 index 0000000..efe8bd3 Binary files /dev/null and b/book/workflows/figures/NewBranch_GitHub.PNG differ diff --git a/book/workflows/figures/NewBranch_GitHub2.PNG b/book/workflows/figures/NewBranch_GitHub2.PNG new file mode 100644 index 0000000..644e247 Binary files /dev/null and b/book/workflows/figures/NewBranch_GitHub2.PNG differ diff --git a/book/workflows/figures/NewBranch_GitHub3.PNG b/book/workflows/figures/NewBranch_GitHub3.PNG new file mode 100644 index 0000000..4c3d006 Binary files /dev/null and b/book/workflows/figures/NewBranch_GitHub3.PNG differ diff --git a/book/workflows/figures/Pull_VS.PNG b/book/workflows/figures/Pull_VS.PNG new file mode 100644 index 0000000..3184ae1 Binary files /dev/null and b/book/workflows/figures/Pull_VS.PNG differ diff --git a/book/workflows/milestones_issues.md b/book/workflows/milestones_issues.md index 4a20595..bf70c5f 100644 --- a/book/workflows/milestones_issues.md +++ b/book/workflows/milestones_issues.md @@ -11,26 +11,23 @@ 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. -The following tabs explain where the Issues can be found in GitLab and GitHub. **Make and assign task to yourself (issues) in ...** `````{tab-set} ````{tab-item} ... GitLab -`````{tab-set} -````{tab-item} GitLab - The issues in GitLab can be found in your repositery in the left bar. ![issues](figures/issues_new.png) -You can create an issue by clicking on the blue `New Issue` button in the top right corner. This will lead you to this window where you can specify all attributes we mentioned before! +You can create an issue by clicking on the blue `New Issue` button in the top right corner.
+This will lead you to this window where you can specify all attributes we mentioned before! ![new issue](figures/New_Issue_GitLab.png) ```` -````{tab-item} GitHub +````{tab-item} ... GitHub The issues in GitHub can be found in your repositery in the top bar. @@ -43,11 +40,6 @@ Clicking on `Issues` will open up the page with all the issues on this repositer Finally, by clicking the green `New Issue` button you can create a new issue and specify all the attributes we mentioned before! New Issue
-````{tab-item} ... GitHub - -```{error} To be written -``` - ```` `````