admin2/manual_teachbooks
1
0
Fork 0
mirror of https://github.com/TeachBooks/manual.git synced 2026-11-12 22:35:51 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions

splitted organize team and extended collab

Browse source
This commit is contained in:
Tom van Woudenberg 2024-10-28 10:09:31 +01:00
parent cfdd56d035
commit 475c3204f5
4 changed files with 98 additions and 75 deletions
Download patch file Download diff file Expand all files Collapse all files

3
book/_toc.yml
View file

@ -22,6 +22,9 @@ parts:
- file: workflows/check_changes_online
- file: workflows/merge_request
- file: installation-and-setup/organize-team
sections:
- file: installation-and-setup/collab
- file: installation-and-setup/tools
- file: installation-and-setup/creating_content.md
- caption: Features
chapters:

17
book/installation-and-setup/collab.md Normal file
View file

@ -0,0 +1,17 @@
# Team and collaboration
## Roles and responsibilities
To ensure smooth collaboration, it is essential to define the roles and responsibilities within your team. Firstly, designate who will be in charge of team organization ('administrators') who should be at least user type 4. Additionally, assign 'maintainers' responsible for combining content, also requiring at least user type 4. 'Editors' should be identified for editing and reviewing content, requiring at least user type 3.
Finally, ensure that team members identify themselves according to the user types. It is crucial to have at least one user type 4 or 5 on the team. While this role can be filled by a teaching assistant (TA), it is recommended that one of the teachers is also comfortable with this user type to provide adequate support and oversight.
## Review process
Furthermore, establish a clear editing and review process.
For the editing process, establish some practical rules on whether to use issues, branches and forks for adding content, fixing typos or making other changes. Furthermore, it can help to write down when you expect (draft) merge/pull requests and how to use the assign and review options in GitHub/GitLab. It is advisable to have at least a maintainer review each piece of content to maintain quality and consistency.
## Private, internally or public
Choose whether you want to share your source code and built book privately, internally or publicly. In any case, you need to obey copyright-rules. We advise public repositories and books in line with a vision on open education.
## Publishing via Open Interactive Textbooks TU Delft
Decide on whether or not to publish your book via Open Interactive Textbooks TU Delft. Publishing will give you a copyright check, ISBN, DOI number, and registration in several shared databases but heavily limits the amount of changes you can make to your book. In case of editing a book for a course during that actual course and if your book is worth publishing outside of your course's content, we advise only publishing an archived version of your book whenever the academic year is over.

76
book/installation-and-setup/organize-team.md
View file

@ -5,78 +5,4 @@
This page is useful for user type 4-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!
## Team
- Define who's in charge of:
- Team organization (administrators), at least user type 4
- Combining content (maintainers), at least user type 4
- Editing and reviewing content (editors)
- Define how your review process is taking place. We advice at least a maintainer reviewing each bit of 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
- Choose whether to host your git repository in your private account or from a share teams (groups in GitLab, organization in GitHub). For GitHub this influences your book web url as well, as it hold your username or organization name. For courses we therefore advise you to create a organization with the course name. Furthermore, on GitHub a private repository has a limited amount of actions-minutes required for published your book. On GitLab, the choice for private or public doesn't influence your web url and the amount of computing power available as that requires you to set up a server yourself.
- Choose whether to have your git repository public or private (independent of whether your book website is public or private). If you'd like a private repo on GitHub, apply for a GitHub Team (free as a teacher as described in the [github documentation](https://docs.github.com/en/education/explore-the-benefits-of-teaching-and-learning-with-github-education/github-education-for-teachers/about-github-education-for-teachers#github-education-features-for-teachers)). If you've a organization for your book on github, link your GitHub team rights to your organization as described on the [github website](https://github.com/team#organizations)
- 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 release branch which contains the students' version of this year. This could be called ie. `release` or `main` or `<current acadamic year>`. Add this branch as the `PRIMARY BRANCH` when making use of the [github workflow](gh-workflow-settings), this will make sure students are redirected to this URL which doesn't move when adding new versions of the book later on. If you plan on keeping only one public version, it's advised to set `BEHAVIOR_PRIMARY` from the default `redirect` to `copy` which makes sure the primary branch is copied to root so that the URL is compact.
- A development branch which contains all the new content combined but not yet published to students. This could be called ie. `dev` or `main`. `dev` is advised when you prefer git's default branch to be the most recent published version (as `main` is expected to be the default branch by many).
- Branches which will be created during the editing process, which is probably something which you want to allow. As long as `BRANCHES_TO_DEPLOY` is set to the default `*`, all branches are build and your fellow editors can review their own and each other's versions online. Once every while, it doesn't hurt to go through the list of branches and delete any branches which are merged but not deleted.
- Branches for previous study years which contain each year's version of the book. These could be called `<academic year>` which ends up in their url too. Add these branches to the list of `BRANCHES_ARCHIVED` when making use of the [github workflow](gh-workflow-settings) to add a banner to the page indicating it's archived state.
- 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.
- Decide on whether or not to publish your book via Open Interactive Textbooks TU Delft. Publishing will give you a copyright check, ISBN, DOI number, and registration in several shared databases but heavily limits the amount of changes you can make to your book. In case of editing a book for a course during that actual course, we advise publishing an archived version of your book whenever the academic year is over.
### GitHub vs GitLab
#### Book URL
Github allows you to host your book on the GitHub server using GitHub pages (to be recognized by the `<organization/username>.github.io/<book>` url, for example the [template book](https://teachbooks.github.io/template/)), which takes all the steps of hosting out of your hands. If you're book is part of the [GitHub Enterprise TU Delft](https://github.com/enterprises/tudelft) and is using SSO, a random url is generated `<random>.github.io/<book>`. Next to GitHub-provided URLs, you can set up a custom owned URL, although this requires some additional skills on a domain which you should own.
On TU Delft's GitLab you need a webserver, which is offered by TeachBooks (to be recognized by the url `teachbooks.tudelft.nl/<book>`, 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/<book>`, for example [the TU Delft OIT demo book](https://interactivetextbooks.tudelft.nl/open-textbooks-demonstration/)).
#### Real-time editing book
Editing the book can happen both locally as online on GitHub/GitLab. If done locally, the book can be generated and viewed locally too (typically takes around 1 minute) but this requires you to be at least user type 4 or 5 depending on the book content. The built book can also be viewed online separate from the released version.
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 but still want to 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). 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 an active editing-phase since constant copyright checks have to be performed.
#### Setting up book repository and website
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.
#### Book access with SSO
When you’re releasing your book on a server on which you're in control (connected to GitLab or GitHub), you can set up SSO login for visitors of the website. This can be arranged for on the TeachBooks server.
If you want the same functionality with GitHub pages, your book should be part of the [GitHub Enterprise of TU Delft](https://github.com/enterprises/tudelft). This SSO login is a bit different as you're required to give access to specific accounts. Furthermore, the url of you're book on GitHub pages is a random one, so you might consider using a custom URL.
#### Access to source code
Both GitLab and GitHub allow for extensive options for visibility of the source code, both private, public or internally. On GitHub, public allows for collaboration with anyone. For SSO login, your book should be part of the [GitHub Enterprise of TU Delft](https://github.com/enterprises/tudelft)
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.
#### Integration with GitHub Desktop
GitHub has a nice integration with the [GitHub Desktop application](git-setup_local.md). For GitLab it works as well, but has less functionality.
#### Intergration with Utteranc.es
[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.
#### Summary
Here's a table summarizing the information:
| | GitHub | GitLab |
|--|----------|-------------|
| Book url | GitHub pages (`<organization/username>.github.io/<book>`), for TU Delft GitHub Enterprise with SSO a random URL (`<random>.github.io/<book>`), or custom url `<anything>.<anything>/<book>`> 🌐 | TeachBooks (`teachbooks.tudelft.nl/<book>`) or TU Delft OIT (`interactivetextbooks.tudelft.nl/<book>`) 🎓 |
| Real-time book editing | Automated and flexible (multiple version of the book, building error insights, fast, custom urls) 🚀 | Automated but simplistic (one or two versions, command-line interface) 🛵 For TU Delft OIT: restricted adaptations because of copyright checks 🚫 |
| Setting up book website | Immediate and automated with [template](../external/template/README.md) ⚡️ | Manual setup on personal webserver, or access required by TeachBooks or TU Delft OIT 🚧 |
| Book access with SSO | Only available for GitHub pages on GitHub Enterprise of TU Delft ❌, optional with custom URL ✅ | Optional ✅ |
| Access to source code | Private (if part of organization linked to educational account) /public / internally TU Delft (on GitHub Enterprise of TU Delft) 👥 | Private / public (read-only) / 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 🏷️🏷️|
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.
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! A distinction has been made between organization of teams and tools.

77
book/installation-and-setup/tools.md Normal file
View file

@ -0,0 +1,77 @@
# Tools
The setup of tools is dependent on agreement you've made.
## Collaboration in readme
Provide explanation on how you organize the book-editing and how you'd like to receive feedback in both the readme as the published book. The use of the [issue button](https://jupyterbook.org/en/stable/basics/repository.html#add-a-button-to-open-issues) is advised for the published book.
## Branches for separate versions
We recommend using at least two separate branches, one which is released to students, the other on for development. If you're planning adapting the book every year, you should set up your branches in such a way that students will always receive the version they should expect.
Firstly, create a release branch which contains the students' version of this year. This branch could be named `release`, `main`, or `<current academic year>`. It is recommended to set this branch as the `PRIMARY BRANCH` when using the [GitHub workflow](gh-workflow-settings). This ensures that students are redirected to a consistent URL, even when new versions of the book are added later. If you plan on maintaining only one public version, it is advisable to set `BEHAVIOR_PRIMARY` from the default `redirect` to `copy`. This ensures that the primary branch is copied to the root, making the URL more compact.
Next, establish a development branch that contains all the new content combined but not yet published to students. This branch could be named `dev` or `main`. Using `dev` is recommended if you prefer the default branch to be the most recent published version, as `main` is commonly expected to be the default branch.
Additionally, allow the creation of branches during the editing process. As long as `BRANCHES_TO_DEPLOY` is set to the default `*`, all branches will be built, enabling fellow editors to review their own and each other's versions online. Periodically, it is beneficial to review the list of branches and delete any that have been merged but not deleted.
Eventually, create branches for previous study years, each containing that year's version of the book. These branches could be named `<academic year>`, which will also be reflected in their URLs. Add these branches to the list of `BRANCHES_ARCHIVED` when using the [GitHub workflow](gh-workflow-settings) to include a banner on the page indicating its archived state.
Lastly, add a readme explaining the way you organized branches.
## Protect branches
To ensure the integrity of your book's content, it is crucial to set up protected branches in both GitHub and GitLab. Protected branches prevent accidental changes and ensure that only authorized modifications are made. In GitHub, you can configure branch protection rules by navigating to the repository settings, selecting "Branches," and then adding branch protection rules for the branches you want to protect. Similarly, in GitLab, you can protect branches by going to the repository settings, selecting "Repository," and then configuring the branch protection settings.
Once the branches are protected, it is essential to assign appropriate permissions to team members based on their roles. In GitHub, you can manage permissions by navigating to the repository settings, selecting "Manage access," and then inviting collaborators with specific roles such as "Admin," "Write," or "Read." In GitLab, permissions can be managed by going to the project settings, selecting "Members," and then adding users with roles like "Maintainer," "Developer," or "Reporter."
Additionally, it is advisable to document the branch protection strategy and the assigned permissions in the readme file. This documentation should explain the rationale behind the branch protection rules and provide clear instructions on how team members can request access or permission changes. By doing so, you create a transparent and organized workflow that facilitates collaboration and minimizes the risk of unauthorized changes.
## GitHub vs GitLab
Choosing between GitHub and GitLab depends on multiple criteria. GitHub provides more functionalities, but you might prefer the TU Delft-closed GitLab system.
### Book URL
Github allows you to host your book on the GitHub server using GitHub pages (to be recognized by the `<organization/username>.github.io/<book>` url, for example the [template book](https://teachbooks.github.io/template/)), which takes all the steps of hosting out of your hands. If you're book is part of the [GitHub Enterprise TU Delft](https://github.com/enterprises/tudelft) and is using SSO, a random url is generated `<random>.github.io/<book>`. Next to GitHub-provided URLs, you can set up a custom owned URL, although this requires some additional skills on a domain which you should own. For courses we advise you to create a organization with the course name so that the URL represent that course.
On TU Delft's GitLab you need a webserver, which is offered by TeachBooks (to be recognized by the url `teachbooks.tudelft.nl/<book>`, 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/<book>`, for example [the TU Delft OIT demo book](https://interactivetextbooks.tudelft.nl/open-textbooks-demonstration/)).
### Real-time editing book
Editing the book can happen both locally as online on GitHub/GitLab. If done locally, the book can be generated and viewed locally too (typically takes around 1 minute) but this requires you to be at least user type 4 or 5 depending on the book content. The built book can also be viewed online separate from the released version.
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). For a private repository, there is an extensive but limited amount of actions-minutes required for published your book. If this proves to be a limit, consider applying for [Teacher benefits](https://docs.github.com/en/education/explore-the-benefits-of-teaching-and-learning-with-github-education/github-education-for-teachers/about-github-education-for-teachers#github-education-features-for-teachers) or joining the [GitHub Enterprise of TU Delft](https://github.com/enterprises/tudelft).
On GitLab a webserver is required to process book-changes online. Both we and other people at TU Delft have a simplistic workflow which can be used when you're set up on those Git environments and webservers. If you want to use GitLab but still want to 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). 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 an active editing-phase since constant copyright checks have to be performed. The amount of computing power available is dependent on how you set the server yourself.
### Setting up book repository and website
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.
### Book access with SSO
When you’re releasing your book on a server on which you're in control (connected to GitLab or GitHub), you can set up SSO login for visitors of the website. This can be arranged for on the TeachBooks server.
If you want the same functionality with GitHub pages, your book should be part of the [GitHub Enterprise of TU Delft](https://github.com/enterprises/tudelft). This SSO login is a bit different as you're required to give access to specific accounts. Furthermore, the url of you're book on GitHub pages is a random one, so you might consider using a custom URL.
### Access to source code
Both GitLab and GitHub allow for extensive options for visibility of the source code, both private, public or internally. On GitHub, public allows for collaboration with anyone. For SSO login, your book should be part of the [GitHub Enterprise of TU Delft](https://github.com/enterprises/tudelft). If you'd like a private repo on GitHub, apply for a GitHub Team (free as a teacher as described in the [github documentation](https://docs.github.com/en/education/explore-the-benefits-of-teaching-and-learning-with-github-education/github-education-for-teachers/about-github-education-for-teachers#github-education-features-for-teachers)) to make use of GitHub pages (for public repos GitHub pages is not restricted).
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.
### Integration with GitHub Desktop
GitHub has a nice integration with the [GitHub Desktop application](git-setup_local.md). For GitLab it works as well, but has less functionality.
### Intergration with Utteranc.es
[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.
### Summary
Here's a table summarizing the information:
| | GitHub | GitLab |
|--|----------|-------------|
| Book url | GitHub pages (`<organization/username>.github.io/<book>`), for TU Delft GitHub Enterprise with SSO a random URL (`<random>.github.io/<book>`), or custom url `<anything>.<anything>/<book>`> 🌐 | TeachBooks (`teachbooks.tudelft.nl/<book>`) or TU Delft OIT (`interactivetextbooks.tudelft.nl/<book>`) 🎓 |
| Real-time book editing | Automated and flexible (multiple version of the book, building error insights, fast, custom urls) 🚀 | Automated but simplistic (one or two versions, command-line interface) 🛵 For TU Delft OIT: restricted adaptations because of copyright checks 🚫 |
| Setting up book website | Immediate and automated with [template](../external/template/README.md) ⚡️ | Manual setup on personal webserver, or access required by TeachBooks or TU Delft OIT 🚧 |
| Book access with SSO | Only available for GitHub pages on GitHub Enterprise of TU Delft ❌, optional with custom URL ✅ | Optional ✅ |
| Access to source code | Private (if part of organization linked to educational account) /public / internally TU Delft (on GitHub Enterprise of TU Delft) 👥 | Private / public (read-only) / 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 🏷️🏷️|
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.