diff --git a/book/_toc.yml b/book/_toc.yml index 94c6153..d2b268e 100644 --- a/book/_toc.yml +++ b/book/_toc.yml @@ -22,8 +22,8 @@ parts: - file: installation-and-setup/jupyter-book-setup - file: workflows/overview sections: - - file: workflows/gitlab - - file: workflows/github + - file: workflows/collaboration + - file: workflows/githubtemplate - caption: Features chapters: - file: basic-features/overview diff --git a/book/workflows/collaboration.md b/book/workflows/collaboration.md new file mode 100644 index 0000000..6da6786 --- /dev/null +++ b/book/workflows/collaboration.md @@ -0,0 +1,57 @@ +# Collaboration + +As previosuly mentioned there are multiple platforms that can host Git repositeries. Here we will elaborate on two: GitLab and GitHub. + +````{tab} GitLab + +## 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 tem-members. Working on content for the book is mainly individual work, the beauty of git comes in when everybodys changes are merged into the main branch. Find out for about staging comitting 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 repositeries, branching and finally merging branches. You can find it [here](/book/installation-and-setup/git-branch.md). + +All the (markdown) files that make up the book are contained on the remote repositery on GitLab or Github. This could be on an open repositery on `gitlab.com`. In the context of creating educational books for students at TU Delft, the repositery will most likely be located on `gitlab.tudelft.com`. + +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 smoothely. + +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. + +## Milestones & Issues + +In a repositery, 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 on 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?) + +```` +````{tab} GitHub + + +```` + + + +(An alternative is to use Github and Github pages to publish your book.?)# \ No newline at end of file diff --git a/book/workflows/figures/Issues.PNG b/book/workflows/figures/Issues.PNG new file mode 100644 index 0000000..9410665 Binary files /dev/null and b/book/workflows/figures/Issues.PNG differ diff --git a/book/workflows/figures/New_Issue_GitLab.png b/book/workflows/figures/New_Issue_GitLab.png new file mode 100644 index 0000000..fb8152c Binary files /dev/null and b/book/workflows/figures/New_Issue_GitLab.png differ diff --git a/book/workflows/github.md b/book/workflows/githubtemplate.md similarity index 98% rename from book/workflows/github.md rename to book/workflows/githubtemplate.md index 783ddbf..739ab55 100644 --- a/book/workflows/github.md +++ b/book/workflows/githubtemplate.md @@ -1,4 +1,4 @@ -# GitHub template +# Get started using our GitHub template! To get started making your Jupyter Book with our functionalities, fork our template book https://github.com/TeachBooks/template : diff --git a/book/workflows/overview.md b/book/workflows/overview.md index d8ab42a..326e50f 100644 --- a/book/workflows/overview.md +++ b/book/workflows/overview.md @@ -1,26 +1,12 @@ -# Team collaboration in Git +# Working in Git -```{warning} Under Construction! - -Okay i have to admit that there are things i am still unsure of - what does the publish branch do? - what is a pipeline -- -``` -This page suggests a workflow how to collaborate in Git and GitLab for different user types. Every team might have a different workflows but this workflow is shown as an example and is used in the MUDE course in CEG and by the TeachBooks team. +This coming page suggests a workflow how to collaborate using Git! Every team might have a different workflows but this workflow is shown as an example and is used in the MUDE course in CEG and by the TeachBooks team.
-# Repositeries, Branching and Merging +There are two web-based platforms that host Git repositeries: GitLab and GitHub. You might have read about GitHub Desktop that we are using to manage local repositeries. GitLab and GitHub have similar features and are both widely used by the open source community. The main difference that is relevant for TeachBooks is that GitHub allows to host websites online without a server whereas GitLab needs a server. TU Delft has their own server which is why we use `tudelft.gitlab.nl`. -We have previously introduced the notions of local and remote repositeries, branching and finally merging branches. You can find it [here](/book/installation-and-setup/git-setup_local.md). - -All the (markdown) files that make up the book are contained on the remote repositery on GitLab. This could be on an open repositery on `gitlab.com`. In the context of creating educational books for students at TU Delft, the repositery will most likely be located on `gitlab.tudelft.com` (local server?). - -The main branch is the default branch. The content on this branch will be the most up to date that is approved by a team-member during merging. 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 smoothely. - -# Issues +Now that you understand how to collaborate in git it is time to get started on your own book. The end of this chapter provides a [tutorial](githubtemplate.md) on how to fork our template book. By forking you are essentially creating an independent copy of the template repositery in your own GitLab or GitHub account. - -(An alternative is to use Github and Github pages to publish your book.?)# -