diff --git a/book/_toc.yml b/book/_toc.yml index c4c8733..d745c73 100644 --- a/book/_toc.yml +++ b/book/_toc.yml @@ -12,6 +12,8 @@ parts: chapters: - file: installation-and-setup/user_types.md - file: installation-and-setup/git.md + sections: + - file: installation-and-setup/tools - file: installation-and-setup/overview.md sections: - file: installation-and-setup/vscode-setup.md @@ -27,7 +29,7 @@ parts: - file: workflows/check_changes_online.md - file: workflows/merge_request.md - file: installation-and-setup/collab - - file: installation-and-setup/tools + - file: installation-and-setup/versioning - file: installation-and-setup/copyright.md sections: - file: installation-and-setup/copyright/considerations diff --git a/book/installation-and-setup/collab.md b/book/installation-and-setup/collab.md index 1742531..eccb53d 100644 --- a/book/installation-and-setup/collab.md +++ b/book/installation-and-setup/collab.md @@ -13,11 +13,29 @@ Finally, ensure that team members identify themselves according to the user type ## 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. +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. 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 [repository button {fa}`github`, suggest edit {fa}`pencil` and issue button {fa}`lightbulb`](https://jupyterbook.org/en/stable/basics/repository.html) is advised. + +## Book previews of contributions +Using the [](../external/deploy-book-workflow/README.md), it's very easy to show a preview of the changes for branches within the same repository. Using [](../features/pull_request_build.md) you allow previews of changes for forks of your repository too. + +Add the way you organized branches and builds in your README. + +## 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 advised 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. We would advise a [ruleset](https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/managing-rulesets/creating-rulesets-for-a-repository): +- Bypassable by repository admins +- Targeting default branch +- Restrict deletions +- Require a pull request before merging with 1 required approval +- Block force pushes ## 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 or DOI number, and registration in several shared databases but limits the amount of changes you can make to your book: for substantial changes a new published version is needed with an updated copyright checks. Small changes like typos can always be made, which are processed in the published version every hour. +## For TU Delft employees: publishing via TU Delft OPEN interactive textbooks +Decide on whether or not to publish your book via TU Delft OPEN interactive textbooks. Publishing will give you a copyright check, ISBN or DOI number, and registration in several shared databases but limits the amount of changes you can make to your book: for substantial changes a new published version is needed with an updated copyright checks. Small changes like typos can always be made, which are processed in the published version every hour. In case of editing a book for a course during that actual course and/or your book has limited value outside your course's content, we advise you only to publish an archived version of your book whenever the academic year is over. \ No newline at end of file diff --git a/book/installation-and-setup/git.md b/book/installation-and-setup/git.md index 6948a84..b9559d2 100644 --- a/book/installation-and-setup/git.md +++ b/book/installation-and-setup/git.md @@ -5,15 +5,12 @@ This page is useful for user type 3-5. ``` -You'll need to interact with Git to collaborate on TeachBooks, but what is this thing? +You'll need to interact with Git to collaborate on TeachBooks. You've been introduced to it in the [exercises in the template](../intro/template.md) and you'll be guided through all of the steps in detail in [](../workflows/collaboration.md), but what is this thing? ## What is Git? Git is a version control system (VCS), used by a wide variety of engineers and software developers to work on projects in parallel together. It provides multiple benefits such as tracking changes to files, working side by side with other people, and the ability to rollback to previous versions of files without losing track of newer changes. It is a free and open sources software. -### What is GitLab? - -GitLab is a cloud-based version control system built around Git. It provides a lot more features such as Issues, Merge Requests, CI/CD pipelines, etc. TU Delft has a license to use GitLab on our own local webservers—this means that all of the files are stored digitally on the TU Delft campus, rather than some unkown webserver that could be physically located in an unsafe location. This is also why we have our “own” GitLab located at gitlab.tudelft.nl, rather than the “normal” GitLab at gitlab.com. ### What is GitHub? @@ -21,5 +18,10 @@ GitHub is the same service as GitLab, but it's part of a commercial company (Mic For first users, we advise you to use GitHub. +### What is GitLab? + +GitLab is a cloud-based version control system built around Git. It provides a lot more features such as Issues, Merge Requests, CI/CD pipelines, etc. TU Delft has a license to use GitLab on our own local webservers—this means that all of the files are stored digitally on the TU Delft campus, rather than some unkown webserver that could be physically located in an unsafe location. This is also why we have our “own” GitLab located at gitlab.tudelft.nl, rather than the “normal” GitLab at gitlab.com. + + ### 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/tools.md b/book/installation-and-setup/tools.md index a733957..52479a6 100644 --- a/book/installation-and-setup/tools.md +++ b/book/installation-and-setup/tools.md @@ -1,4 +1,4 @@ -# Choose URLs and tools +# Which git provider to choose ```{admonition} User types :class: tip @@ -7,41 +7,7 @@ This page is useful for user type 4-5. The setup of tools and URLs is dependent on agreements you've made on [collaboration](./collab.md). -## 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 one 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 ``. 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 ``, 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. - -We advise you to enable two options in the general repository setting regarding pull requests in GitHub: -- Enable `Always suggest updating pull request branches`, suggesting a merge from the default branch into any separate branch before merging into main. -- Enable `Automatically delete head branches` to delete branches after they are merged (you'll still be able to restore those). - -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 advised 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. We would advise a [ruleset](https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/managing-rulesets/creating-rulesets-for-a-repository): -- Bypassable by repository admins -- Targeting default branch -- Restrict deletions -- Require a pull request before merging with 1 required approval -- Block force pushes - -## 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. +Choosing between GitHub and GitLab depends on multiple criteria. GitHub provides more functionalities, but you might prefer the TU Delft-closed GitLab system if you're a TU Delft employee. ### Book URL 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. 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. diff --git a/book/installation-and-setup/user_types.md b/book/installation-and-setup/user_types.md index c7f11e3..7eb516e 100644 --- a/book/installation-and-setup/user_types.md +++ b/book/installation-and-setup/user_types.md @@ -60,7 +60,7 @@ class: dark-light ``` -User 4 is a hybrid between type 3 and 5. Basically this user is making changes 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 5 has more knowledge to make changes to python files the book as well. This user can build the book online and therefore does not need to have special software installed besides a text editor (e.g., Python is not required). +User 4 is a hybrid between type 3 and 5. Basically this user is making changes 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 5 has more knowledge to make changes to python files the book as well. This user can build the book online and therefore does not need to have special software installed besides a text editor (e.g., Python is not required). Using this skills, this user type can take the role as editor, managing more than just book content. ## User type 5: Colleague making adjustments and incorporating them in the book locally @@ -74,7 +74,7 @@ class: dark-light ``` -This user has more knowledge in GitLab/GitHub than the previous user and can take care of branching and merging directly. They know how to work with software for editing .md and .ipynb files. They can use the Deploy Book Workflow online to view their changes in the book and coordinate peer review, and/or build the book locally. +This user has more knowledge in GitLab/GitHub than the previous user and can take care of branching and merging directly. They know how to work with software for editing .md and .ipynb files. They can use the Deploy Book Workflow online to view their changes in the book and coordinate peer review, and/or build the book locally. This user can easily take the role as editor, and might even add additional features to the book. If you do so, please share those on the [TeachBooks-community](https://github.com/teachbooks) so that other people can benefit and contribute to your tooling. ```{Note} diff --git a/book/installation-and-setup/versioning.md b/book/installation-and-setup/versioning.md new file mode 100644 index 0000000..b0ab4ff --- /dev/null +++ b/book/installation-and-setup/versioning.md @@ -0,0 +1,30 @@ +# Versioning and URLs + +```{admonition} User types +:class: tip +This page is useful for user type 4-5. +``` + +Online books can be easily updated, however, this might confuse readers. Therefore, it's good practice to be aware of this and, where needed, provide explicit version to the readers. It's recommended to do this in multiple ways, which can be combined: +- Publish versions on separate (fixed) URLs +- Use some sort of semantic versioning +- Keep both source code as (export of) websites of archived versions + +## Publish version on separate (fixed) URLs +When making books for education, typically your book can change substantially for consequential academic years. If there's many people working on different parts of the book and material is staged for publication to stduents, we recommend using at least two separate branches, one which is released to students, the other one for development. Using the [](../external/deploy-book-workflow/README.md), it's very easy to share multiple versions of your book on the same root-URL. + +Firstly, create a release branch which contains the students' version of this year. This branch could be named `release`, `main`, or ``. 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`, `main`, `-draft`. 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 ``, 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. + +We advise you to enable two options in the general repository setting regarding pull requests in GitHub: +- Enable `Always suggest updating pull request branches`, suggesting a merge from the default branch into any separate branch before merging into main. +- Enable `Automatically delete head branches` to delete branches after they are merged (you'll still be able to restore those). + +Lastly, add a readme explaining the way you organized branches. + +## TO BE WRITTEN \ No newline at end of file