diff --git a/book/_toc.yml b/book/_toc.yml index d2b268e..748c41a 100644 --- a/book/_toc.yml +++ b/book/_toc.yml @@ -23,6 +23,7 @@ parts: - file: workflows/overview sections: - file: workflows/collaboration + - file: workflows/publish - file: workflows/githubtemplate - caption: Features chapters: diff --git a/book/installation-and-setup/overview.md b/book/installation-and-setup/overview.md index 1c5bced..1094afc 100644 --- a/book/installation-and-setup/overview.md +++ b/book/installation-and-setup/overview.md @@ -2,14 +2,30 @@ 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 5 types of users. -1. Example Image**Students providing feedback on the published website**. As can already be seen on the [MUDE website](https://mude.citg.tudelft.nl/book/intro.html) an extension has been added that allows students to highlight and annotate sections which they consider important. Through that extension students will also be able to leave feedback about the content or the website for the responsible teacher. +1. **Students providing feedback on the published website**.
+Example Image -2. **Colleague providing feedback on the draft website**. In a similar manner, colleages and team members can leave content related comments on the webiste through that extension. In this way, multiple teachers can give input in the draft of the textbook and course material without requiring and exact understanding of Jupyter Books or GitLab. The responsible teacher (or student assistants) can then make the adaptations to the book as recommended by their colleagues. -3. **Colleague making adjustments in GitLab using single text editor**. This type of user requires only very basic knowledge in GitLab in order to make changes to the website themselves without needing to install any software! Making adjustments using single text editor only requires the user to be able to login into GitLab and edit .md or .ipynb files. The changes can be done directly in the main or publish branch and if a new branch is needed for the changes then the set-up and merging can be taken care of by someone more familiar in GitLab. + As can already be seen on the [MUDE website](https://mude.citg.tudelft.nl/book/intro.html) an extension has been added that allows students to highlight and annotate sections which they consider important. Through that extension students will also be able to leave feedback about the content or the website for the responsible teacher. -4. **Colleague making adjustments to non-interactive content locally**. This user has more knowledge in GitLab than the previous user and can basically take care of branching and merging by themselves. They know how to work with software for editing .md and .ipynb files. They can use the draft book online to view their changed in the book, or build the book locally. The tricky part however is implementing interactive features in the book as they definitely require more knowledge on implementation and testing using a local python server or in the draft version online. +
-5. Example Image**Colleague making adjustments to all content locally**. This user has an understanding of GitLab and can independently make changes on the website built through Jupyter Books. Moreover they have an understanding of various extensions that allows them to make the pages interactive for the student. +2. **Colleague providing feedback on the draft website**.
+ In a similar manner, colleages and team members can leave content related comments on the webiste through that extension. In this way, multiple teachers can give input in the draft of the textbook and course material without requiring and exact understanding of Jupyter Books or GitLab. The responsible teacher (or student assistants) can then make the adaptations to the book as recommended by their colleagues. + +3. **Colleague making adjustments in GitLab using single text editor**.
+ This type of user requires only very basic knowledge in GitLab in order to make changes to the website themselves without needing to install any software! Making adjustments using single text editor only requires the user to be able to login into GitLab and edit .md or .ipynb files. The changes can be done directly in the main or publish branch and if a new branch is needed for the changes then the set-up and merging can be taken care of by someone more familiar in GitLab. + + As an extra step, user 3.5 is a hybrid between type 3 and 4. Basically this user is making changes to individual chapters by editing the .md files locally using, for example, VS Code. Therefore this user requires a little bit more knowledge on git (think of pulling and pushing changes) but their main focus remains to make adjustments to the content of the book by editing .md files whereas user type 4 has more knowledge to make structral changes to the book as well. + +4. **Colleague making adjustments to non-interactive content locally**.
+ This user has more knowledge in GitLab than the previous user and can basically take care of branching and merging by themselves. They know how to work with software for editing .md and .ipynb files. They can use the draft book online to view their changed in the book, or build the book locally. The tricky part however is implementing interactive features in the book as they definitely require more knowledge on implementation and testing using a local python server or in the draft version online. + +5. **Colleague making adjustments to all content locally**.
+Example Image + + This user has an understanding of GitLab and can independently make changes on the website built through Jupyter Books. Moreover they have an understanding of various extensions that allows them to make the pages interactive for the student. + +
**Overview required software** diff --git a/book/workflows/collaboration.md b/book/workflows/collaboration.md index 6da6786..3501fce 100644 --- a/book/workflows/collaboration.md +++ b/book/workflows/collaboration.md @@ -2,17 +2,15 @@ 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). +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). -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`. +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`. 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. @@ -23,6 +21,11 @@ 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. +```{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 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: @@ -46,12 +49,6 @@ When the task is completed, the issue can be closed and you can move on to the n 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 +## GitHub - -```` - - - -(An alternative is to use Github and Github pages to publish your book.?)# \ No newline at end of file +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. diff --git a/book/workflows/publish.md b/book/workflows/publish.md new file mode 100644 index 0000000..6a0de18 --- /dev/null +++ b/book/workflows/publish.md @@ -0,0 +1,15 @@ +# 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. + +# 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 delpoying 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. + +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