From edbc2a55fc3942b5e7e14b35fe4ef048f43467e0 Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Sat, 22 Feb 2025 10:00:18 +0100 Subject: [PATCH] Move publish part --- book/installation-and-setup/collab.md | 6 +----- book/installation-and-setup/versioning.md | 25 ++++++++++++----------- 2 files changed, 14 insertions(+), 17 deletions(-) diff --git a/book/installation-and-setup/collab.md b/book/installation-and-setup/collab.md index bb236d7..de7f906 100644 --- a/book/installation-and-setup/collab.md +++ b/book/installation-and-setup/collab.md @@ -45,8 +45,4 @@ Additionally, it is advisable to document the branch protection strategy and the - 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. - -## 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 +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. \ No newline at end of file diff --git a/book/installation-and-setup/versioning.md b/book/installation-and-setup/versioning.md index b0ab4ff..ea69afc 100644 --- a/book/installation-and-setup/versioning.md +++ b/book/installation-and-setup/versioning.md @@ -7,24 +7,25 @@ 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 +- Use some sort of semantic versioning with tags - Keep both source code as (export of) websites of archived versions +- Publishing your book more officially ## 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. +When making books for education, typically your book can change substantially for consequential academic years. Using the [](../external/deploy-book-workflow/README.md), you can release the different version of your book all under the same root URL. If you name each students' version of each year to the ``, the students URL includes that academic year too. It is recommended to yearly update the current academic year 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. Eventually, you can add old 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. -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. +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. +Don't forget to explain how you organize these URLs in your README and eventually in the book itself too with a sentence like this: -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. +``` +This is the 2024-2025-version of this book. Go to `` to view the most recent version of this book, or adapt the year in `/` to the year when you took the course. +``` -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. +## Semantic versioning -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). +## Publishing your book with publisher +You can choose to publish your online book with a publisher. This could increase findability of your book, but may have versioning, copyright and licensing consequences -Lastly, add a readme explaining the way you organized branches. - -## TO BE WRITTEN \ No newline at end of file +For TU Delft employees, you can decide to publish 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