diff --git a/book/_toc.yml b/book/_toc.yml index c3a2abe..dcf902e 100644 --- a/book/_toc.yml +++ b/book/_toc.yml @@ -6,7 +6,6 @@ parts: chapters: - file: installation-and-setup/user_types - file: installation-and-setup/git - - file: installation-and-setup/choose_platforms.md - file: installation-and-setup/overview sections: - file: installation-and-setup/vscode-setup @@ -22,6 +21,7 @@ parts: - file: workflows/edit_book - file: workflows/check_changes_online - file: workflows/merge_request + - file: installation-and-setup/organize_team - caption: Features chapters: - file: basic-features/overview diff --git a/book/installation-and-setup/git.md b/book/installation-and-setup/git.md index e99f1f7..6948a84 100644 --- a/book/installation-and-setup/git.md +++ b/book/installation-and-setup/git.md @@ -1,4 +1,4 @@ -# Essential for collaboration: Git +# Collaboration tool: Git ```{admonition} User types :class: tip @@ -19,5 +19,7 @@ GitLab is a cloud-based version control system built around Git. It provides a l GitHub is the same service as GitLab, but it's part of a commercial company (Microsoft). It's the most well-known cloud-based Git provider and provides a lot of functionalities for free for education. It also allows you to host websites on `github.io` eliminating the need for your own / TU Delft webserver, although you don't have full servercontrol. +For first users, we advise you to use GitHub. + ### Additional lessons Software carpentry offers git-lessons if you'd like to learn more than just it's specific use for TeachBooks. The lessons are available [online](https://swcarpentry.github.io/git-novice/) and TU Delft offers these as part of a [Software Carpentry workshop](https://www.tudelft.nl/library/research-data-management/r/training-evenementen/training-voor-onderzoekers/software-carpentry-workshops) \ No newline at end of file diff --git a/book/installation-and-setup/organize_team b/book/installation-and-setup/organize_team new file mode 100644 index 0000000..0d32453 --- /dev/null +++ b/book/installation-and-setup/organize_team @@ -0,0 +1,54 @@ +# Organize your editing team and tools + +```{admonition} User types +:class: tip +This page is useful for user type 3-5. +``` + +If you want to create a collaborative book for students, there's a few agreements you should make to enhance collaboration and student experience. These are written from our own experience, feel free to deviate or provide your own advice! + +**This page is work in progress** + +## Team +- Define who's in charge of: + - Team organization (administrators) + - Combining content (maintainers) + - Editing and reviewing content (editors) +- Define how your review process is taking place. We advice at least a maintainer reviewing each bit o content. +- Make sure people identify themselves as one of the user types. You should have at least one user type 4 or 5. Although this can be a TA, it is advised one of the teachers is comfortable with this user type as well. + +## Tools +- Choose between GitHub and GitLab, as explained below +- If you've chosen for GitHub, start with our [template](../external/template/README.md) +- Define branches in GitHub/GitLab. We advise the following branches: + - A published branch which contains the students' version of this year. This could be called ie. `publish` or `main` or `` + - A development branch which contains all the new content combined but not yet published to students. This could be called `dev` or `main` (depending on whether you prefer having the most recent published version as main or the development branch). + - Branches which will be created during the editing process which contain edits ie. single chapters + - Branches for previous study years which contain each year's version of the book. These could be called `` +- Setup protected branches in GitHub/GitLab to prevent accidental changes +- Add people with GitHub/GitLab permission matching their role and the protected branches. +- Add a readme explaining the way you organized branches and permissions +- Provide explanation on how you'd like to receive feedback in both the readme as the published book. The use of issues (in the book with the issue button) is advised. + +### GitHub vs GitLab + +- Github allows you to host your book on the GitHub server using GitHub pages (to be recognized by the `.github.io/` url, for example the [template book](https://teachbooks.github.io/template/)), which takes all the steps of hosting out of your hands. You can also use a custom owned URL, although this requires some additional skills. On TU Delft's GitLab you need a webserver, which is offered by TeachBooks (to be recognized by the url `teachbooks.tudelft.nl/`, for example [this manual](https://teachbooks.tudelft.nl/jupyter-book-manual)) as the TU Delft OIT team (to be recognized by the url `interactivetextbooks.tudelft.nl/`, for example [the TU Delft OIT demo book](https://interactivetextbooks.tudelft.nl/open-textbooks-demonstration/)). For the TU Delft OIT webserver you’re required to publish your book more officially, it cannot be used for viewing your book online in the editing-phase. +- On GitHub you can start right away with a git environment and online book using our [template](../external/template/README.md). On GitLab you can set up your own git environment, but you need to be given access by [TeachBooks](mailto:teachbooks@tudelft.nl) or [TU Delft OIT](mailto:Interactive-textbooks@tudelft.nl) to view your build book online. +- On GitHub we developed a [automatic process which builds the book and publishes it online](../external/deploy-book-workflow/README.md) in a very flexible way (publication of multiple version of the book, insights in book building errors, parallel so fast build, custom urls in subdirectories). On GitLab both we and other people at TU Delft have a more simplistic workflow which can be used when you're set up on those Git environments and webservers. If you want to use GitLab and make use of the GitHub workflow, you can [mirror your repository to GitHub](https://docs.gitlab.com/ee/user/project/repository/mirror/push.html#set-up-a-push-mirror-from-gitlab-to-github) +- Because we’re in control on the server connected to GitLab, we can set up SSO login for visitors of the website. This is not an option for GitHub because we don’t own the server. +- Both GitLab and GitHub allow for extensive options for visibility of the source code. If you're using GitHub pages, you need a free organization linked to a free eduational account. The TU Delft GitLab requires SSO login for editing the book. Although this is useful for TU Delft employees, it limits the collaboration with people outside of TU Delft. +- GitHub has a nice integration with the [GitHub Desktop application](git-setup_local.md). For GitLab it works as well, but has less functionality. +- [Utteranc.es](../basic-features/utterances.md) requires a GitHub repository to host the discussions. If you're using a GitLab repository, you need a separate GitHub repository and the discussions and book content is not at the same place. + +If you have doubt about this choice, we advise you to start on GitHub. Moving/duplicating your content to GitLab or hosting to a custom URL is always possible at a later stage. + +Here's a table summarizing the information: +| | GitHub | GitLab | +|--|----------|-------------| +| Website to view book online | GitHub pages (`.github.io/`) or custom URL 🌐 | TeachBooks (`teachbooks.tudelft.nl/`) or TU Delft OIT (`interactivetextbooks.tudelft.nl/`) πŸŽ“ | +| Setting up book website | Immediate and automated with [template](../external/template/README.md) ⚑️ | Access required by TeachBooks or TU Delft OIT 🚧 | +| Updating book website | Automated and flexible (multiple version of the book, building error insights, fast, custom urls) πŸš€ | Automated but simplistic (one or two versions, command-line interface) πŸ›΅ | +| Student book access with SSO | Not available for GitHub pages ❌, optional with custom URL βœ… | Optional βœ… | +| Teacher/TA access to Git repository | Private (if part of organization linked to educational account) /public πŸ‘€ | Private / public / internally TU Delft, editing requires requires SSO login πŸ‘₯ | +| GitHub Desktop | Well integrated 😎 | Basic integration πŸ™‚ | +| Utteranc.es | Can be linked to same repository 🏷️ | Requires GitHub repository next to GitLab repository 🏷️🏷️| \ No newline at end of file diff --git a/book/installation-and-setup/overview.md b/book/installation-and-setup/overview.md index 3db5dcc..eb209c9 100644 --- a/book/installation-and-setup/overview.md +++ b/book/installation-and-setup/overview.md @@ -1,5 +1,10 @@ # Install & authenticate required software +```{admonition} User types +:class: tip +This page is useful for user type 4-5. +``` + Now that the types of users have been explained, you might have an idea which type corresponds to you! The following table will link the relevant installation and setup steps for you. diff --git a/book/workflows/collaboration.md b/book/workflows/collaboration.md index 46536fe..08496da 100644 --- a/book/workflows/collaboration.md +++ b/book/workflows/collaboration.md @@ -7,7 +7,7 @@ This page is useful for user type 3, 4 and 5. A jupyter book is composed out of many 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. -We have previously introduced the notions of using Git in the online environment (remote) or locally. All the (text, figures, etc.) 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` or `github.com/teachbooks`. +We have previously introduced the notions of using Git in the online environment (remote) or locally. All the (text, figures, etc.) 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` or `github.com/teachbooks`. If this is the first time you interact with books, you're advise to use `github.com`. The steps involved are as follows: