Merge branch 'main' into 'publish'

Git-VS Code

See merge request interactivetextbooks-citg/jupyter-book-manual!13

book/_toc.yml

@@ -7,6 +7,18 @@ parts:
     - file: installation-and-setup/git-setup
     - file: installation-and-setup/vscode-setup
     - file: installation-and-setup/jupyter-book-setup
+  - caption: Workflows
+    chapters:
+    - file: workflows/git-basic
+      sections:
+      - file: workflows/git-clone
+      - file: workflows/git-branch
+      - file: workflows/git-stage-commit-push
+      - file: workflows/git-merge
+      - file: workflows/git-advanced
+        sections: 
+        - file: workflows/git-merge-conflict
+    - file: workflows/gitlab
   - caption: Cookbook
     chapters:
     - file: cookbook/recipes.md

book/workflows/git-advanced.md

@@ -0,0 +1,4 @@
+(git-advanced)=
+# Advanced Git topics
+
+Under construction.

book/workflows/git-basic.md

@@ -0,0 +1,23 @@
+# Working with Git in VS Code
+
+In this section you will learn how to perform basic Git actions in VS Code. Courses on Git usually make use of the command line interface to do these actions, but this introduces a steep learning curve. Instead, using Git from VS Code is much more visual (i.e., more "clicky"), and therefore easier to use for those inexperienced with the command line. 
+
+## What is Git?
+Git is a version control system (VCS). In short, a VCS is a tool that helps you keep track of changes to you codebase (e.g., a Jupyter Book project!) over time. It allows you to keep track of the history of changes made to your code, work collaboratively with others, and revert to a previous version of the code if needed. 
+
+## What is GitLab?
+GitLab is platform that hosts Git repositories, which can also be accessed through a web interface. Essentially, GitLab hosts the main repository that the members of a project interact with. Additionally, GitLab has plenty of other useful features such as issue tracking and code review. A selection of these features that are particularly useful for us as Jupyter Book developers will be highlighted in a {ref}`later section <gitlab>.
+
+## Terminology
+This is a (non-exhaustive) list of terminology that will be used throughout this section:
+
+- Repository: a collection of files and folders, along with a history of their changes and who made them. 
+- Commit: a snapshot of the current state of the repository.
+- Staging: preparation of files to be committed. During staging, we propose files to be committed.
+- Branch: a development line.
+- Local: on your own computer.
+- Remote: on someone elses computer.
+- Pushing: uploading new commits to the remote repository.
+- Pulling: downloading new commits from the remote repository to your local repository.
+- Tracked (files): files that Git knows about and keeps track of their history.
+- Untracked (files): files that Git does not yet know about.

book/workflows/git-branch.md

@@ -0,0 +1,59 @@
+(git-branch)=
+# Branches
+
+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. Some advantages of working with branches are:
+
+- Isolation: when you work on your own branch, your changes are isolated from the main codebase. Unfinished or unreviewed parts of your book are "hidden". 
+- Collaboration: branches make it easier for multiple project members to work on the same codebase simultaneously. If every member works on their own branch, they can make their changes without having to worry about interfering with another members' changes.
+
+## How to make a branch
+
+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.
+
+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
+: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. 
+```
+
+4. The final step is to *check out* our new branch in VS Code. *Checking out* means that we're changing our working branch (i.e., the one to which we will be committing our changes) from one to the other. In VS Code, open the branch menu from the bottom left (see {numref}`git-branch-menu-main`). You'll be be greeted with a menu that looks like the one in {numref}`git-branch-selection-menu`. In this menu, we get an overview of the branches of our repository. Notice that our new branch `chapter-2` appears as `origin/chapter-2`, and has a cloud icon in front of it. This means that the branch only exists on the remote repository. Check out the branch by simply clicking on it. Check that the branch is indeed checked out by looking at the branch menu button in the bottom left again; it should now say the name of your branch instead of `main` (in our case `chapter-2`). 
+
+```{figure} ../images/git-branch-menu-main.png
+:name: git-branch-menu-main
+
+Location of the branch menu.
+```
+
+```{figure} ../images/git-branch-selection-menu.png
+:name: git-branch-selection-menu
+
+The branch selection menu, where our new branch has shown up.
+```
+
+5. Now that we've created and checked out our new branch, we can start {ref}`making and committing changes <stage-commit-push>`.
+
+## Predefined branches
+
+If your repository is located in the [Interactive Textbooks CiTG](https://gitlab.tudelft.nl/interactivetextbooks-citg) group on GitLab, it is likely that it already has some predefined branches in addition to `main`, namely `publish` and `publish-html`. These branches serve the following purposes:
+
+- `main`: this is the main development branch on which new changes are collected. If you're working on 
+- `publish`: this is the version of the book that is visible to the public (i.e., the version that the students will see). Again, you cannot push directly to this branch. 
+- `publish-html`: this branch contains the HTML of the version of the book that lives on the `publish` branch. When a new version of the book is merged in the `publish` branch, the new book is built using the `jupyter book build` command and the HTML is uploaded to `publish-html`. The webserver is constantly fetching this branch and pulling any incoming changes.

book/workflows/git-clone.md

@@ -0,0 +1,24 @@
+(git-clone)=
+# Cloning a repository
+
+Before we can start working on our Jupyter Book, we of course need to have the repository on our own system. This is done by *cloning* the repository, and here's how you do it with VS Code:
+
+1. On GitLab, go to the repository of your book. Click on the blue button that says "Clone" ({numref}`gitlab-clone`), and copy the link under "Clone with SSH".
+
+```{figure} ../images/gitlab-clone.png
+:name: gitlab-clone
+
+The cloning menu.
+```
+
+2. Open a new VS Code window. You should be greeted with a welcome page ({numref}`vscode-welcome`). On this page, click "Clone Git Repository". Alternatively, open the Source Control menu from the left side bar, and click on "Clone Repository".
+
+```{figure} ../images/vscode-welcome.png
+:name: vscode-welcome
+
+The VS Code welcome screen.
+```
+
+3. On the top of your screen, you should get a prompt asking you for a URL. In this field, paste the link you copied from GitLab and press enter. It will ask you to choose the location of the repository. After you've chosen a location, a final prompt will show up asking if you want to open the repository. Click on "Open".
+
+4. You now have a local copy of the repository. Next, {ref}`make a new branch <git-branch>` for your work.

book/workflows/git-merge-conflict.md

@@ -0,0 +1,4 @@
+(merge-conflicts)=
+# Merge conflicts
+
+Under construction.

book/workflows/git-merge.md

@@ -0,0 +1,33 @@
+(git-merge)=
+# Merging
+
+We're finished with our chapter, and now it's time to include all of our commits in the `main` branch.
+
+1. Make sure that you've committed all your new sections and changes, and that they're pushed to the remote repository.
+
+2. Go the repository overview on GitLab. In the left menu bar, go to "Merge requests". On the Merge requests page, click "New merge request". 
+
+3. You can now choose a source branch and a target branch. Since we want to merge our changes from `chapter-2` *into* `main`, `chapter-2` is the source branch and `main` is the target branch ({numref}`gitlab-merge-request`) . Once you've selected the correct branches, click "Compare branches and continue".
+
+```{figure} ../images/gitlab-merge-request.png
+:name: gitlab-merge-request
+
+Creating a new merge request to merge `chapter-2` into `main`.
+```
+
+4. On the next page, you can give your merge request a name, and provide a description of your changes ({numref}`gitlab-merge-request-description`). If somebody has to review your changes, you can add them in the "Reviewer menu". They will then be notified via email that they need to review your work. Finally, watch out for the option "Delete source branch when merge request is accepted". If you want to keep working on the same branch, even after your previous work has been merged, make sure you untick the box! Once everything is filled in, click "Create merge request".
+
+```{figure} ../images/gitlab-merge-request-description.png
+:name: gitlab-merge-request-description
+
+Example of a filled-in merge request.
+```
+
+5. 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). If this isn't the case, you'll see a red cross instead of the green checkmark, and GitLab will tell that you've run into a *merge conflict*. You'll need to figure out which file(s) are causing this, and fix it. You can read more on this in the {ref}`section on merge conflicts <merge-conflicts>`.
+
+
+```{figure} ../images/gitlab-finished-merge-request.png
+:name: gitlab-finished-merge-request
+
+The finished merge request.
+```

book/workflows/git-stage-commit-push.md

@@ -0,0 +1,44 @@
+(stage-commit-push)=
+# Staging, committing and 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, and we've checked out this branch (make sure this is really the case by checking the name of the current branch in the bottom-left corner of your VS Code window!).
+
+## 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. 
+
+## Committing
+Next, in the field that says "Message", write a short description of the changes you have made. This message is what is called the *Commit Message*. After we've done this, the menu should now look something like this:
+
+```{figure} ../images/git-file-added.png
+
+The new file has been staged, and we've written a Commit Message.
+```
+
+Now, we are ready to add the changes to the repository. This is done by *committing* the staged changes. To do this, simply press the big, blue "Commit" button in the Source Control menu. 
+
+```{tip}
+Unlike this example, you do not have to stage and commit every file individually. In a real case, a chapter may consist of multiple files (and images!), and it makes sense to add them in the same commit. 
+```
+
+## Pushing the changes
+Are we done now? No! Up to now, we have only made changes and committed to the *local* copy of the repository. We still need to *push* our changes to the *remote* repository (the one that is on the TU Delft GitLab), so that others can see our changes and interact with them. 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.
+```
+
+## Summary
+In short, the Git workflow consists of the following steps:
+
+1. Staging new and modified files
+2. Writing a commit message
+3. Committing the changes
+4. Pushing the new changes to GitLab

book/workflows/gitlab.md

@@ -0,0 +1,2 @@
+(gitlab)=
+# Useful GitLab features