diff --git a/book/workflows/collaboration.md b/book/workflows/collaboration.md index 3501fce..162e094 100644 --- a/book/workflows/collaboration.md +++ b/book/workflows/collaboration.md @@ -1,23 +1,23 @@ # Collaboration -As previosuly mentioned there are multiple platforms that can host Git repositeries. Here we will elaborate on two: GitLab and GitHub. +As previously mentioned there are multiple platforms that can host Git repositories. Here we will elaborate on two: GitLab and GitHub. ## 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). +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 repositeries, [branching](/book/installation-and-setup/git-branch.md). and finally [merging branches](/book/installation-and-setup/git-merge.md). +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 repositery on GitLab or Github. This could be on an open repositery on `gitlab.com` or `github.com`. In the context of creating educational books for students at TU Delft, the repositery will most likely be located on `gitlab.tudelft.nl`. +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 smoothely. +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. @@ -28,11 +28,11 @@ There is a slight difference in terminology between GitLab and GitHub. GitLab us ## 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: +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 on the top right corner. +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 @@ -51,4 +51,4 @@ Once the book is ready to be published, a static website can be created through ## 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 and GitLab pages Github and Github pages ca also be used to publish your book. +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. diff --git a/book/workflows/overview.md b/book/workflows/overview.md index 326e50f..434ae2d 100644 --- a/book/workflows/overview.md +++ b/book/workflows/overview.md @@ -5,8 +5,8 @@ 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.
-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`. +There are two web-based platforms that host Git repositories: GitLab and GitHub. You might have read about GitHub Desktop that we are using to manage local repositories. 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`. -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. +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 repository in your own GitLab or GitHub account. diff --git a/book/workflows/publish.md b/book/workflows/publish.md index 6a0de18..ecee4d2 100644 --- a/book/workflows/publish.md +++ b/book/workflows/publish.md @@ -1,6 +1,6 @@ # Publishing your book -Now that we have talked about how you can collaborate using git, its time to explain how the book is actually built. +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 @@ -8,8 +8,8 @@ Now that we have talked about how you can collaborate using git, its time to exp # 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 delpoying the books. It makes sure that the book is always up-to-date and available. +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 repositery (where does the oublish 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. +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