From 05f7e7e86a46e4ce425018e4004fe4e054248169 Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Mon, 25 Mar 2024 09:56:38 +0100 Subject: [PATCH] Moved stuff from install chapter and restructured --- book/_toc.yml | 12 ++-- book/features/buildbook.md | 15 +++++ book/installation-and-setup/git-clone.md | 24 ------- book/workflows/access_control_permissions.md | 1 + .../git-branch.md => workflows/branches.md} | 30 +++++---- book/workflows/collaboration.md | 64 ++++--------------- .../edit_book.md} | 56 ++++++++++++---- .../merge_request.md} | 20 +++++- book/workflows/milestones_issues.md | 32 ++++++++++ book/workflows/overview.md | 2 +- book/workflows/publish.md | 15 +---- book/workflows/repositories.md | 51 +++++++++++++++ 12 files changed, 200 insertions(+), 122 deletions(-) create mode 100644 book/features/buildbook.md delete mode 100644 book/installation-and-setup/git-clone.md create mode 100644 book/workflows/access_control_permissions.md rename book/{installation-and-setup/git-branch.md => workflows/branches.md} (75%) rename book/{installation-and-setup/git-stage-commit-push.md => workflows/edit_book.md} (52%) rename book/{installation-and-setup/git-merge.md => workflows/merge_request.md} (80%) create mode 100644 book/workflows/milestones_issues.md create mode 100644 book/workflows/repositories.md diff --git a/book/_toc.yml b/book/_toc.yml index 748c41a..0c50d6c 100644 --- a/book/_toc.yml +++ b/book/_toc.yml @@ -10,11 +10,6 @@ parts: - file: installation-and-setup/git-setup - file: installation-and-setup/vscode-setup - file: installation-and-setup/git-setup_local - sections: - - file: installation-and-setup/git-clone - - file: installation-and-setup/git-branch - - file: installation-and-setup/git-stage-commit-push - - file: installation-and-setup/git-merge - file: installation-and-setup/anaconda - file: installation-and-setup/add_conda_to_path - file: installation-and-setup/working-directory @@ -23,7 +18,12 @@ parts: - file: workflows/overview sections: - file: workflows/collaboration - - file: workflows/publish + sections: + - file: workflows/milestones_issues + - file: workflows/repositories + - file: workflows/branches + - file: workflows/edit_book + - file: workflows/publish - file: workflows/githubtemplate - caption: Features chapters: diff --git a/book/features/buildbook.md b/book/features/buildbook.md new file mode 100644 index 0000000..c9acb3e --- /dev/null +++ b/book/features/buildbook.md @@ -0,0 +1,15 @@ +# Book build on webserver / GitHub Pages + +Now that we have talked about how you can collaborate using git, it's time to explain how the book is actually built. + +## GitLab Pages + +## GitHub Pages + +## Pipeline + +Both GitLab and GitHub make use of CI/CD to publish the jupyter books. CI/CD stands for Continuous Integration/Continuous Deployment. Within the scope of jupyter books focuses on automating the process of building and deploying the books. It makes sure that the book is always up-to-date and available. + +Concretely, Continuous Integration means that whenever changes are pushed to the repository (where does the publish branch come in?) the pipeline is triggered. Moreover, the pipeline also builds the book which is composed out of multiple .md or .ipynb files and converts those files into HTML. + +Continuous Deployment ensures that the book is deployed onto the desired destination (in our case the website) and accessible to the readers. \ No newline at end of file diff --git a/book/installation-and-setup/git-clone.md b/book/installation-and-setup/git-clone.md deleted file mode 100644 index 5ed959c..0000000 --- a/book/installation-and-setup/git-clone.md +++ /dev/null @@ -1,24 +0,0 @@ -(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 ` for your work. \ No newline at end of file diff --git a/book/workflows/access_control_permissions.md b/book/workflows/access_control_permissions.md new file mode 100644 index 0000000..2aef880 --- /dev/null +++ b/book/workflows/access_control_permissions.md @@ -0,0 +1 @@ +# Access Control / Permissions \ No newline at end of file diff --git a/book/installation-and-setup/git-branch.md b/book/workflows/branches.md similarity index 75% rename from book/installation-and-setup/git-branch.md rename to book/workflows/branches.md index 0366f57..d67666d 100644 --- a/book/installation-and-setup/git-branch.md +++ b/book/workflows/branches.md @@ -1,15 +1,17 @@ -(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: +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: -- 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. +- 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". Your own branch helps to keep an overview of the changes made to the book. +- 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. In case those changes made in parallel lead to conflicts, they can be resolved during the merging of the branches. -## How to make a branch +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} Branching in 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 @@ -33,9 +35,12 @@ We're making a new branch called `chapter-2` from the `main` branch. The circled menu is the branch selection menu. ``` - +```` +````{tab-item} Branching in GitHub +... +```` +````{tab-item} Branching locally with Git in VS Code 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 @@ -47,9 +52,10 @@ Location of the branch menu. The branch selection menu, where our new branch has shown up. ``` +```` +````{tab-item} Branching locally with GitHub Desktop +... +```` +````` -5. Now that we've created and checked out our new branch, we can start {ref}`making and committing changes `. - -## The `publish` branch - -If your repository is located in the [Interactive Textbooks CiTG](https://gitlab.tudelft.nl/interactivetextbooks-citg) group on GitLab, you will see that it already has a branch called `publish`. 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 (and certainly not right before an exam!) to prevent confusion. This way, you can still make frequent changes to the `main` branch. +Now that we've created and checked out our new branch, we can start {ref}`making and committing changes `. diff --git a/book/workflows/collaboration.md b/book/workflows/collaboration.md index 162e094..ff382f2 100644 --- a/book/workflows/collaboration.md +++ b/book/workflows/collaboration.md @@ -1,54 +1,14 @@ -# Collaboration +# Collaborative book-editing using Git -As previously mentioned there are multiple platforms that can host Git repositories. Here we will elaborate on two: GitLab and GitHub. +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. -## Staging, committing and pushing - -A jupyter book is composed out of many markdown 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. Find out for about staging committing and pushing [here](/book/installation-and-setup/git-stage-commit-push.md). - -## Repositeries, Branching and Merging - -We have previously introduced the notions of local and remote repositories, [branching](/book/installation-and-setup/git-branch.md). and finally [merging branches](/book/installation-and-setup/git-merge.md). - -All the (markdown) files that make up the book are contained on the remote repository on GitLab or GitHub. This could be on an open repository on `gitlab.com` or `github.com`. In the context of creating educational books for students at TU Delft, the repository will most likely be located on `gitlab.tudelft.nl`. - -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. -- The different branches help to keep an overview of the changes made to the book. -- Branching allows multiple people to make changes to the book at the same time. -- In case those changes made in parallel lead to conflicts, they can be resolved during the merging of the branches. - -This systematic workflow guarantees that editing the book goes smoothly. - -Merging a branch into the main branch is a also good moment to let a team-member review the content. This is done in the merge-request. By assigning a colleague to review your branch you can check the quality of your new content. - -```{note} -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. -``` -## Access Control / Permissions - -## 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. Every team member can create issues when they think of a task that would improve the book like for example: - -New Issue
- -You can create an issue by clicking on the blue `New Issue` button in the top right corner. - -An issue is built up of the following attributes: -- the title, this should just be a quick description of the task -- a label, to assign a category to the task such as: new content -- an assignee, the person who created the task can assign a team-member to the task or the task can remain without an assignee. Then whoever would like to pick up the task can assign it to themselves! -- a discussion section, here team-members can discuss any questions about the task -- a due date, in case the task is urgent or to keep track of deadlines - -New Issue
- -When the task is completed, the issue can be closed and you can move on to the next! - -## Publishing the website - -Once the book is ready to be published, a static website can be created through GitLab pages. (Need more info on that/Are we using gitlab pages?) - -## GitHub - -The workflow described above is largely the same on both platforms since both platforms stick to the names of the git functionalities. So alternatively to GitLab. Github and Github pages ca also be used to publish your book. +Globally, the steps involved are as follows: + 1. Define 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: + - Staging your changes + - Commit a collection of changes + - If working on a repository locally: pushing your changes + 5. Reviewing and merging changes in a merge request + 6. Publish changes to published version of book \ No newline at end of file diff --git a/book/installation-and-setup/git-stage-commit-push.md b/book/workflows/edit_book.md similarity index 52% rename from book/installation-and-setup/git-stage-commit-push.md rename to book/workflows/edit_book.md index b15f130..b004607 100644 --- a/book/installation-and-setup/git-stage-commit-push.md +++ b/book/workflows/edit_book.md @@ -1,9 +1,22 @@ -(stage-commit-push)= -# Staging, committing and pushing +# Editing the book + +A jupyter book is composed out of many markdown 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. 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 + +`````{tab-set} +````{tab-item} Staging in GitLab +In GitLab staging doesn't exist, just edit a file and you can directly commit it. +... +```` +````{tab-item} Staging in GitHub +In GitHub staging doesn't exist, just edit a file and you can directly commit it. +... +```` +````{tab-item} Staging using Git in VS Code + 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 @@ -12,8 +25,23 @@ 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. +```` +````{tab-item} Staging using GitHub Desktop +... +```` +````` ## Committing +Now that we've made some change, we need to add them to our git-timeline. + +`````{tab-set} +````{tab-item} Committing in GitLab +... +```` +````{tab-item} Committing in GitHub +... +```` +````{tab-item} Committing using Git in VS Code 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 @@ -22,23 +50,29 @@ 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. +```` +````{tab-item} Committing using GitHub Desktop +... +```` +````` ```{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. +Are we done now? Yes, if you've made all your changes on GitLab / GitHub. However, no! if you did that locally! 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. + +`````{tab-set} +````{tab-item} Committing using Git in VS Code +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 \ No newline at end of file +```` +````{tab-item} Committing using GitHub Desktop +... +```` +````` \ No newline at end of file diff --git a/book/installation-and-setup/git-merge.md b/book/workflows/merge_request.md similarity index 80% rename from book/installation-and-setup/git-merge.md rename to book/workflows/merge_request.md index 5402a75..21c290b 100644 --- a/book/installation-and-setup/git-merge.md +++ b/book/workflows/merge_request.md @@ -1,8 +1,16 @@ -(git-merge)= -# Merging +# Reviewing and merging changes + +Merging a branch into the main branch is also good moment to let a team-member review the content. This is done in the merge-request. By assigning a colleague to review your branch you can check the quality of your new content. + +```{note} +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. +`````{tab-set} +````{tab-item} Committing using GitLab + 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". @@ -30,4 +38,10 @@ Example of a filled-in merge request. :name: gitlab-finished-merge-request The finished merge request. -``` \ No newline at end of file +``` + +```` +````{tab-item} Committing using GitHub +... +```` +````` diff --git a/book/workflows/milestones_issues.md b/book/workflows/milestones_issues.md new file mode 100644 index 0000000..1c5bdf4 --- /dev/null +++ b/book/workflows/milestones_issues.md @@ -0,0 +1,32 @@ +# 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. + +An issue is built up of the following attributes: +- the title, this should just be a quick description of the task +- a label, to assign a category to the task such as: new content +- an assignee, the person who created the task can assign a team-member to the task or the task can remain without an assignee. Then whoever would like to pick up the task can assign it to themselves! +- a discussion section, here team-members can discuss any questions about the task +- a due date, in case the task is urgent or to keep track of deadlines + +Every team member can create issues when they think of a task that would improve the book. + +`````{tab-set} +````{tab-item} Issues in GitLab + +The issues in GitLab can be found on this page: + +New Issue
+ +You can create an issue by clicking on the blue `New Issue` button in the top right corner. + +New Issue
+```` + +````{tab-item} Issues in GitHub +... + +```` +````` + +When the task is completed, the issue can be closed and you can move on to the next! \ No newline at end of file diff --git a/book/workflows/overview.md b/book/workflows/overview.md index 434ae2d..4fccbc9 100644 --- a/book/workflows/overview.md +++ b/book/workflows/overview.md @@ -1,4 +1,4 @@ -# Working in Git +# Workflows - what does the publish branch do? - what is a pipeline diff --git a/book/workflows/publish.md b/book/workflows/publish.md index ecee4d2..ee94123 100644 --- a/book/workflows/publish.md +++ b/book/workflows/publish.md @@ -1,15 +1,4 @@ # Publishing your book -Now that we have talked about how you can collaborate using git, it's time to explain how the book is actually built. - -# GitLab Pages - -# GitHub Pages - -# Pipeline - -Both GitLab and GitHub make use of CI/CD to publish the jupyter books. CI/CD stands for Continuous Integration/Continuous Deployment. Within the scope of jupyter books focuses on automating the process of building and deploying the books. It makes sure that the book is always up-to-date and available. - -Concretely, Continuous Integration means that whenever changes are pushed to the repository (where does the publish branch come in?) the pipeline is triggered. Moreover, the pipeline also builds the book which is composed out of multiple .md or .ipynb files and converts those files into HTML. - -Continuous Deployment ensures that the book is deployed onto the desired destination (in our case the website) and accessible to the readers. \ No newline at end of file +Once the book is ready to be published, a static website can be created through GitLab. (Need more info on that/Are we using gitlab pages?) +If your repository is located in the [Interactive Textbooks CiTG](https://gitlab.tudelft.nl/interactivetextbooks-citg) group on GitLab, you will see that it already has a branch called `publish`. 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 (and certainly not right before an exam!) to prevent confusion. This way, you can still make frequent changes to the `main` branch. \ No newline at end of file diff --git a/book/workflows/repositories.md b/book/workflows/repositories.md new file mode 100644 index 0000000..44cc0d3 --- /dev/null +++ b/book/workflows/repositories.md @@ -0,0 +1,51 @@ +# Open files online / clone files +We have previously introduced the notions of using Git in the online environment (remote) or locally. All the (markdown) files that make up the book are contained on the remote repository on GitLab or GitHub. This could be on an open repository on `gitlab.com` or `github.com`. In the context of creating educational books for students at TU Delft, the repository will most likely be located on `gitlab.tudelft.nl`. + +If you'd like to work on your book locally, you need to clone your book. + +### Cloning a repository + +`````{tab-set} +````{tab-item} Cloning repository from GitLab + +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. +``` +```` + +````{tab-item} Cloning repository from GitHub +... +```` + +````{tab-item} Cloning repository from GitHub using GitHub Desktop +... +```` +````` + +Now that we've obtained the source, we can set up the files locally: + +`````{tab-set} +````{tab-item} Cloning repository with Git in VS Code +2. Open a new VS Code window. You should be greeted with a welcome page ({numref}`vscode-welcome`). On this page, click "Clone Git Repository". Alternatively, open the Source Control menu from the left side bar, and click on "Clone Repository". + +```{figure} ../images/vscode-welcome.png +:name: vscode-welcome + +The VS Code welcome screen. +``` + +3. On the top of your screen, you should get a prompt asking you for a URL. In this field, paste the link you copied from GitLab and press enter. It will ask you to choose the location of the repository. After you've chosen a location, a final prompt will show up asking if you want to open the repository. Click on "Open". + +4. You now have a local copy of the repository. +```` + +````{tab-item} Cloning repository with GitHub Desktop +.... +```` +````` \ No newline at end of file