From ac7051fc8757b875bc5a4daeeda5406fcc0ea745 Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Sat, 22 Feb 2025 10:56:59 +0100 Subject: [PATCH 01/32] Update versioning.md --- book/installation-and-setup/versioning.md | 56 ++++++++++++++++++++++- 1 file changed, 55 insertions(+), 1 deletion(-) diff --git a/book/installation-and-setup/versioning.md b/book/installation-and-setup/versioning.md index 5899a4d..ae4cda3 100644 --- a/book/installation-and-setup/versioning.md +++ b/book/installation-and-setup/versioning.md @@ -8,7 +8,7 @@ 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 with tags -- Keep both source code as (export of) websites of archived versions +- Keep both source code as (export of) websites of all versions - Publishing your book more officially ## Publish version on separate (fixed) URLs @@ -23,6 +23,60 @@ Don't forget to explain how you organize these URLs in your README and eventuall If you've many version of the book, at some point you might reach the 1 GB GitHub Pages limit. This is only expected for extremely large books with a lot of non-text-based (binary) content. To prevent going over that limit, store large content not used for building the website (like images) on an external server. This can be another GitHub repository or a (paid) object store ## Semantic versioning +Semantic versioning is used extensively in the world of software management to deal with versions. This is more suited than the more traditional way of versioning paper books (version 1, 2, etc.), because of the amount of edits which online books allow. There's [guidelines](https://semver.org/) about how to use a 'x.y.z' version numbers for software, for which we propose the following alternative for books: + +1. A normal version number MUST take the form X.Y.Z where X, Y, and Z are non-negative integers, and MUST NOT contain leading zeroes. X is the major version or yearly version, Y is the minor version, and Z is the patch version. Each element MUST increase numerically. For instance: 1.9.0 -> 1.10.0 -> 1.11.0. or 2025.9.0 -> 2025.10.0 -> 2025.11.0 +2. Once a versioned book has been released, the contents of that version MUST NOT be modified. Any modifications MUST be released as a new version. +3. Major version zero (0.y.z) is for initial development. Anything MAY change at any time. The book content should not be shared with readers as it's not considers as stable. +4. Version 1.0.0 defines the first released book. The way in which the version number is incremented after this release should be explained in the README of the source code and in the book itself. +5. Patch version Z (x.y.Z | x > 0) MUST be incremented if a small change is made which should be communicated to the reader in both the source code and in the book itself. If the small change is not crucial (like a simple typo), you might consider not defining it as a new version but combining it with other changes in the next version. +6. Minor version Y (x.Y.z | x > 0) MUST be incremented if a big change / addition is made to the book. It MUST be communicated in both the source code and in the book itself. It MAY include patch level changes. Patch version MUST be reset to 0 when minor version is incremented. +7. Major version X (X.y.z | X > 0) MUST be incremented if a substantial restructure is made to the book. A new academic year is a great example for this. It MUST be communicated in both the source code and in the book itself. It MAY also include minor and patch level changes. Patch and minor versions MUST be reset to 0 when major version is incremented. +8. Precedence refers to how versions are compared to each other when ordered. + 1. Precedence MUST be calculated by separating the version into major, minor, patch and pre-release identifiers in that order. + 2. Precedence is determined by the first difference when comparing each of these identifiers from left to right as follows: Major, minor, and patch versions are always compared numerically. Example: 1.0.0 < 2.0.0 < 2.1.0 < 2.1.1. + +### Changelog +To communicate changes, we advise creating a changelog in the book. The [template](https://github.com/TeachBooks/template/blob/main/book/changelog.md) contains an example: + +```md +# Changelog + +## ``: `` +- `` [](``) +- ... +- Full Changelog: `[...]()' + +## ``: <...> +- <...> + +<...> +``` + +### Implement tags and releases +Tags can be added to your source code by adding the version number as a tag to a specific commit. You can do so only locally. In GitHub Desktop this is done by clicking 'Create Tag...` for a specific commit in the History tab. + +```{figure} figures/tags.png +--- +width: 300px +align: center +--- + +``` + +Once the tags is pushed to GitHub/GitLab. You can create a release of the version by clicking `Release` on the `Code` page of your repository. There you can select a tag and generate release notes. It's recommended to add the relevant part of the changelog too. An example can be found [here](https://github.com/CIEM5000-2025/book/releases/tag/v2025.2.0) + +## Keep source code and website of all versions +Although you might only want to share the most recent version of the book with your readers, it might be useful too the have the source code and website of older versions somewhere too. + +Git allows you to go back in the git history to the source code of old versions. To make this as easy as possible for readers, use tags and releases instead of having the readers scroll through a long list of (not alway very descriptive) commit descriptions. + +To share the built book / website of old versions for your book on GitHub you've a few options: +- add a zip of the built book to the release in GitHub as binary asset. This requires readers to download the zip and open the html files locally, but doesn't require you to host it somewhere. This zip can be easily downloaded as an artifact from [the GitHub action](../external/deploy-book-workflow/README.md). An example can be found [here](https://github.com/TUDelft-books/CME4501/releases/tag/v2024.1.0) +- create a branch for each tag. When doing this, [the GitHub workflow](../external/deploy-book-workflow/README.md) will build it on GitHub pages. It's advised to use the version as branch name. You can create a branch from a tag locally by running: `git branch `. Note that when you've many version and a large book, this approach might easily fill up your 1 GB GitHub pages limit. +- Use [Read the Docs](../features/pull_request_build.md) to build a website for all your tags. Refer to the URL of this built from your GitHub release. To enable this functionality in Read the Docs, apply the following settings in [your Read the Docs dashboard](https://app.readthedocs.org/dashboard/): go to `Setup` - `Settings` - `Automation rules` - `Add rule` and set `Description`: 'Build all tags', `Match`: `Custom Match`, `Custom match`: `.*`, `Version type`: `Tag`, `Action`: `Activate version` + +If you've your own webserver, you can publish each version on it manually. ## 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 From 5d253d440ca6ecc636e540b02093a73514c82678 Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Sat, 22 Feb 2025 11:09:44 +0100 Subject: [PATCH 02/32] Add reference --- book/credits.md | 1 + book/installation-and-setup/versioning.md | 4 +++- book/references.bib | 10 +++++++++- 3 files changed, 13 insertions(+), 2 deletions(-) diff --git a/book/credits.md b/book/credits.md index 7a22754..c74d628 100644 --- a/book/credits.md +++ b/book/credits.md @@ -60,6 +60,7 @@ The following pages contain content written by others, part of has been reused a - Pages {ref}`copyright` and {ref}`copyright_considerations` include text from {cite:t}`tud_cip_24` that is used in the copyright checklist items. Original content licensed under CC BY. - Page {ref}`copyright_licenses`: {numref}`Figure %s` is included unmodified, along with paraphrased and quoted text (including hyperlinks) from {cite:t}`hall21`. Work is licensed under CC BY. - Page {ref}`copyright_licenses`: {numref}`Figure %s` is included unmodified. Work is provided by Kennisland under a CC0 license. Accessed at [](https://wiki.creativecommons.org/wiki/File:CC_License_Compatibility_Chart.png) on December 17, 2024. +- page [](./installation-and-setup/versioning.md): include text from {cite:t}`semver` that has been modified. Original content licensed under CC BY 3.0. diff --git a/book/installation-and-setup/versioning.md b/book/installation-and-setup/versioning.md index ae4cda3..94c435e 100644 --- a/book/installation-and-setup/versioning.md +++ b/book/installation-and-setup/versioning.md @@ -1,5 +1,7 @@ # Versioning and URLs +> This page reuses adapted CC BY 3.0 content from Tom Preston-Werner {cite:p}`semver`. {fa}`quote-left`{ref}`Find out more here.` + ```{admonition} User types :class: tip This page is useful for user type 4-5. @@ -23,7 +25,7 @@ Don't forget to explain how you organize these URLs in your README and eventuall If you've many version of the book, at some point you might reach the 1 GB GitHub Pages limit. This is only expected for extremely large books with a lot of non-text-based (binary) content. To prevent going over that limit, store large content not used for building the website (like images) on an external server. This can be another GitHub repository or a (paid) object store ## Semantic versioning -Semantic versioning is used extensively in the world of software management to deal with versions. This is more suited than the more traditional way of versioning paper books (version 1, 2, etc.), because of the amount of edits which online books allow. There's [guidelines](https://semver.org/) about how to use a 'x.y.z' version numbers for software, for which we propose the following alternative for books: +Semantic versioning is used extensively in the world of software management to deal with versions {cite:p}`semver`. This is more suited than the more traditional way of versioning paper books (version 1, 2, etc.), because of the amount of edits which online books allow. There's [guidelines](https://semver.org/) about how to use a 'x.y.z' version numbers for software, for which we propose the following alternative for books: 1. A normal version number MUST take the form X.Y.Z where X, Y, and Z are non-negative integers, and MUST NOT contain leading zeroes. X is the major version or yearly version, Y is the minor version, and Z is the patch version. Each element MUST increase numerically. For instance: 1.9.0 -> 1.10.0 -> 1.11.0. or 2025.9.0 -> 2025.10.0 -> 2025.11.0 2. Once a versioned book has been released, the contents of that version MUST NOT be modified. Any modifications MUST be released as a new version. diff --git a/book/references.bib b/book/references.bib index bda464b..3b54aed 100644 --- a/book/references.bib +++ b/book/references.bib @@ -133,4 +133,12 @@ url = {https://github.com/TeachBooks/Sphinx-Named-Colors}, year = {2024}, note = {Retrieved January 2025. MIT.} -} \ No newline at end of file +} + +@misc{semver, + author = {Tom Preston-Werner}, + title = {Semantic Versioning specification}, + url = {https://semver.org/}, + year = {2025}, + note = {Retrieved February 2025. CC BY 3.0.} +} From a111b4bbc2e2d1c2da2167f35a1a791390665fd1 Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Sat, 22 Feb 2025 11:14:10 +0100 Subject: [PATCH 03/32] final --- book/credits.md | 2 +- book/installation-and-setup/versioning.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/book/credits.md b/book/credits.md index c74d628..ef9cdf1 100644 --- a/book/credits.md +++ b/book/credits.md @@ -60,7 +60,7 @@ The following pages contain content written by others, part of has been reused a - Pages {ref}`copyright` and {ref}`copyright_considerations` include text from {cite:t}`tud_cip_24` that is used in the copyright checklist items. Original content licensed under CC BY. - Page {ref}`copyright_licenses`: {numref}`Figure %s` is included unmodified, along with paraphrased and quoted text (including hyperlinks) from {cite:t}`hall21`. Work is licensed under CC BY. - Page {ref}`copyright_licenses`: {numref}`Figure %s` is included unmodified. Work is provided by Kennisland under a CC0 license. Accessed at [](https://wiki.creativecommons.org/wiki/File:CC_License_Compatibility_Chart.png) on December 17, 2024. -- page [](./installation-and-setup/versioning.md): include text from {cite:t}`semver` that has been modified. Original content licensed under CC BY 3.0. +- page [](./installation-and-setup/versioning.md): includes text from {cite:t}`semver` that has been modified. Original content licensed under CC BY 3.0. diff --git a/book/installation-and-setup/versioning.md b/book/installation-and-setup/versioning.md index 94c435e..1906b30 100644 --- a/book/installation-and-setup/versioning.md +++ b/book/installation-and-setup/versioning.md @@ -1,6 +1,6 @@ # Versioning and URLs -> This page reuses adapted CC BY 3.0 content from Tom Preston-Werner {cite:p}`semver`. {fa}`quote-left`{ref}`Find out more here.` +> This page reuses adapted CC BY 3.0 content from Tom Preston-Werner {cite:t}`semver`. {fa}`quote-left`{ref}`Find out more here.` ```{admonition} User types :class: tip From b154115a40014f4b75de0e298ba1b11deb37dd7b Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Sun, 23 Feb 2025 19:41:37 +0100 Subject: [PATCH 04/32] Clarified teachbook versioning --- book/installation-and-setup/versioning.md | 62 +++++++++++++++++++---- 1 file changed, 51 insertions(+), 11 deletions(-) diff --git a/book/installation-and-setup/versioning.md b/book/installation-and-setup/versioning.md index 1906b30..dd262fb 100644 --- a/book/installation-and-setup/versioning.md +++ b/book/installation-and-setup/versioning.md @@ -24,19 +24,37 @@ Don't forget to explain how you organize these URLs in your README and eventuall If you've many version of the book, at some point you might reach the 1 GB GitHub Pages limit. This is only expected for extremely large books with a lot of non-text-based (binary) content. To prevent going over that limit, store large content not used for building the website (like images) on an external server. This can be another GitHub repository or a (paid) object store -## Semantic versioning -Semantic versioning is used extensively in the world of software management to deal with versions {cite:p}`semver`. This is more suited than the more traditional way of versioning paper books (version 1, 2, etc.), because of the amount of edits which online books allow. There's [guidelines](https://semver.org/) about how to use a 'x.y.z' version numbers for software, for which we propose the following alternative for books: +## TeachBooks versioning +Versions combined with a changelog can be a very effective way to communicate book changes. Inspired by versioning systems in software management (i.e. semantic and CalVer versioning) version is used extensively in the world of software management to deal with versions. This is more suited than the more traditional way of versioning paper books (version 1, 2, etc.), because of the amount of edits which online books allow. TeachBooks versioning comes in two flavors: -1. A normal version number MUST take the form X.Y.Z where X, Y, and Z are non-negative integers, and MUST NOT contain leading zeroes. X is the major version or yearly version, Y is the minor version, and Z is the patch version. Each element MUST increase numerically. For instance: 1.9.0 -> 1.10.0 -> 1.11.0. or 2025.9.0 -> 2025.10.0 -> 2025.11.0 +1. `academic_year.additions.errata` versioning for books tailed-made for courses in which content is added / adapted during the course and might be restructured extensively every year while remaining to be available in the original form. +2. `major.errata` versioning for books which are more stable over years, in which big changes are covered only by the version number. + +We've come up with guidelines how to use the two TeachBooks-versioning options (adapted from {cite:p}`semver`): + +`````{tab-set} +````{tab-item} `academic_year.additions.errata` +1. A normal version number MUST take the form `academic_year.additions.errata` where `academic_year` is the academic year in which the book is used, and `additions`, and `errata` are non-negative integers, and MUST NOT contain leading zeroes. Each element MUST increase numerically. For instance: 2025.9.0 -> 2025.10.0 -> 2025.11.0 2. Once a versioned book has been released, the contents of that version MUST NOT be modified. Any modifications MUST be released as a new version. -3. Major version zero (0.y.z) is for initial development. Anything MAY change at any time. The book content should not be shared with readers as it's not considers as stable. -4. Version 1.0.0 defines the first released book. The way in which the version number is incremented after this release should be explained in the README of the source code and in the book itself. -5. Patch version Z (x.y.Z | x > 0) MUST be incremented if a small change is made which should be communicated to the reader in both the source code and in the book itself. If the small change is not crucial (like a simple typo), you might consider not defining it as a new version but combining it with other changes in the next version. -6. Minor version Y (x.Y.z | x > 0) MUST be incremented if a big change / addition is made to the book. It MUST be communicated in both the source code and in the book itself. It MAY include patch level changes. Patch version MUST be reset to 0 when minor version is incremented. -7. Major version X (X.y.z | X > 0) MUST be incremented if a substantial restructure is made to the book. A new academic year is a great example for this. It MUST be communicated in both the source code and in the book itself. It MAY also include minor and patch level changes. Patch and minor versions MUST be reset to 0 when major version is incremented. -8. Precedence refers to how versions are compared to each other when ordered. - 1. Precedence MUST be calculated by separating the version into major, minor, patch and pre-release identifiers in that order. - 2. Precedence is determined by the first difference when comparing each of these identifiers from left to right as follows: Major, minor, and patch versions are always compared numerically. Example: 1.0.0 < 2.0.0 < 2.1.0 < 2.1.1. +3. Errata versions MUST be incremented if a small change is made which should be communicated to the reader in both the source code and in the book itself. If the small change is not crucial (like a simple typo), you might consider not defining it as a new version but combining it with other changes in the next errata or additions version. +4. Additions version MUST be incremented if an addition is made to the book. It MUST be communicated in both the source code and in the book itself. It MAY include errata level changes. The errata version MUST be reset to 0 when the addition version is incremented. +5. Academic year version MUST be incremented if a fresh book is started for which additions will follow later. It MUST be communicated in both the source code and in the book itself. Additions and errata versions MUST be reset to 0 when academic version is incremented. +6. Precedence refers to how versions are compared to each other when ordered. + 1. Precedence MUST be calculated by separating the version into academic year, additions and errata identifiers in that order. + 2. Precedence is determined by the first difference when comparing each of these identifiers from left to right as follows: Academic year, additions and errata versions are always compared numerically. Example: 2024.0.0 < 2025.0.0 < 2025.1.0 < 2025.1.1. +7. The way in which the version number is incremented after the initial release should be explained in the README of the source code and in the book itself. +```` +````{tab-item} `major.errata` +1. A normal version number MUST take the form `major.errata` where `major`, and `errata` are non-negative integers, and MUST NOT contain leading zeroes. Each element MUST increase numerically. For instance: 9.0 -> 10.0 -> 11.0 +2. Once a versioned book has been released, the contents of that version MUST NOT be modified. Any modifications MUST be released as a new version. +3. Errata versions MUST be incremented if a small change is made which should be communicated to the reader in both the source code and in the book itself. If the small change is not crucial (like a simple typo), you might consider not defining it as a new version but combining it with other changes in the next major version. +5. Major versions MUST be incremented if a substantial restructure or additions is made. It MUST be communicated in both the source code and in the book itself. Errata versions MUST be reset to 0 when the major version is incremented. +6. Precedence refers to how versions are compared to each other when ordered. + 1. Precedence MUST be calculated by separating the version into major and errata identifiers in that order. + 2. Precedence is determined by the first difference when comparing each of these identifiers from left to right as follows: major and errata versions are always compared numerically. Example: 1.0 < 2.0 < 2.1. +7. The way in which the version number is incremented after the initial release should be explained in the README of the source code and in the book itself. +```` +````` ### Changelog To communicate changes, we advise creating a changelog in the book. The [template](https://github.com/TeachBooks/template/blob/main/book/changelog.md) contains an example: @@ -55,6 +73,28 @@ To communicate changes, we advise creating a changelog in the book. The [templat <...> ``` +### Note on version change on page +When making errata changes or additions, it's advised to notify the reader not only in the changelog, but also on the relevant pages. You can do so using the `versionadded` and `versionchanged` admonitions: + +```md +::::::{versionchanged} + +:::::: +``` + +and + +```md +::::::{versionadded} + +:::::: +``` + +Lead to for example: +::::::{versionchanged} v2025.3.5 2025-02-23 +TeachBooks versioning added +:::::: + ### Implement tags and releases Tags can be added to your source code by adding the version number as a tag to a specific commit. You can do so only locally. In GitHub Desktop this is done by clicking 'Create Tag...` for a specific commit in the History tab. From 51a853cb6e86e3863ab8989a3ec427a11cda7ade Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Sun, 23 Feb 2025 19:44:35 +0100 Subject: [PATCH 05/32] fix tabs? --- book/installation-and-setup/versioning.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/book/installation-and-setup/versioning.md b/book/installation-and-setup/versioning.md index dd262fb..91a1029 100644 --- a/book/installation-and-setup/versioning.md +++ b/book/installation-and-setup/versioning.md @@ -33,7 +33,7 @@ Versions combined with a changelog can be a very effective way to communicate bo We've come up with guidelines how to use the two TeachBooks-versioning options (adapted from {cite:p}`semver`): `````{tab-set} -````{tab-item} `academic_year.additions.errata` +````{tab-item} academic_year.additions.errata 1. A normal version number MUST take the form `academic_year.additions.errata` where `academic_year` is the academic year in which the book is used, and `additions`, and `errata` are non-negative integers, and MUST NOT contain leading zeroes. Each element MUST increase numerically. For instance: 2025.9.0 -> 2025.10.0 -> 2025.11.0 2. Once a versioned book has been released, the contents of that version MUST NOT be modified. Any modifications MUST be released as a new version. 3. Errata versions MUST be incremented if a small change is made which should be communicated to the reader in both the source code and in the book itself. If the small change is not crucial (like a simple typo), you might consider not defining it as a new version but combining it with other changes in the next errata or additions version. @@ -44,7 +44,7 @@ We've come up with guidelines how to use the two TeachBooks-versioning options ( 2. Precedence is determined by the first difference when comparing each of these identifiers from left to right as follows: Academic year, additions and errata versions are always compared numerically. Example: 2024.0.0 < 2025.0.0 < 2025.1.0 < 2025.1.1. 7. The way in which the version number is incremented after the initial release should be explained in the README of the source code and in the book itself. ```` -````{tab-item} `major.errata` +````{tab-item} major.errata 1. A normal version number MUST take the form `major.errata` where `major`, and `errata` are non-negative integers, and MUST NOT contain leading zeroes. Each element MUST increase numerically. For instance: 9.0 -> 10.0 -> 11.0 2. Once a versioned book has been released, the contents of that version MUST NOT be modified. Any modifications MUST be released as a new version. 3. Errata versions MUST be incremented if a small change is made which should be communicated to the reader in both the source code and in the book itself. If the small change is not crucial (like a simple typo), you might consider not defining it as a new version but combining it with other changes in the next major version. @@ -90,7 +90,7 @@ and :::::: ``` -Lead to for example: +Leads to for example: ::::::{versionchanged} v2025.3.5 2025-02-23 TeachBooks versioning added :::::: From f8de3ee3339999ed9da965805a43e438c663887c Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Sun, 23 Feb 2025 19:51:07 +0100 Subject: [PATCH 06/32] puntjes op de i --- book/installation-and-setup/versioning.md | 14 ++++++++------ 1 file changed, 8 insertions(+), 6 deletions(-) diff --git a/book/installation-and-setup/versioning.md b/book/installation-and-setup/versioning.md index 91a1029..2bc1c96 100644 --- a/book/installation-and-setup/versioning.md +++ b/book/installation-and-setup/versioning.md @@ -9,7 +9,7 @@ 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 with tags +- Use TeachBooks versioning - Keep both source code as (export of) websites of all versions - Publishing your book more officially @@ -57,7 +57,7 @@ We've come up with guidelines how to use the two TeachBooks-versioning options ( ````` ### Changelog -To communicate changes, we advise creating a changelog in the book. The [template](https://github.com/TeachBooks/template/blob/main/book/changelog.md) contains an example: +To communicate changes, we advise creating a changelog in the book. The [template](https://github.com/TeachBooks/template/blob/main/book/changelog.md) contains an empty changelog to fill: ```md # Changelog @@ -73,20 +73,22 @@ To communicate changes, we advise creating a changelog in the book. The [templat <...> ``` +An example can be found [here](https://ciem5000-2025.github.io/book/changelog.html) + ### Note on version change on page When making errata changes or additions, it's advised to notify the reader not only in the changelog, but also on the relevant pages. You can do so using the `versionadded` and `versionchanged` admonitions: ```md -::::::{versionchanged} - +::::::{versionchanged} + :::::: ``` and ```md -::::::{versionadded} - +::::::{versionadded} + :::::: ``` From c5c96735455e9de1a88f2c4b661bcefa0d1edb5d Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Mon, 24 Feb 2025 17:23:18 +0100 Subject: [PATCH 07/32] Increase figsize --- book/installation-and-setup/versioning.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/book/installation-and-setup/versioning.md b/book/installation-and-setup/versioning.md index 2bc1c96..1729b2f 100644 --- a/book/installation-and-setup/versioning.md +++ b/book/installation-and-setup/versioning.md @@ -102,7 +102,7 @@ Tags can be added to your source code by adding the version number as a tag to a ```{figure} figures/tags.png --- -width: 300px +width: 500px align: center --- @@ -126,4 +126,4 @@ If you've your own webserver, you can publish each version on it manually. 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 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 +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. From c2db440f102086f78cc744a010d8e447bfbbc501 Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Mon, 24 Feb 2025 20:51:13 +0100 Subject: [PATCH 08/32] Restructure --- book/_toc.yml | 5 + book/installation-and-setup/publisher.md | 6 + book/installation-and-setup/versioning.md | 127 +++--------------- .../versioning_archived.md | 0 .../versioning_changelog.md | 85 ++++++++++++ book/installation-and-setup/versions_URLs.md | 11 ++ 6 files changed, 122 insertions(+), 112 deletions(-) create mode 100644 book/installation-and-setup/publisher.md create mode 100644 book/installation-and-setup/versioning_archived.md create mode 100644 book/installation-and-setup/versioning_changelog.md create mode 100644 book/installation-and-setup/versions_URLs.md diff --git a/book/_toc.yml b/book/_toc.yml index d745c73..e5e5a4d 100644 --- a/book/_toc.yml +++ b/book/_toc.yml @@ -30,6 +30,11 @@ parts: - file: workflows/merge_request.md - file: installation-and-setup/collab - file: installation-and-setup/versioning + sections: + - file: installation-and-setup/versions_URLs + - file: installation-and-setup/versioning_changelog + - file: installation-and-setup/versioning_archived + - file: installation-and-setup/publisher - file: installation-and-setup/copyright.md sections: - file: installation-and-setup/copyright/considerations diff --git a/book/installation-and-setup/publisher.md b/book/installation-and-setup/publisher.md new file mode 100644 index 0000000..55111a0 --- /dev/null +++ b/book/installation-and-setup/publisher.md @@ -0,0 +1,6 @@ + +# Publishing your book with a 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 + +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. diff --git a/book/installation-and-setup/versioning.md b/book/installation-and-setup/versioning.md index 1729b2f..1fe7b79 100644 --- a/book/installation-and-setup/versioning.md +++ b/book/installation-and-setup/versioning.md @@ -7,123 +7,26 @@ 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 TeachBooks versioning -- Keep both source code as (export of) websites of all versions -- Publishing your book more officially +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. -## Publish version on separate (fixed) URLs -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. +For example when making taylor-made books for specific academic years, you want students to be able to find their own book (even after the academic year is over). For students which take the course twice, you might want to provide some sort of changelog of what has been changed. -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. +Another example could be a course in which you add content and solutions during the course or you're fixing mistakes which may have misinformed the reader. If this is not directly visible in the table of contents, students might not be aware of these changes. Again, a changelog could be useful to inform the reader about the change. Furthermore, a smart versioning system might tell the reader something about the impact of the addition differentiating errata and additions. -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: +You could also think of your published book which is references by other people. As content (and the location of this in your book) might change over time, other people can use versions to refer to a fixed version in time of your book. -> 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. +Maybe this all sounds confusing and difficult. No worries! A use-case could be a book which progresses in time, but in which you don't want to deal with the additional hassle of versioning. Your book could be perfectly fine without any measures on this topic! -If you've many version of the book, at some point you might reach the 1 GB GitHub Pages limit. This is only expected for extremely large books with a lot of non-text-based (binary) content. To prevent going over that limit, store large content not used for building the website (like images) on an external server. This can be another GitHub repository or a (paid) object store +Finally, you might consider publishing your book at an online publisher. This could increase findability of your book and you might benefit from the brand of the publisher, but it may have versioning, copyright and licensing consequences. -## TeachBooks versioning -Versions combined with a changelog can be a very effective way to communicate book changes. Inspired by versioning systems in software management (i.e. semantic and CalVer versioning) version is used extensively in the world of software management to deal with versions. This is more suited than the more traditional way of versioning paper books (version 1, 2, etc.), because of the amount of edits which online books allow. TeachBooks versioning comes in two flavors: +So, there's a few use-cases for which different (combinations) of solutions exist. These are summarized in the table below. You can combine use-cases to your liking: -1. `academic_year.additions.errata` versioning for books tailed-made for courses in which content is added / adapted during the course and might be restructured extensively every year while remaining to be available in the original form. -2. `major.errata` versioning for books which are more stable over years, in which big changes are covered only by the version number. +| Use-case | [Publish version on separate URLs](./versios_URLs.md) | [Use TeachBooks versioning with a changelog](versioning_changelog) | [Keep old versions online](./versioning_archived.md) | [Keep source code of old versions online](./versioning_archived.md) | [Publish your book officially](./publisher.md) | +|:---:|:---:|:---:|:---:|:---:|:---:| +| Book changes over time, but you don't want to deal with versioning | | | | | | +| Taylor-made book per academic year | Recommended | | Recommended | Can be considered | | +| Continuously adding content and solutions or updating crucial mistakes | | Recommended | | | | +| Allow referencing specific versions | Can be considered | Recommended | Can be considered | Recommended | | +| Increase findability or benefit from publisher's brand | | | | | Recommended | -We've come up with guidelines how to use the two TeachBooks-versioning options (adapted from {cite:p}`semver`): - -`````{tab-set} -````{tab-item} academic_year.additions.errata -1. A normal version number MUST take the form `academic_year.additions.errata` where `academic_year` is the academic year in which the book is used, and `additions`, and `errata` are non-negative integers, and MUST NOT contain leading zeroes. Each element MUST increase numerically. For instance: 2025.9.0 -> 2025.10.0 -> 2025.11.0 -2. Once a versioned book has been released, the contents of that version MUST NOT be modified. Any modifications MUST be released as a new version. -3. Errata versions MUST be incremented if a small change is made which should be communicated to the reader in both the source code and in the book itself. If the small change is not crucial (like a simple typo), you might consider not defining it as a new version but combining it with other changes in the next errata or additions version. -4. Additions version MUST be incremented if an addition is made to the book. It MUST be communicated in both the source code and in the book itself. It MAY include errata level changes. The errata version MUST be reset to 0 when the addition version is incremented. -5. Academic year version MUST be incremented if a fresh book is started for which additions will follow later. It MUST be communicated in both the source code and in the book itself. Additions and errata versions MUST be reset to 0 when academic version is incremented. -6. Precedence refers to how versions are compared to each other when ordered. - 1. Precedence MUST be calculated by separating the version into academic year, additions and errata identifiers in that order. - 2. Precedence is determined by the first difference when comparing each of these identifiers from left to right as follows: Academic year, additions and errata versions are always compared numerically. Example: 2024.0.0 < 2025.0.0 < 2025.1.0 < 2025.1.1. -7. The way in which the version number is incremented after the initial release should be explained in the README of the source code and in the book itself. -```` -````{tab-item} major.errata -1. A normal version number MUST take the form `major.errata` where `major`, and `errata` are non-negative integers, and MUST NOT contain leading zeroes. Each element MUST increase numerically. For instance: 9.0 -> 10.0 -> 11.0 -2. Once a versioned book has been released, the contents of that version MUST NOT be modified. Any modifications MUST be released as a new version. -3. Errata versions MUST be incremented if a small change is made which should be communicated to the reader in both the source code and in the book itself. If the small change is not crucial (like a simple typo), you might consider not defining it as a new version but combining it with other changes in the next major version. -5. Major versions MUST be incremented if a substantial restructure or additions is made. It MUST be communicated in both the source code and in the book itself. Errata versions MUST be reset to 0 when the major version is incremented. -6. Precedence refers to how versions are compared to each other when ordered. - 1. Precedence MUST be calculated by separating the version into major and errata identifiers in that order. - 2. Precedence is determined by the first difference when comparing each of these identifiers from left to right as follows: major and errata versions are always compared numerically. Example: 1.0 < 2.0 < 2.1. -7. The way in which the version number is incremented after the initial release should be explained in the README of the source code and in the book itself. -```` -````` - -### Changelog -To communicate changes, we advise creating a changelog in the book. The [template](https://github.com/TeachBooks/template/blob/main/book/changelog.md) contains an empty changelog to fill: - -```md -# Changelog - -## ``: `` -- `` [](``) -- ... -- Full Changelog: `[...]()' - -## ``: <...> -- <...> - -<...> -``` - -An example can be found [here](https://ciem5000-2025.github.io/book/changelog.html) - -### Note on version change on page -When making errata changes or additions, it's advised to notify the reader not only in the changelog, but also on the relevant pages. You can do so using the `versionadded` and `versionchanged` admonitions: - -```md -::::::{versionchanged} - -:::::: -``` - -and - -```md -::::::{versionadded} - -:::::: -``` - -Leads to for example: -::::::{versionchanged} v2025.3.5 2025-02-23 -TeachBooks versioning added -:::::: - -### Implement tags and releases -Tags can be added to your source code by adding the version number as a tag to a specific commit. You can do so only locally. In GitHub Desktop this is done by clicking 'Create Tag...` for a specific commit in the History tab. - -```{figure} figures/tags.png ---- -width: 500px -align: center ---- - -``` - -Once the tags is pushed to GitHub/GitLab. You can create a release of the version by clicking `Release` on the `Code` page of your repository. There you can select a tag and generate release notes. It's recommended to add the relevant part of the changelog too. An example can be found [here](https://github.com/CIEM5000-2025/book/releases/tag/v2025.2.0) - -## Keep source code and website of all versions -Although you might only want to share the most recent version of the book with your readers, it might be useful too the have the source code and website of older versions somewhere too. - -Git allows you to go back in the git history to the source code of old versions. To make this as easy as possible for readers, use tags and releases instead of having the readers scroll through a long list of (not alway very descriptive) commit descriptions. - -To share the built book / website of old versions for your book on GitHub you've a few options: -- add a zip of the built book to the release in GitHub as binary asset. This requires readers to download the zip and open the html files locally, but doesn't require you to host it somewhere. This zip can be easily downloaded as an artifact from [the GitHub action](../external/deploy-book-workflow/README.md). An example can be found [here](https://github.com/TUDelft-books/CME4501/releases/tag/v2024.1.0) -- create a branch for each tag. When doing this, [the GitHub workflow](../external/deploy-book-workflow/README.md) will build it on GitHub pages. It's advised to use the version as branch name. You can create a branch from a tag locally by running: `git branch `. Note that when you've many version and a large book, this approach might easily fill up your 1 GB GitHub pages limit. -- Use [Read the Docs](../features/pull_request_build.md) to build a website for all your tags. Refer to the URL of this built from your GitHub release. To enable this functionality in Read the Docs, apply the following settings in [your Read the Docs dashboard](https://app.readthedocs.org/dashboard/): go to `Setup` - `Settings` - `Automation rules` - `Add rule` and set `Description`: 'Build all tags', `Match`: `Custom Match`, `Custom match`: `.*`, `Version type`: `Tag`, `Action`: `Activate version` - -If you've your own webserver, you can publish each version on it manually. - -## 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 - -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. +Read more about each of these measures on the following sub-pages diff --git a/book/installation-and-setup/versioning_archived.md b/book/installation-and-setup/versioning_archived.md new file mode 100644 index 0000000..e69de29 diff --git a/book/installation-and-setup/versioning_changelog.md b/book/installation-and-setup/versioning_changelog.md new file mode 100644 index 0000000..fba48a8 --- /dev/null +++ b/book/installation-and-setup/versioning_changelog.md @@ -0,0 +1,85 @@ +# TeachBooks versioning with changelog +Versions combined with a changelog can be a very effective way to communicate book changes. Inspired by versioning systems in software management (i.e. semantic and CalVer versioning) version is used extensively in the world of software management to deal with versions. This is more suited than the more traditional way of versioning paper books (version 1, 2, etc.), because of the amount of edits which online books allow. TeachBooks versioning comes in two flavors: + +1. `academic_year.additions.errata` versioning for books tailed-made for courses in which content is added / adapted during the course and might be restructured extensively every year while remaining to be available in the original form. +2. `major.errata` versioning for books which are more stable over years, in which big changes are covered only by the version number. + +We've come up with guidelines how to use the two TeachBooks-versioning options (adapted from {cite:p}`semver`): + +`````{tab-set} +````{tab-item} academic_year.additions.errata +1. A normal version number MUST take the form `academic_year.additions.errata` where `academic_year` is the academic year in which the book is used, and `additions`, and `errata` are non-negative integers, and MUST NOT contain leading zeroes. Each element MUST increase numerically. For instance: 2025.9.0 -> 2025.10.0 -> 2025.11.0 +2. Once a versioned book has been released, the contents of that version MUST NOT be modified. Any modifications MUST be released as a new version. +3. Errata versions MUST be incremented if a small change is made which should be communicated to the reader in both the source code and in the book itself. If the small change is not crucial (like a simple typo), you might consider not defining it as a new version but combining it with other changes in the next errata or additions version. +4. Additions version MUST be incremented if an addition is made to the book. It MUST be communicated in both the source code and in the book itself. It MAY include errata level changes. The errata version MUST be reset to 0 when the addition version is incremented. +5. Academic year version MUST be incremented if a fresh book is started for which additions will follow later. It MUST be communicated in both the source code and in the book itself. Additions and errata versions MUST be reset to 0 when academic version is incremented. +6. Precedence refers to how versions are compared to each other when ordered. + 1. Precedence MUST be calculated by separating the version into academic year, additions and errata identifiers in that order. + 2. Precedence is determined by the first difference when comparing each of these identifiers from left to right as follows: Academic year, additions and errata versions are always compared numerically. Example: 2024.0.0 < 2025.0.0 < 2025.1.0 < 2025.1.1. +7. The way in which the version number is incremented after the initial release should be explained in the README of the source code and in the book itself. +```` +````{tab-item} major.errata +1. A normal version number MUST take the form `major.errata` where `major`, and `errata` are non-negative integers, and MUST NOT contain leading zeroes. Each element MUST increase numerically. For instance: 9.0 -> 10.0 -> 11.0 +2. Once a versioned book has been released, the contents of that version MUST NOT be modified. Any modifications MUST be released as a new version. +3. Errata versions MUST be incremented if a small change is made which should be communicated to the reader in both the source code and in the book itself. If the small change is not crucial (like a simple typo), you might consider not defining it as a new version but combining it with other changes in the next major version. +5. Major versions MUST be incremented if a substantial restructure or additions is made. It MUST be communicated in both the source code and in the book itself. Errata versions MUST be reset to 0 when the major version is incremented. +6. Precedence refers to how versions are compared to each other when ordered. + 1. Precedence MUST be calculated by separating the version into major and errata identifiers in that order. + 2. Precedence is determined by the first difference when comparing each of these identifiers from left to right as follows: major and errata versions are always compared numerically. Example: 1.0 < 2.0 < 2.1. +7. The way in which the version number is incremented after the initial release should be explained in the README of the source code and in the book itself. +```` +````` + +## Changelog +To communicate changes, we advise creating a changelog in the book. The [template](https://github.com/TeachBooks/template/blob/main/book/changelog.md) contains an empty changelog to fill: + +```md +# Changelog + +## ``: `` +- `` [](``) +- ... +- Full Changelog: `[...]()' + +## ``: <...> +- <...> + +<...> +``` + +An example can be found [here](https://ciem5000-2025.github.io/book/changelog.html) + +## Note on version change on page +When making errata changes or additions, it's advised to notify the reader not only in the changelog, but also on the relevant pages. You can do so using the `versionadded` and `versionchanged` admonitions: + +```md +::::::{versionchanged} + +:::::: +``` + +and + +```md +::::::{versionadded} + +:::::: +``` + +Leads to for example: +::::::{versionchanged} v2025.3.5 2025-02-23 +TeachBooks versioning added +:::::: + +## Implement tags and releases +Tags can be added to your source code by adding the version number as a tag to a specific commit. You can do so only locally. In GitHub Desktop this is done by clicking 'Create Tag...` for a specific commit in the History tab. + +```{figure} figures/tags.png +--- +width: 500px +align: center +--- + +``` + +Once the tags is pushed to GitHub/GitLab. You can create a release of the version by clicking `Release` on the `Code` page of your repository. There you can select a tag and generate release notes. It's recommended to add the relevant part of the changelog too. An example can be found [here](https://github.com/CIEM5000-2025/book/releases/tag/v2025.2.0) diff --git a/book/installation-and-setup/versions_URLs.md b/book/installation-and-setup/versions_URLs.md new file mode 100644 index 0000000..9bde6fb --- /dev/null +++ b/book/installation-and-setup/versions_URLs.md @@ -0,0 +1,11 @@ +# Publish version on separate (fixed) URLs + +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. + +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. + +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: + +> 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. + +If you've many version of the book, at some point you might reach the 1 GB GitHub Pages limit. This is only expected for extremely large books with a lot of non-text-based (binary) content. To prevent going over that limit, store large content not used for building the website (like images) on an external server. This can be another GitHub repository or a (paid) object store From 5ae094a9f5afb2c93275f1e643b086460467f8da Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Mon, 24 Feb 2025 20:55:20 +0100 Subject: [PATCH 09/32] WIP --- book/installation-and-setup/versioning.md | 2 +- book/installation-and-setup/versioning_archived.md | 11 +++++++++++ 2 files changed, 12 insertions(+), 1 deletion(-) diff --git a/book/installation-and-setup/versioning.md b/book/installation-and-setup/versioning.md index 1fe7b79..84ed18e 100644 --- a/book/installation-and-setup/versioning.md +++ b/book/installation-and-setup/versioning.md @@ -21,7 +21,7 @@ Finally, you might consider publishing your book at an online publisher. This co So, there's a few use-cases for which different (combinations) of solutions exist. These are summarized in the table below. You can combine use-cases to your liking: -| Use-case | [Publish version on separate URLs](./versios_URLs.md) | [Use TeachBooks versioning with a changelog](versioning_changelog) | [Keep old versions online](./versioning_archived.md) | [Keep source code of old versions online](./versioning_archived.md) | [Publish your book officially](./publisher.md) | +| Use-case | [Publish version on separate URLs](./versions_URLs.md) | [Use TeachBooks versioning with a changelog](versioning_changelog) | [Keep old versions online](./versioning_archived.md) | [Keep source code of old versions online](./versioning_archived.md) | [Publish your book officially](./publisher.md) | |:---:|:---:|:---:|:---:|:---:|:---:| | Book changes over time, but you don't want to deal with versioning | | | | | | | Taylor-made book per academic year | Recommended | | Recommended | Can be considered | | diff --git a/book/installation-and-setup/versioning_archived.md b/book/installation-and-setup/versioning_archived.md index e69de29..21369e5 100644 --- a/book/installation-and-setup/versioning_archived.md +++ b/book/installation-and-setup/versioning_archived.md @@ -0,0 +1,11 @@ +# Keep source code and website of all versions +Although you might only want to share the most recent version of the book with your readers, it might be useful too the have the source code and website of older versions somewhere too. + +Git allows you to go back in the git history to the source code of old versions. To make this as easy as possible for readers, use tags and releases instead of having the readers scroll through a long list of (not alway very descriptive) commit descriptions. + +To share the built book / website of old versions for your book on GitHub you've a few options: +- add a zip of the built book to the release in GitHub as binary asset. This requires readers to download the zip and open the html files locally, but doesn't require you to host it somewhere. This zip can be easily downloaded as an artifact from [the GitHub action](../external/deploy-book-workflow/README.md). An example can be found [here](https://github.com/TUDelft-books/CME4501/releases/tag/v2024.1.0) +- create a branch for each tag. When doing this, [the GitHub workflow](../external/deploy-book-workflow/README.md) will build it on GitHub pages. It's advised to use the version as branch name. You can create a branch from a tag locally by running: `git branch `. Note that when you've many version and a large book, this approach might easily fill up your 1 GB GitHub pages limit. +- Use [Read the Docs](../features/pull_request_build.md) to build a website for all your tags. Refer to the URL of this built from your GitHub release. To enable this functionality in Read the Docs, apply the following settings in [your Read the Docs dashboard](https://app.readthedocs.org/dashboard/): go to `Setup` - `Settings` - `Automation rules` - `Add rule` and set `Description`: 'Build all tags', `Match`: `Custom Match`, `Custom match`: `.*`, `Version type`: `Tag`, `Action`: `Activate version` + +If you've your own webserver, you can publish each version on it manually. \ No newline at end of file From 18d64ff18e68c3855d971f8b94972c35ec098ea9 Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Mon, 24 Feb 2025 21:01:33 +0100 Subject: [PATCH 10/32] WIP --- book/installation-and-setup/versioning.md | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/book/installation-and-setup/versioning.md b/book/installation-and-setup/versioning.md index 84ed18e..73fee3f 100644 --- a/book/installation-and-setup/versioning.md +++ b/book/installation-and-setup/versioning.md @@ -7,7 +7,7 @@ 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. +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 an explicit version to the readers. For example when making taylor-made books for specific academic years, you want students to be able to find their own book (even after the academic year is over). For students which take the course twice, you might want to provide some sort of changelog of what has been changed. @@ -17,6 +17,8 @@ You could also think of your published book which is references by other people. Maybe this all sounds confusing and difficult. No worries! A use-case could be a book which progresses in time, but in which you don't want to deal with the additional hassle of versioning. Your book could be perfectly fine without any measures on this topic! +If you are part of the previous group, but at some point decide to make a new version of the book while keeping the old one, you could do so without dealing with version numbers and changelogs, but just publish both versions online. + Finally, you might consider publishing your book at an online publisher. This could increase findability of your book and you might benefit from the brand of the publisher, but it may have versioning, copyright and licensing consequences. So, there's a few use-cases for which different (combinations) of solutions exist. These are summarized in the table below. You can combine use-cases to your liking: @@ -24,9 +26,10 @@ So, there's a few use-cases for which different (combinations) of solutions exis | Use-case | [Publish version on separate URLs](./versions_URLs.md) | [Use TeachBooks versioning with a changelog](versioning_changelog) | [Keep old versions online](./versioning_archived.md) | [Keep source code of old versions online](./versioning_archived.md) | [Publish your book officially](./publisher.md) | |:---:|:---:|:---:|:---:|:---:|:---:| | Book changes over time, but you don't want to deal with versioning | | | | | | -| Taylor-made book per academic year | Recommended | | Recommended | Can be considered | | +| Occasionally releasing a new version while keeping the previous version, with minimal effort for versioning | Recommended | | Recommended | Can be considered | | | Continuously adding content and solutions or updating crucial mistakes | | Recommended | | | | | Allow referencing specific versions | Can be considered | Recommended | Can be considered | Recommended | | +| Taylor-made book per academic year | Recommended | Recommended in case of students retaking a course | Recommended | Can be considered | | | Increase findability or benefit from publisher's brand | | | | | Recommended | Read more about each of these measures on the following sub-pages From dedfdd7d973f452ea8b2d7bccdf807675b6dfdf2 Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Mon, 24 Feb 2025 21:29:44 +0100 Subject: [PATCH 11/32] WIP --- book/_toc.yml | 2 +- book/installation-and-setup/versioning.md | 28 +++++++++---------- .../versioning_archived.md | 10 ++----- .../versioning_changelog.md | 2 +- book/installation-and-setup/versions_URLs.md | 17 +++++++++-- 5 files changed, 32 insertions(+), 27 deletions(-) diff --git a/book/_toc.yml b/book/_toc.yml index e5e5a4d..0371461 100644 --- a/book/_toc.yml +++ b/book/_toc.yml @@ -32,8 +32,8 @@ parts: - file: installation-and-setup/versioning sections: - file: installation-and-setup/versions_URLs - - file: installation-and-setup/versioning_changelog - file: installation-and-setup/versioning_archived + - file: installation-and-setup/versioning_changelog - file: installation-and-setup/publisher - file: installation-and-setup/copyright.md sections: diff --git a/book/installation-and-setup/versioning.md b/book/installation-and-setup/versioning.md index 73fee3f..3a8a8fb 100644 --- a/book/installation-and-setup/versioning.md +++ b/book/installation-and-setup/versioning.md @@ -11,25 +11,25 @@ Online books can be easily updated, however, this might confuse readers. Therefo For example when making taylor-made books for specific academic years, you want students to be able to find their own book (even after the academic year is over). For students which take the course twice, you might want to provide some sort of changelog of what has been changed. -Another example could be a course in which you add content and solutions during the course or you're fixing mistakes which may have misinformed the reader. If this is not directly visible in the table of contents, students might not be aware of these changes. Again, a changelog could be useful to inform the reader about the change. Furthermore, a smart versioning system might tell the reader something about the impact of the addition differentiating errata and additions. +Another example could be a book in which you add content and solutions during the course or you're fixing mistakes which may have misinformed the reader. If this is not directly visible in the table of contents, students might not be aware of these changes. Again, a changelog could be useful to inform the reader about the change. Furthermore, a smart versioning system might tell the reader something about the impact of the addition differentiating errata and additions. -You could also think of your published book which is references by other people. As content (and the location of this in your book) might change over time, other people can use versions to refer to a fixed version in time of your book. +You could also think of your published book which is referenced by other people. As content (and the location of this in your book) might change over time, other people can use versions to refer to a fixed version in time of your book. Maybe this all sounds confusing and difficult. No worries! A use-case could be a book which progresses in time, but in which you don't want to deal with the additional hassle of versioning. Your book could be perfectly fine without any measures on this topic! -If you are part of the previous group, but at some point decide to make a new version of the book while keeping the old one, you could do so without dealing with version numbers and changelogs, but just publish both versions online. +If you are part of the previous group, but at some point decide to make a new version of the book while keeping the old one, you could do so without dealing with version numbers and changelogs. Just publish both versions online. -Finally, you might consider publishing your book at an online publisher. This could increase findability of your book and you might benefit from the brand of the publisher, but it may have versioning, copyright and licensing consequences. +Finally, you might consider publishing your book at an online publisher. This could increase findability of your book and you might benefit from the brand of the publisher, but it may have flexibility, copyright and licensing consequences. -So, there's a few use-cases for which different (combinations) of solutions exist. These are summarized in the table below. You can combine use-cases to your liking: +So, there's a few use-cases for which different (combinations) of solutions exist. These are summarized in the table below in order of increasingly effort and impact. You can combine use-cases to your liking: -| Use-case | [Publish version on separate URLs](./versions_URLs.md) | [Use TeachBooks versioning with a changelog](versioning_changelog) | [Keep old versions online](./versioning_archived.md) | [Keep source code of old versions online](./versioning_archived.md) | [Publish your book officially](./publisher.md) | -|:---:|:---:|:---:|:---:|:---:|:---:| -| Book changes over time, but you don't want to deal with versioning | | | | | | -| Occasionally releasing a new version while keeping the previous version, with minimal effort for versioning | Recommended | | Recommended | Can be considered | | -| Continuously adding content and solutions or updating crucial mistakes | | Recommended | | | | -| Allow referencing specific versions | Can be considered | Recommended | Can be considered | Recommended | | -| Taylor-made book per academic year | Recommended | Recommended in case of students retaking a course | Recommended | Can be considered | | -| Increase findability or benefit from publisher's brand | | | | | Recommended | +| Use-case | [Publish versions on separate URLs](./versions_URLs.md) | [Publish source code of all versions](./versioning_archived.md) | [Use TeachBooks versioning with a changelog](versioning_changelog) | [Publish your book officially](./publisher.md) | +|:---:|:---:|:---:|:---:|:---:| +| Book changes over time, but you don't want to deal with versioning | | | | | +| Occasionally releasing a new version while keeping the previous version, with minimal effort for versioning | Recommended | Can be considered | | | +| Continuously adding content and solutions or updating crucial mistakes | | | Recommended | | +| Allow referencing specific versions | Can be considered |Recommended | Recommended | | +| Taylor-made book per academic year | Recommended | Can be considered | Recommended in case of students retaking a course | | +| Increase findability or benefit from publisher's brand | | | | Recommended | -Read more about each of these measures on the following sub-pages +Read more about each of these measures on the following sub-pages. \ No newline at end of file diff --git a/book/installation-and-setup/versioning_archived.md b/book/installation-and-setup/versioning_archived.md index 21369e5..94e54b3 100644 --- a/book/installation-and-setup/versioning_archived.md +++ b/book/installation-and-setup/versioning_archived.md @@ -1,11 +1,5 @@ # Keep source code and website of all versions -Although you might only want to share the most recent version of the book with your readers, it might be useful too the have the source code and website of older versions somewhere too. -Git allows you to go back in the git history to the source code of old versions. To make this as easy as possible for readers, use tags and releases instead of having the readers scroll through a long list of (not alway very descriptive) commit descriptions. +Although you might only want to share the most recent version of the book with your readers, it might be useful too the have the source code of those versions somewhere too. Don't be afraid, git makes it very easy to make this possible. -To share the built book / website of old versions for your book on GitHub you've a few options: -- add a zip of the built book to the release in GitHub as binary asset. This requires readers to download the zip and open the html files locally, but doesn't require you to host it somewhere. This zip can be easily downloaded as an artifact from [the GitHub action](../external/deploy-book-workflow/README.md). An example can be found [here](https://github.com/TUDelft-books/CME4501/releases/tag/v2024.1.0) -- create a branch for each tag. When doing this, [the GitHub workflow](../external/deploy-book-workflow/README.md) will build it on GitHub pages. It's advised to use the version as branch name. You can create a branch from a tag locally by running: `git branch `. Note that when you've many version and a large book, this approach might easily fill up your 1 GB GitHub pages limit. -- Use [Read the Docs](../features/pull_request_build.md) to build a website for all your tags. Refer to the URL of this built from your GitHub release. To enable this functionality in Read the Docs, apply the following settings in [your Read the Docs dashboard](https://app.readthedocs.org/dashboard/): go to `Setup` - `Settings` - `Automation rules` - `Add rule` and set `Description`: 'Build all tags', `Match`: `Custom Match`, `Custom match`: `.*`, `Version type`: `Tag`, `Action`: `Activate version` - -If you've your own webserver, you can publish each version on it manually. \ No newline at end of file +Git allows you to go back in the git history to the source code of old versions. To make this as easy as possible for readers, use branches, tags and releases instead of having the readers scroll through a long list of (not alway very descriptive) commit descriptions. How to use tags and releases is described in [](./versioning_changelog.md) \ No newline at end of file diff --git a/book/installation-and-setup/versioning_changelog.md b/book/installation-and-setup/versioning_changelog.md index fba48a8..d9fd37e 100644 --- a/book/installation-and-setup/versioning_changelog.md +++ b/book/installation-and-setup/versioning_changelog.md @@ -1,5 +1,5 @@ # TeachBooks versioning with changelog -Versions combined with a changelog can be a very effective way to communicate book changes. Inspired by versioning systems in software management (i.e. semantic and CalVer versioning) version is used extensively in the world of software management to deal with versions. This is more suited than the more traditional way of versioning paper books (version 1, 2, etc.), because of the amount of edits which online books allow. TeachBooks versioning comes in two flavors: +Versions combined with a changelog can be a very effective way to communicate book changes to the reader and allow reuse of specific versions. Inspired by versioning systems in software management (i.e. semantic and CalVer versioning) you can define a version guideline in which the version number tells the reader about the impact of the change. This might more suitable for your online books than the more traditional way of versioning paper books (version 1, 2, etc.), because of the amount of edits which online books allow. We recommend TeachBooks versioning, which comes in two flavors: 1. `academic_year.additions.errata` versioning for books tailed-made for courses in which content is added / adapted during the course and might be restructured extensively every year while remaining to be available in the original form. 2. `major.errata` versioning for books which are more stable over years, in which big changes are covered only by the version number. diff --git a/book/installation-and-setup/versions_URLs.md b/book/installation-and-setup/versions_URLs.md index 9bde6fb..f40266d 100644 --- a/book/installation-and-setup/versions_URLs.md +++ b/book/installation-and-setup/versions_URLs.md @@ -1,11 +1,22 @@ # Publish version on separate (fixed) URLs -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. +As soon as you've different versions online, you have to make a decision about URLs. 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 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. -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: +To share the built book / website of old versions for your book on GitHub you've a few options: +- create a branch for each version. When doing this, [the GitHub workflow](../external/deploy-book-workflow/README.md) will build it on GitHub pages. Here's a few tips: + - It's advised to use the version as branch name. In case of versions per academic year, you can just name each branch to the current academic year, this leads to the URL with the same name. In that case. + - It is recommended to update the primary branch as the `PRIMARY BRANCH` when using the [GitHub workflow](gh-workflow-settings) whenever a new version is considered to be the most primary one. This ensures that readers 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. Alternatively, you can add a banner manually to `_config.yml`. + - If you're using tags (as will be explained in [later](./versioning_changelog.md)), you can create a branch from a tag locally by running: `git branch `. + - If you've many version of the book, at some point you might reach the 1 GB GitHub Pages limit. This is only expected for extremely large books with a lot of non-text-based (binary) content. To prevent going over that limit, store large content not used for building the website (like images) on an external server. This can be another GitHub repository or a (paid) object store. +- add a zip of the built book to the release in GitHub as binary asset. This requires readers to download the zip and open the html files locally, but doesn't require you to host it somewhere. This zip can be easily downloaded as an artifact from [the GitHub action](../external/deploy-book-workflow/README.md). An example can be found [here](https://github.com/TUDelft-books/CME4501/releases/tag/v2024.1.0). Note that this requires you to set up tags and releases, as explained in [](versioning_changelog.md) +- Use [Read the Docs](../features/pull_request_build.md) to build a website for all your branches, forks and tags as Read the docs doesn't have a 1 GB limit, but has a very different URL structure. In case you're using tags and release, refer to the URL of this built from your GitHub release. + +If you've your own webserver, you can publish each version on it manually. + +Don't forget to explain how you organize your URLs and old versions in your README and eventually in the book itself too with a sentence like this: > 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. -If you've many version of the book, at some point you might reach the 1 GB GitHub Pages limit. This is only expected for extremely large books with a lot of non-text-based (binary) content. To prevent going over that limit, store large content not used for building the website (like images) on an external server. This can be another GitHub repository or a (paid) object store From 3c97679bb722421fa40c42033dba03a4a4e2d00f Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Mon, 24 Feb 2025 21:30:42 +0100 Subject: [PATCH 12/32] WIP --- book/credits.md | 2 +- book/installation-and-setup/versioning.md | 2 -- book/installation-and-setup/versioning_changelog.md | 3 +++ 3 files changed, 4 insertions(+), 3 deletions(-) diff --git a/book/credits.md b/book/credits.md index ef9cdf1..c33d85c 100644 --- a/book/credits.md +++ b/book/credits.md @@ -60,7 +60,7 @@ The following pages contain content written by others, part of has been reused a - Pages {ref}`copyright` and {ref}`copyright_considerations` include text from {cite:t}`tud_cip_24` that is used in the copyright checklist items. Original content licensed under CC BY. - Page {ref}`copyright_licenses`: {numref}`Figure %s` is included unmodified, along with paraphrased and quoted text (including hyperlinks) from {cite:t}`hall21`. Work is licensed under CC BY. - Page {ref}`copyright_licenses`: {numref}`Figure %s` is included unmodified. Work is provided by Kennisland under a CC0 license. Accessed at [](https://wiki.creativecommons.org/wiki/File:CC_License_Compatibility_Chart.png) on December 17, 2024. -- page [](./installation-and-setup/versioning.md): includes text from {cite:t}`semver` that has been modified. Original content licensed under CC BY 3.0. +- page [](./installation-and-setup/versioning_changelog.md): includes text from {cite:t}`semver` that has been modified. Original content licensed under CC BY 3.0. diff --git a/book/installation-and-setup/versioning.md b/book/installation-and-setup/versioning.md index 3a8a8fb..85eb2a2 100644 --- a/book/installation-and-setup/versioning.md +++ b/book/installation-and-setup/versioning.md @@ -1,7 +1,5 @@ # Versioning and URLs -> This page reuses adapted CC BY 3.0 content from Tom Preston-Werner {cite:t}`semver`. {fa}`quote-left`{ref}`Find out more here.` - ```{admonition} User types :class: tip This page is useful for user type 4-5. diff --git a/book/installation-and-setup/versioning_changelog.md b/book/installation-and-setup/versioning_changelog.md index d9fd37e..26aa67d 100644 --- a/book/installation-and-setup/versioning_changelog.md +++ b/book/installation-and-setup/versioning_changelog.md @@ -1,4 +1,7 @@ # TeachBooks versioning with changelog + +> This page reuses adapted CC BY 3.0 content from Tom Preston-Werner {cite:t}`semver`. {fa}`quote-left`{ref}`Find out more here.` + Versions combined with a changelog can be a very effective way to communicate book changes to the reader and allow reuse of specific versions. Inspired by versioning systems in software management (i.e. semantic and CalVer versioning) you can define a version guideline in which the version number tells the reader about the impact of the change. This might more suitable for your online books than the more traditional way of versioning paper books (version 1, 2, etc.), because of the amount of edits which online books allow. We recommend TeachBooks versioning, which comes in two flavors: 1. `academic_year.additions.errata` versioning for books tailed-made for courses in which content is added / adapted during the course and might be restructured extensively every year while remaining to be available in the original form. From 1bcc3473d764beb30159612501d957ebdca84487 Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Mon, 24 Feb 2025 21:34:32 +0100 Subject: [PATCH 13/32] WIP --- book/installation-and-setup/versioning_archived.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/book/installation-and-setup/versioning_archived.md b/book/installation-and-setup/versioning_archived.md index 94e54b3..af3899f 100644 --- a/book/installation-and-setup/versioning_archived.md +++ b/book/installation-and-setup/versioning_archived.md @@ -1,5 +1,5 @@ # Keep source code and website of all versions -Although you might only want to share the most recent version of the book with your readers, it might be useful too the have the source code of those versions somewhere too. Don't be afraid, git makes it very easy to make this possible. +In case you'd like other to use your source code and you've different versions, it might be useful to have the source code of those versions somewhere too. Don't be afraid, git makes it very easy to make this possible. Git allows you to go back in the git history to the source code of old versions. To make this as easy as possible for readers, use branches, tags and releases instead of having the readers scroll through a long list of (not alway very descriptive) commit descriptions. How to use tags and releases is described in [](./versioning_changelog.md) \ No newline at end of file From cd7093e1d4634979ae42adab9b2b8f953cc75dbd Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Mon, 24 Feb 2025 21:44:09 +0100 Subject: [PATCH 14/32] Final stuff for today --- book/installation-and-setup/versioning.md | 2 +- book/installation-and-setup/versioning_archived.md | 2 +- book/installation-and-setup/versions_URLs.md | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/book/installation-and-setup/versioning.md b/book/installation-and-setup/versioning.md index 85eb2a2..0d9fbb4 100644 --- a/book/installation-and-setup/versioning.md +++ b/book/installation-and-setup/versioning.md @@ -21,7 +21,7 @@ Finally, you might consider publishing your book at an online publisher. This co So, there's a few use-cases for which different (combinations) of solutions exist. These are summarized in the table below in order of increasingly effort and impact. You can combine use-cases to your liking: -| Use-case | [Publish versions on separate URLs](./versions_URLs.md) | [Publish source code of all versions](./versioning_archived.md) | [Use TeachBooks versioning with a changelog](versioning_changelog) | [Publish your book officially](./publisher.md) | +| Use-case | [Publish versions on separate URLs](./versions_URLs.md) | [Publish source code of all versions](./versioning_archived.md) | [Use TeachBooks versioning with a changelog](versioning_changelog) | [Publish your book with a publisher](./publisher.md) | |:---:|:---:|:---:|:---:|:---:| | Book changes over time, but you don't want to deal with versioning | | | | | | Occasionally releasing a new version while keeping the previous version, with minimal effort for versioning | Recommended | Can be considered | | | diff --git a/book/installation-and-setup/versioning_archived.md b/book/installation-and-setup/versioning_archived.md index af3899f..1b6746b 100644 --- a/book/installation-and-setup/versioning_archived.md +++ b/book/installation-and-setup/versioning_archived.md @@ -1,4 +1,4 @@ -# Keep source code and website of all versions +# Publish source code of all versions In case you'd like other to use your source code and you've different versions, it might be useful to have the source code of those versions somewhere too. Don't be afraid, git makes it very easy to make this possible. diff --git a/book/installation-and-setup/versions_URLs.md b/book/installation-and-setup/versions_URLs.md index f40266d..8cc7e53 100644 --- a/book/installation-and-setup/versions_URLs.md +++ b/book/installation-and-setup/versions_URLs.md @@ -12,7 +12,7 @@ To share the built book / website of old versions for your book on GitHub you've - If you're using tags (as will be explained in [later](./versioning_changelog.md)), you can create a branch from a tag locally by running: `git branch `. - If you've many version of the book, at some point you might reach the 1 GB GitHub Pages limit. This is only expected for extremely large books with a lot of non-text-based (binary) content. To prevent going over that limit, store large content not used for building the website (like images) on an external server. This can be another GitHub repository or a (paid) object store. - add a zip of the built book to the release in GitHub as binary asset. This requires readers to download the zip and open the html files locally, but doesn't require you to host it somewhere. This zip can be easily downloaded as an artifact from [the GitHub action](../external/deploy-book-workflow/README.md). An example can be found [here](https://github.com/TUDelft-books/CME4501/releases/tag/v2024.1.0). Note that this requires you to set up tags and releases, as explained in [](versioning_changelog.md) -- Use [Read the Docs](../features/pull_request_build.md) to build a website for all your branches, forks and tags as Read the docs doesn't have a 1 GB limit, but has a very different URL structure. In case you're using tags and release, refer to the URL of this built from your GitHub release. +- Use [Read the Docs](../features/pull_request_build.md) to build a website for all your branches, forks and tags as Read the docs doesn't have a 1 GB limit, but has a very different URL structure and the free community version has advertisement. In case you're using tags and releases, refer to the URL of this built from your GitHub release to make sure that GitHub visitors find their way to Read the Docs. If you've your own webserver, you can publish each version on it manually. From 33d160caaf1f11f0ed901690ebbaf92729ec280b Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Tue, 25 Feb 2025 08:24:49 +0100 Subject: [PATCH 15/32] Update after review Dennis --- book/_toc.yml | 1 - book/installation-and-setup/versioning.md | 18 +++++++++--------- .../versioning_archived.md | 5 ----- .../versioning_changelog.md | 6 +++++- book/installation-and-setup/versions_URLs.md | 13 +++++++------ 5 files changed, 21 insertions(+), 22 deletions(-) delete mode 100644 book/installation-and-setup/versioning_archived.md diff --git a/book/_toc.yml b/book/_toc.yml index f75fb9c..49d2083 100644 --- a/book/_toc.yml +++ b/book/_toc.yml @@ -32,7 +32,6 @@ parts: - file: installation-and-setup/versioning sections: - file: installation-and-setup/versions_URLs - - file: installation-and-setup/versioning_archived - file: installation-and-setup/versioning_changelog - file: installation-and-setup/publisher - file: installation-and-setup/copyright.md diff --git a/book/installation-and-setup/versioning.md b/book/installation-and-setup/versioning.md index 0d9fbb4..ad5022b 100644 --- a/book/installation-and-setup/versioning.md +++ b/book/installation-and-setup/versioning.md @@ -11,7 +11,7 @@ For example when making taylor-made books for specific academic years, you want Another example could be a book in which you add content and solutions during the course or you're fixing mistakes which may have misinformed the reader. If this is not directly visible in the table of contents, students might not be aware of these changes. Again, a changelog could be useful to inform the reader about the change. Furthermore, a smart versioning system might tell the reader something about the impact of the addition differentiating errata and additions. -You could also think of your published book which is referenced by other people. As content (and the location of this in your book) might change over time, other people can use versions to refer to a fixed version in time of your book. +You could also think of your published book which is referenced by other people. Don't be afraid, git makes it very easy to make this possible. Git allows you to go back in the git history to the source code of old versions. To make this as easy as possible for readers, you can assign versions instead of having the readers scroll through a long list of (not alway very descriptive) commit descriptions. Maybe this all sounds confusing and difficult. No worries! A use-case could be a book which progresses in time, but in which you don't want to deal with the additional hassle of versioning. Your book could be perfectly fine without any measures on this topic! @@ -21,13 +21,13 @@ Finally, you might consider publishing your book at an online publisher. This co So, there's a few use-cases for which different (combinations) of solutions exist. These are summarized in the table below in order of increasingly effort and impact. You can combine use-cases to your liking: -| Use-case | [Publish versions on separate URLs](./versions_URLs.md) | [Publish source code of all versions](./versioning_archived.md) | [Use TeachBooks versioning with a changelog](versioning_changelog) | [Publish your book with a publisher](./publisher.md) | -|:---:|:---:|:---:|:---:|:---:| -| Book changes over time, but you don't want to deal with versioning | | | | | -| Occasionally releasing a new version while keeping the previous version, with minimal effort for versioning | Recommended | Can be considered | | | -| Continuously adding content and solutions or updating crucial mistakes | | | Recommended | | -| Allow referencing specific versions | Can be considered |Recommended | Recommended | | -| Taylor-made book per academic year | Recommended | Can be considered | Recommended in case of students retaking a course | | -| Increase findability or benefit from publisher's brand | | | | Recommended | +| Use-case | [Publish versions on separate URLs](./versions_URLs.md) | [Use TeachBooks versioning with a changelog](versioning_changelog) | [Publish your book with a publisher](./publisher.md) | +|:---:|:---:|:---:|:---:| +| Book changes over time, but you don't want to deal with versioning | | | | +| Occasionally releasing a new version while keeping the previous version, with minimal effort for versioning | Recommended | | | +| Continuously adding content and solutions or updating crucial mistakes | | Recommended | | +| Allow referencing specific versions | Can be considered | Recommended | | +| Taylor-made book per academic year | Recommended | Recommended in case of students retaking a course | | +| Increase findability or benefit from publisher's brand | | | Recommended | Read more about each of these measures on the following sub-pages. \ No newline at end of file diff --git a/book/installation-and-setup/versioning_archived.md b/book/installation-and-setup/versioning_archived.md deleted file mode 100644 index 1b6746b..0000000 --- a/book/installation-and-setup/versioning_archived.md +++ /dev/null @@ -1,5 +0,0 @@ -# Publish source code of all versions - -In case you'd like other to use your source code and you've different versions, it might be useful to have the source code of those versions somewhere too. Don't be afraid, git makes it very easy to make this possible. - -Git allows you to go back in the git history to the source code of old versions. To make this as easy as possible for readers, use branches, tags and releases instead of having the readers scroll through a long list of (not alway very descriptive) commit descriptions. How to use tags and releases is described in [](./versioning_changelog.md) \ No newline at end of file diff --git a/book/installation-and-setup/versioning_changelog.md b/book/installation-and-setup/versioning_changelog.md index 26aa67d..86fa7bc 100644 --- a/book/installation-and-setup/versioning_changelog.md +++ b/book/installation-and-setup/versioning_changelog.md @@ -7,7 +7,7 @@ Versions combined with a changelog can be a very effective way to communicate bo 1. `academic_year.additions.errata` versioning for books tailed-made for courses in which content is added / adapted during the course and might be restructured extensively every year while remaining to be available in the original form. 2. `major.errata` versioning for books which are more stable over years, in which big changes are covered only by the version number. -We've come up with guidelines how to use the two TeachBooks-versioning options (adapted from {cite:p}`semver`): +We have come up with guidelines how to use the two TeachBooks-versioning options (adapted from {cite:p}`semver`): `````{tab-set} ````{tab-item} academic_year.additions.errata @@ -20,6 +20,8 @@ We've come up with guidelines how to use the two TeachBooks-versioning options ( 1. Precedence MUST be calculated by separating the version into academic year, additions and errata identifiers in that order. 2. Precedence is determined by the first difference when comparing each of these identifiers from left to right as follows: Academic year, additions and errata versions are always compared numerically. Example: 2024.0.0 < 2025.0.0 < 2025.1.0 < 2025.1.1. 7. The way in which the version number is incremented after the initial release should be explained in the README of the source code and in the book itself. + +An example can be seen in [the source repository of the Engineering Systems Optimization book](https://github.com/TUDelft-books/CME4501/tags) showing tags for different versions. ```` ````{tab-item} major.errata 1. A normal version number MUST take the form `major.errata` where `major`, and `errata` are non-negative integers, and MUST NOT contain leading zeroes. Each element MUST increase numerically. For instance: 9.0 -> 10.0 -> 11.0 @@ -74,6 +76,8 @@ Leads to for example: TeachBooks versioning added :::::: +An example can be found [here](https://oit.tudelft.nl/CME4501/2024/pages/linear_constrained_optimization_class.html) + ## Implement tags and releases Tags can be added to your source code by adding the version number as a tag to a specific commit. You can do so only locally. In GitHub Desktop this is done by clicking 'Create Tag...` for a specific commit in the History tab. diff --git a/book/installation-and-setup/versions_URLs.md b/book/installation-and-setup/versions_URLs.md index 8cc7e53..e39f6e5 100644 --- a/book/installation-and-setup/versions_URLs.md +++ b/book/installation-and-setup/versions_URLs.md @@ -1,22 +1,23 @@ # Publish version on separate (fixed) URLs -As soon as you've different versions online, you have to make a decision about URLs. Using the [](../external/deploy-book-workflow/README.md), you can release the different version of your book all under the same root URL. +As soon as you have different versions online, you have to make a decision about URLs. 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 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. -To share the built book / website of old versions for your book on GitHub you've a few options: +To share the built book / website of old versions for your book on GitHub you have a few options: - create a branch for each version. When doing this, [the GitHub workflow](../external/deploy-book-workflow/README.md) will build it on GitHub pages. Here's a few tips: - It's advised to use the version as branch name. In case of versions per academic year, you can just name each branch to the current academic year, this leads to the URL with the same name. In that case. - It is recommended to update the primary branch as the `PRIMARY BRANCH` when using the [GitHub workflow](gh-workflow-settings) whenever a new version is considered to be the most primary one. This ensures that readers 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. Alternatively, you can add a banner manually to `_config.yml`. - If you're using tags (as will be explained in [later](./versioning_changelog.md)), you can create a branch from a tag locally by running: `git branch `. - - If you've many version of the book, at some point you might reach the 1 GB GitHub Pages limit. This is only expected for extremely large books with a lot of non-text-based (binary) content. To prevent going over that limit, store large content not used for building the website (like images) on an external server. This can be another GitHub repository or a (paid) object store. + - If you have many version of the book, at some point you might reach the 1 GB GitHub Pages limit. This is only expected for extremely large books with a lot of non-text-based (binary) content. To prevent going over that limit, store large content not used for building the website (like images) on an external server. This can be another GitHub repository or a (paid) object store. + - An example can be found in the book 'Engineering Systems Optimization': it has two versions for readers online, the [2023-version](https://oit.tudelft.nl/CME4501/2023) and the [2024-version](https://oit.tudelft.nl/CME4501/2024), recognizable by the URL. Both versions originate from their respective branches in the [GitHub-repository](https://github.com/TUDelft-books/CME4501) - add a zip of the built book to the release in GitHub as binary asset. This requires readers to download the zip and open the html files locally, but doesn't require you to host it somewhere. This zip can be easily downloaded as an artifact from [the GitHub action](../external/deploy-book-workflow/README.md). An example can be found [here](https://github.com/TUDelft-books/CME4501/releases/tag/v2024.1.0). Note that this requires you to set up tags and releases, as explained in [](versioning_changelog.md) - Use [Read the Docs](../features/pull_request_build.md) to build a website for all your branches, forks and tags as Read the docs doesn't have a 1 GB limit, but has a very different URL structure and the free community version has advertisement. In case you're using tags and releases, refer to the URL of this built from your GitHub release to make sure that GitHub visitors find their way to Read the Docs. -If you've your own webserver, you can publish each version on it manually. +If you have your own webserver, you can publish each version on it manually. -Don't forget to explain how you organize your URLs and old versions in your README and eventually in the book itself too with a sentence like this: +Don't forget to explain how you organize your URLs and old versions in your README and eventually in the book itself too with a sentence like this (as can be seen in [this book](https://oit.tudelft.nl/CME4501/2024/intro.html) too): -> 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. +> This is the ``-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. From 5da8f5711bb19ff6608f80c1b8a293f578686c1b Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Tue, 25 Feb 2025 08:34:03 +0100 Subject: [PATCH 16/32] added versioning to tools to --- book/_toc.yml | 1 + book/credits.md | 2 +- book/features/versioning.md | 38 +++++++++++++++++++ book/installation-and-setup/versioning.md | 2 +- .../versioning_changelog.md | 34 ++--------------- book/installation-and-setup/versions_URLs.md | 2 +- 6 files changed, 45 insertions(+), 34 deletions(-) create mode 100644 book/features/versioning.md diff --git a/book/_toc.yml b/book/_toc.yml index 49d2083..c01916a 100644 --- a/book/_toc.yml +++ b/book/_toc.yml @@ -63,6 +63,7 @@ parts: - file: features/local_server - file: external/Nested-Books/README.md - file: features/update_env + - file: features/versioning - file: features/sphinx_extensions.md sections: - file: external/Download-Link-Replacer/README.md diff --git a/book/credits.md b/book/credits.md index c33d85c..64caec1 100644 --- a/book/credits.md +++ b/book/credits.md @@ -60,7 +60,7 @@ The following pages contain content written by others, part of has been reused a - Pages {ref}`copyright` and {ref}`copyright_considerations` include text from {cite:t}`tud_cip_24` that is used in the copyright checklist items. Original content licensed under CC BY. - Page {ref}`copyright_licenses`: {numref}`Figure %s` is included unmodified, along with paraphrased and quoted text (including hyperlinks) from {cite:t}`hall21`. Work is licensed under CC BY. - Page {ref}`copyright_licenses`: {numref}`Figure %s` is included unmodified. Work is provided by Kennisland under a CC0 license. Accessed at [](https://wiki.creativecommons.org/wiki/File:CC_License_Compatibility_Chart.png) on December 17, 2024. -- page [](./installation-and-setup/versioning_changelog.md): includes text from {cite:t}`semver` that has been modified. Original content licensed under CC BY 3.0. +- page [](./features/versioning.md): includes text from {cite:t}`semver` that has been modified. Original content licensed under CC BY 3.0. diff --git a/book/features/versioning.md b/book/features/versioning.md new file mode 100644 index 0000000..c769c82 --- /dev/null +++ b/book/features/versioning.md @@ -0,0 +1,38 @@ +# TeachBooks Versioning + +> This page reuses adapted CC BY 3.0 content from Tom Preston-Werner {cite:t}`semver`. {fa}`quote-left`{ref}`Find out more here.` + +Inspired by versioning systems in software management (i.e. semantic and CalVer versioning) TeachBooks suggests a versioning guideline in which the version number tells the reader about the impact of the change. This might more suitable for your online books than the more traditional way of versioning paper books (version 1, 2, etc.), because of the amount of edits which online books allow. We recommend TeachBooks versioning, which comes in two flavors: + +1. `academic_year.additions.errata` versioning for books tailed-made for courses in which content is added / adapted during the course and might be restructured extensively every year while remaining to be available in the original form. +2. `major.errata` versioning for books which are more stable over years, in which big changes are covered only by the version number. + +We have come up with guidelines how to use the two TeachBooks-versioning options (adapted from {cite:p}`semver`): + +`````{tab-set} +````{tab-item} academic_year.additions.errata +1. A normal version number MUST take the form `academic_year.additions.errata` where `academic_year` is the academic year in which the book is used, and `additions`, and `errata` are non-negative integers, and MUST NOT contain leading zeroes. Each element MUST increase numerically. For instance: 2025.9.0 -> 2025.10.0 -> 2025.11.0 +2. Once a versioned book has been released, the contents of that version MUST NOT be modified. Any modifications MUST be released as a new version. +3. Errata versions MUST be incremented if a small change is made which should be communicated to the reader in both the source code and in the book itself. If the small change is not crucial (like a simple typo), you might consider not defining it as a new version but combining it with other changes in the next errata or additions version. +4. Additions version MUST be incremented if an addition is made to the book. It MUST be communicated in both the source code and in the book itself. It MAY include errata level changes. The errata version MUST be reset to 0 when the addition version is incremented. +5. Academic year version MUST be incremented if a fresh book is started for which additions will follow later. It MUST be communicated in both the source code and in the book itself. Additions and errata versions MUST be reset to 0 when academic version is incremented. +6. Precedence refers to how versions are compared to each other when ordered. + 1. Precedence MUST be calculated by separating the version into academic year, additions and errata identifiers in that order. + 2. Precedence is determined by the first difference when comparing each of these identifiers from left to right as follows: Academic year, additions and errata versions are always compared numerically. Example: 2024.0.0 < 2025.0.0 < 2025.1.0 < 2025.1.1. +7. The way in which the version number is incremented after the initial release should be explained in the README of the source code and in the book itself. + +An example can be seen in [the source repository of the Engineering Systems Optimization book](https://github.com/TUDelft-books/CME4501/tags) showing tags for different versions. +```` +````{tab-item} major.errata +1. A normal version number MUST take the form `major.errata` where `major`, and `errata` are non-negative integers, and MUST NOT contain leading zeroes. Each element MUST increase numerically. For instance: 9.0 -> 10.0 -> 11.0 +2. Once a versioned book has been released, the contents of that version MUST NOT be modified. Any modifications MUST be released as a new version. +3. Errata versions MUST be incremented if a small change is made which should be communicated to the reader in both the source code and in the book itself. If the small change is not crucial (like a simple typo), you might consider not defining it as a new version but combining it with other changes in the next major version. +5. Major versions MUST be incremented if a substantial restructure or additions is made. It MUST be communicated in both the source code and in the book itself. Errata versions MUST be reset to 0 when the major version is incremented. +6. Precedence refers to how versions are compared to each other when ordered. + 1. Precedence MUST be calculated by separating the version into major and errata identifiers in that order. + 2. Precedence is determined by the first difference when comparing each of these identifiers from left to right as follows: major and errata versions are always compared numerically. Example: 1.0 < 2.0 < 2.1. +7. The way in which the version number is incremented after the initial release should be explained in the README of the source code and in the book itself. +```` +````` + +Read [](../installation-and-setup/versioning_changelog.md) on how to combine this with a changelog, tags and releases! \ No newline at end of file diff --git a/book/installation-and-setup/versioning.md b/book/installation-and-setup/versioning.md index ad5022b..e265115 100644 --- a/book/installation-and-setup/versioning.md +++ b/book/installation-and-setup/versioning.md @@ -11,7 +11,7 @@ For example when making taylor-made books for specific academic years, you want Another example could be a book in which you add content and solutions during the course or you're fixing mistakes which may have misinformed the reader. If this is not directly visible in the table of contents, students might not be aware of these changes. Again, a changelog could be useful to inform the reader about the change. Furthermore, a smart versioning system might tell the reader something about the impact of the addition differentiating errata and additions. -You could also think of your published book which is referenced by other people. Don't be afraid, git makes it very easy to make this possible. Git allows you to go back in the git history to the source code of old versions. To make this as easy as possible for readers, you can assign versions instead of having the readers scroll through a long list of (not alway very descriptive) commit descriptions. +You could also think of your published book which is referenced by other people. Don't be afraid, git makes it very easy to make this possible. Git allows you to go back in the git history. To make this as easy as possible for readers, you can assign versions using TeachBooks versioning instead of having the readers scroll through a long list of (not alway very descriptive) commit descriptions. Maybe this all sounds confusing and difficult. No worries! A use-case could be a book which progresses in time, but in which you don't want to deal with the additional hassle of versioning. Your book could be perfectly fine without any measures on this topic! diff --git a/book/installation-and-setup/versioning_changelog.md b/book/installation-and-setup/versioning_changelog.md index 86fa7bc..3be6d74 100644 --- a/book/installation-and-setup/versioning_changelog.md +++ b/book/installation-and-setup/versioning_changelog.md @@ -1,39 +1,11 @@ # TeachBooks versioning with changelog -> This page reuses adapted CC BY 3.0 content from Tom Preston-Werner {cite:t}`semver`. {fa}`quote-left`{ref}`Find out more here.` +Versions combined with a changelog can be a very effective way to communicate book changes to the reader and allow reuse of specific versions. We recommend [TeachBooks versioning]((../features/versioning.md)), which comes in two flavors: -Versions combined with a changelog can be a very effective way to communicate book changes to the reader and allow reuse of specific versions. Inspired by versioning systems in software management (i.e. semantic and CalVer versioning) you can define a version guideline in which the version number tells the reader about the impact of the change. This might more suitable for your online books than the more traditional way of versioning paper books (version 1, 2, etc.), because of the amount of edits which online books allow. We recommend TeachBooks versioning, which comes in two flavors: - -1. `academic_year.additions.errata` versioning for books tailed-made for courses in which content is added / adapted during the course and might be restructured extensively every year while remaining to be available in the original form. +1. `academic_year.additions.errata` versioning for books tailed-made for courses in which content is added / adapted during the course and might be restructured extensively every year while remaining to be available in the original form. An example can be seen in [the source repository of the Engineering Systems Optimization book](https://github.com/TUDelft-books/CME4501/tags) showing tags for different versions. 2. `major.errata` versioning for books which are more stable over years, in which big changes are covered only by the version number. -We have come up with guidelines how to use the two TeachBooks-versioning options (adapted from {cite:p}`semver`): - -`````{tab-set} -````{tab-item} academic_year.additions.errata -1. A normal version number MUST take the form `academic_year.additions.errata` where `academic_year` is the academic year in which the book is used, and `additions`, and `errata` are non-negative integers, and MUST NOT contain leading zeroes. Each element MUST increase numerically. For instance: 2025.9.0 -> 2025.10.0 -> 2025.11.0 -2. Once a versioned book has been released, the contents of that version MUST NOT be modified. Any modifications MUST be released as a new version. -3. Errata versions MUST be incremented if a small change is made which should be communicated to the reader in both the source code and in the book itself. If the small change is not crucial (like a simple typo), you might consider not defining it as a new version but combining it with other changes in the next errata or additions version. -4. Additions version MUST be incremented if an addition is made to the book. It MUST be communicated in both the source code and in the book itself. It MAY include errata level changes. The errata version MUST be reset to 0 when the addition version is incremented. -5. Academic year version MUST be incremented if a fresh book is started for which additions will follow later. It MUST be communicated in both the source code and in the book itself. Additions and errata versions MUST be reset to 0 when academic version is incremented. -6. Precedence refers to how versions are compared to each other when ordered. - 1. Precedence MUST be calculated by separating the version into academic year, additions and errata identifiers in that order. - 2. Precedence is determined by the first difference when comparing each of these identifiers from left to right as follows: Academic year, additions and errata versions are always compared numerically. Example: 2024.0.0 < 2025.0.0 < 2025.1.0 < 2025.1.1. -7. The way in which the version number is incremented after the initial release should be explained in the README of the source code and in the book itself. - -An example can be seen in [the source repository of the Engineering Systems Optimization book](https://github.com/TUDelft-books/CME4501/tags) showing tags for different versions. -```` -````{tab-item} major.errata -1. A normal version number MUST take the form `major.errata` where `major`, and `errata` are non-negative integers, and MUST NOT contain leading zeroes. Each element MUST increase numerically. For instance: 9.0 -> 10.0 -> 11.0 -2. Once a versioned book has been released, the contents of that version MUST NOT be modified. Any modifications MUST be released as a new version. -3. Errata versions MUST be incremented if a small change is made which should be communicated to the reader in both the source code and in the book itself. If the small change is not crucial (like a simple typo), you might consider not defining it as a new version but combining it with other changes in the next major version. -5. Major versions MUST be incremented if a substantial restructure or additions is made. It MUST be communicated in both the source code and in the book itself. Errata versions MUST be reset to 0 when the major version is incremented. -6. Precedence refers to how versions are compared to each other when ordered. - 1. Precedence MUST be calculated by separating the version into major and errata identifiers in that order. - 2. Precedence is determined by the first difference when comparing each of these identifiers from left to right as follows: major and errata versions are always compared numerically. Example: 1.0 < 2.0 < 2.1. -7. The way in which the version number is incremented after the initial release should be explained in the README of the source code and in the book itself. -```` -````` +The details of TeachBooks versioning are covered [here](../features/versioning.md) ## Changelog To communicate changes, we advise creating a changelog in the book. The [template](https://github.com/TeachBooks/template/blob/main/book/changelog.md) contains an empty changelog to fill: diff --git a/book/installation-and-setup/versions_URLs.md b/book/installation-and-setup/versions_URLs.md index e39f6e5..347067c 100644 --- a/book/installation-and-setup/versions_URLs.md +++ b/book/installation-and-setup/versions_URLs.md @@ -8,7 +8,7 @@ To share the built book / website of old versions for your book on GitHub you ha - create a branch for each version. When doing this, [the GitHub workflow](../external/deploy-book-workflow/README.md) will build it on GitHub pages. Here's a few tips: - It's advised to use the version as branch name. In case of versions per academic year, you can just name each branch to the current academic year, this leads to the URL with the same name. In that case. - It is recommended to update the primary branch as the `PRIMARY BRANCH` when using the [GitHub workflow](gh-workflow-settings) whenever a new version is considered to be the most primary one. This ensures that readers 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. Alternatively, you can add a banner manually to `_config.yml`. + - 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. Alternatively, you can add a banner manually to `_config.yml`, as explained [here](../basic-features/banner.md). - If you're using tags (as will be explained in [later](./versioning_changelog.md)), you can create a branch from a tag locally by running: `git branch `. - If you have many version of the book, at some point you might reach the 1 GB GitHub Pages limit. This is only expected for extremely large books with a lot of non-text-based (binary) content. To prevent going over that limit, store large content not used for building the website (like images) on an external server. This can be another GitHub repository or a (paid) object store. - An example can be found in the book 'Engineering Systems Optimization': it has two versions for readers online, the [2023-version](https://oit.tudelft.nl/CME4501/2023) and the [2024-version](https://oit.tudelft.nl/CME4501/2024), recognizable by the URL. Both versions originate from their respective branches in the [GitHub-repository](https://github.com/TUDelft-books/CME4501) From f52339f316a5ae5b9ab3b7c91b1b91e540e9ce0f Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Tue, 25 Feb 2025 08:39:13 +0100 Subject: [PATCH 17/32] refer to draft versioning too --- book/installation-and-setup/collab.md | 1 + book/installation-and-setup/versions_URLs.md | 2 +- 2 files changed, 2 insertions(+), 1 deletion(-) diff --git a/book/installation-and-setup/collab.md b/book/installation-and-setup/collab.md index de7f906..9db1239 100644 --- a/book/installation-and-setup/collab.md +++ b/book/installation-and-setup/collab.md @@ -15,6 +15,7 @@ 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. 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}`fa-github`, suggest edit {fa}`pencil` and issue button {fa}`lightbulb`](https://jupyterbook.org/en/stable/basics/repository.html) is advised. +(draft_book)= ## Define draft version of book If there's many people working on different parts of the book and material is staged for publication to students, 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. diff --git a/book/installation-and-setup/versions_URLs.md b/book/installation-and-setup/versions_URLs.md index 347067c..c4c24fe 100644 --- a/book/installation-and-setup/versions_URLs.md +++ b/book/installation-and-setup/versions_URLs.md @@ -1,6 +1,6 @@ # Publish version on separate (fixed) URLs -As soon as you have different versions online, you have to make a decision about URLs. Using the [](../external/deploy-book-workflow/README.md), you can release the different version of your book all under the same root URL. +As soon as you have different versions online, you have to make a decision about URLs. Using the [](../external/deploy-book-workflow/README.md), you can release the different version of your book all under the same root URL. So, it uses the same workflow as used for draft versions of your book as describe [before](draft_book), the only difference being that URLs of draft versions are generally not shared publicly. 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. From 70737d9ecd09966a238aff88ab68d11966a3d1f4 Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Tue, 25 Feb 2025 08:43:04 +0100 Subject: [PATCH 18/32] typo --- book/installation-and-setup/versioning_changelog.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/book/installation-and-setup/versioning_changelog.md b/book/installation-and-setup/versioning_changelog.md index 3be6d74..d6c69be 100644 --- a/book/installation-and-setup/versioning_changelog.md +++ b/book/installation-and-setup/versioning_changelog.md @@ -1,6 +1,6 @@ # TeachBooks versioning with changelog -Versions combined with a changelog can be a very effective way to communicate book changes to the reader and allow reuse of specific versions. We recommend [TeachBooks versioning]((../features/versioning.md)), which comes in two flavors: +Versions combined with a changelog can be a very effective way to communicate book changes to the reader and allow reuse of specific versions. We recommend [TeachBooks versioning](../features/versioning.md), which comes in two flavors: 1. `academic_year.additions.errata` versioning for books tailed-made for courses in which content is added / adapted during the course and might be restructured extensively every year while remaining to be available in the original form. An example can be seen in [the source repository of the Engineering Systems Optimization book](https://github.com/TUDelft-books/CME4501/tags) showing tags for different versions. 2. `major.errata` versioning for books which are more stable over years, in which big changes are covered only by the version number. From 505e8fff730bfa59729f3aab511798c0b32105be Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Tue, 25 Feb 2025 16:26:30 +0100 Subject: [PATCH 19/32] Separate local server and draft-release workflow fully Based on how it's used in the book-editing process --- book/features/local_server.md | 46 ++++++++++++++++++ book/features/teachbooks.md | 92 +++++------------------------------ 2 files changed, 58 insertions(+), 80 deletions(-) diff --git a/book/features/local_server.md b/book/features/local_server.md index cea8930..9540355 100644 --- a/book/features/local_server.md +++ b/book/features/local_server.md @@ -28,6 +28,7 @@ Remember that the browser is serving static files provided by the local server a You should reload the page if you are editing and rebuilding the book. You can try `CTRL+R` `ctrl`+`F5`. If this does not work, on Chrome try right-clicking somewhere on the page, select \"Inspect\", open the \"Network\" tab, then reload with `CTRL+R`. ``` +(teachbooks-serve)= ## TeachBooks Server: `teachbooks serve` If you have the TeachBooks Python package installed (`pip install teachbooks`), starting a server is as simple as: @@ -38,6 +39,51 @@ teachbooks serve See the {ref}`TeachBooks Package page ` for additional guidance on using the CLI tool. + +By default it assumes you have a book in `./book/`, are running the command from the root `./` of your repository and will serve `./book/_build/html`. If not, it will serve the repository root. You can also specify the directory to serve: + +```bash +teachbooks serve path unconventional_book_dir/_build/html +``` + +```{tip} +Remember that the browser is serving static files provided by the local server and does not always keep track when they are updated. + +You should reload the page if you are editing and rebuilding the book. You can try `CTRL+R` `ctrl`+`F5`. If this does not work, on Chrome try right-clicking somewhere on the page, select \"Inspect\", open the \"Network\" tab, then reload with `CTRL+R`. +``` + +To stop the server, simply run + +```bash +teachbooks serve stop +``` + +The CLI tool is set up to make the book edit and check workflow as easy as possible locally: +- you can rebuild the book without restarting the server. +- it reuses an existing server if already running. +- it prints the URL where the book is served after building the book to easily access it by clicking the link in standard output. +- the `teachbooks serve stop` command prevents Python processes running in the backgroudn and slowing down your computer (it saves the server state in a pickle file). + +### Installation of TeachBooks + +The TeachBooks package is currently [available on PyPI](https://pypi.org/project/teachbooks/) and can be installed as follows: + +``` +pip install teachbooks +``` + +The first stable release (`v1.0.0`) is expected to be released in Spring 2025. Until then the package is very much useable but will be updated frequently. Therefore, get in the habit of updating the package regularly: + +```bash +pip install --upgrade teachbooks +``` + +We recommend you install this in an environment that is specifically dedicated for building books. Python virtual environments are a good way to manage this and would be consistent with what is used by the GitHub servers via the {ref}`Deploy Book Workflow `. However, if you use non-Python tools to edit and check your book, a Conda environment may be a better choice. + +The package is a CLI tool that primarily provides a wrapper around the Jupyter Book package which is used for pre- and postprocessing. In this case "wrapper" refers to the CLI usage: CLI commands generally invoke `jupyter-book` commands internally; the `jupyter-book` package is _not_ distributed within the `teachbooks` package. + +The source code and function of the package will eventually be documented on a Sphinx-built website ([teachbooks.io/TeachBooks/](https://teachbooks.io/TeachBooks/)), however, this is currently still under construction. + ## Live Server: a VS Code Extension A local server is easy to initialize directly in VS Code using the Live Server extension. Once installed, it can be activated with a "Go Live" button in the bottom right corner of VS Code. The extension will automatically serve index.html, so depending on your book build settings you may need to navigate to the correct directory/file manually using the URL address in the browser. diff --git a/book/features/teachbooks.md b/book/features/teachbooks.md index 4caf9a8..570536c 100644 --- a/book/features/teachbooks.md +++ b/book/features/teachbooks.md @@ -1,65 +1,13 @@ (teachbooks-package)= -# Pre- and postprocessing book +# Draft-release workflow ```{admonition} User types :class: tip -This page is useful for all users to understand how the book building process works and can be influenced, although the implementation is likely going to be carried out by User Types 3, 4 or 5. +This page is useful for user type 3-5. ``` {bdg-secondary}`Python Package` -The package is a CLI tool that primarily provides a wrapper around the Jupyter Book package which is used for pre- and postprocessing. In this case "wrapper" refers to the CLI usage: CLI commands generally invoke `jupyter-book` commands internally; the `jupyter-book` package is _not_ distributed within the `teachbooks` package. - -The source code and function of the package will eventually be documented on a Sphinx-built website ([teachbooks.io/TeachBooks/](https://teachbooks.io/TeachBooks/)), however, this is currently still under construction. - -## Primary Features - -Key features (described in the sections below) include: -- pre- and post-processing steps for the Jupyter Book package -- Draft-Release Workflow (`teachbooks build --release book`) -- Start and stop a local server to check your book (`teachbooks serve`) - -This list will be updated periodically as features are added. Check the [Release Notes](https://github.com/TeachBooks/TeachBooks/releases) in the GitHub repository for the most up-to-date information. - -## Installation - -The package is currently only [available on PyPI](https://pypi.org/project/teachbooks/) and can be installed as follows: - -``` -pip install teachbooks -``` - -The first stable release (`v1.0.0`) is expected to be released in Spring 2025. Until then the package is very much useable but will be updated frequently. Therefore, get in the habit of updating the package regularly: - -```bash -pip install --upgrade teachbooks -``` - -We recommend you install this in an environment that is specifically dedicated for building books. Python virtual environments are a good way to manage this and would be consistent with what is used by the GitHub servers via the {ref}`Deploy Book Workflow `. However, if you use non-Python tools to edit and check your book, a Conda environment may be a better choice. - -## Contribute - -This tool's repository is stored on [GitHub](https://github.com/TeachBooks/TeachBooks). The `README.md` of the repository describes how you can contribute---don't hesitate to make an issue if you would like to request new features! - -## Description of Features - -(teachbooks-pre-post)= -### Jupyter Book Pre- and Post-Processing - -Using the teachbooks CLI in the book building process generally invokes Jupyter Book. Many of the features in this package are then invoked in the stages before and after this command. The process generally includes the following steps: - -1. Edit source code and prepare to build a book -2. Execute `teachbooks [OPTIONS] COMMAND [ARGS]` -3. Pre-processing step: carried out by `teachbooks` -4. Build step: book is built using `jupyter book [OPTIONS] COMMAND [ARGS]` -5. Post-processing step: carried out by `teachbooks` - -Additional options like those used in jupyterbook (`--all` for example) can be used with `teachbooks` in an identical usage as with the `jupyter-book` command. - -```{note} -The pre- and post-processing steps have not yet bet formally defined; they only exist implicitly in the source code for the `build` CLI command. If you are interested in suggesting a feature or contributing to the package, please visit the [GitHub repository](https://github.com/teachbooks/teachbooks) and take a look at the Discussions and Issues. For example, [this one](https://github.com/orgs/TeachBooks/discussions/28). -``` - (teachbooks-draft-release)= ### Draft-Release Workflow @@ -107,38 +55,22 @@ Note that `teachbooks build book` would build a book without stripping the tagge TeachBooks: running build with strategy 'draft' ``` -(teachbooks-serve)= -### Local Python server +## Installation -```{tip} -Visit the {ref}`Local Server page ` for an explanation of why you need a local server. +The package is currently [available on PyPI](https://pypi.org/project/teachbooks/) and can be installed as follows: + +``` +pip install teachbooks ``` -The TeachBooks Python package includes a command line interface (CLI) that can be used to start a local server: +The first stable release (`v1.0.0`) is expected to be released in Spring 2025. Until then the package is very much useable but will be updated frequently. Therefore, get in the habit of updating the package regularly: ```bash -teachbooks serve -``` -By default it assumes you have a book in `./book/`, are running the command from the root `./` of your repository and will serve `./book/_build/html`. If not, it will serve the repository root. You can also specify the directory to serve: - -```bash -teachbooks serve path unconventional_book_dir/_build/html +pip install --upgrade teachbooks ``` -```{tip} -Remember that the browser is serving static files provided by the local server and does not always keep track when they are updated. +We recommend you install this in an environment that is specifically dedicated for building books. Python virtual environments are a good way to manage this and would be consistent with what is used by the GitHub servers via the {ref}`Deploy Book Workflow `. However, if you use non-Python tools to edit and check your book, a Conda environment may be a better choice. -You should reload the page if you are editing and rebuilding the book. You can try `CTRL+R` `ctrl`+`F5`. If this does not work, on Chrome try right-clicking somewhere on the page, select \"Inspect\", open the \"Network\" tab, then reload with `CTRL+R`. -``` +The package is a CLI tool that primarily provides a wrapper around the Jupyter Book package which is used for pre- and postprocessing. In this case "wrapper" refers to the CLI usage: CLI commands generally invoke `jupyter-book` commands internally; the `jupyter-book` package is _not_ distributed within the `teachbooks` package. -To stop the server, simply run - -```bash -teachbooks serve stop -``` - -The CLI tool is set up to make the book edit and check workflow as easy as possible locally: -- you can rebuild the book without restarting the server. -- it reuses an existing server if already running. -- it prints the URL where the book is served after building the book to easily access it by clicking the link in standard output. -- the `teachbooks serve stop` command prevents Python processes running in the backgroudn and slowing down your computer (it saves the server state in a pickle file). \ No newline at end of file +The source code and function of the package will eventually be documented on a Sphinx-built website ([teachbooks.io/TeachBooks/](https://teachbooks.io/TeachBooks/)), however, this is currently still under construction. \ No newline at end of file From fed8024961b2ee21e03f6c8f54e2ac845029ace7 Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Tue, 25 Feb 2025 17:16:32 +0100 Subject: [PATCH 20/32] Added tags on GitHub Thanks @BSchilperoort --- .../figures/tags_github.png | Bin 0 -> 29867 bytes .../versioning_changelog.md | 20 ++++++++++++++++-- 2 files changed, 18 insertions(+), 2 deletions(-) create mode 100644 book/installation-and-setup/figures/tags_github.png diff --git a/book/installation-and-setup/figures/tags_github.png b/book/installation-and-setup/figures/tags_github.png new file mode 100644 index 0000000000000000000000000000000000000000..0092a245951efd701097c2e85738362b5392ddd0 GIT binary patch literal 29867 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 KLgn*UAO8mmuI}al literal 0 HcmV?d00001 diff --git a/book/installation-and-setup/versioning_changelog.md b/book/installation-and-setup/versioning_changelog.md index d6c69be..f0981b5 100644 --- a/book/installation-and-setup/versioning_changelog.md +++ b/book/installation-and-setup/versioning_changelog.md @@ -51,7 +51,19 @@ TeachBooks versioning added An example can be found [here](https://oit.tudelft.nl/CME4501/2024/pages/linear_constrained_optimization_class.html) ## Implement tags and releases -Tags can be added to your source code by adding the version number as a tag to a specific commit. You can do so only locally. In GitHub Desktop this is done by clicking 'Create Tag...` for a specific commit in the History tab. +Tags can be added to your source code by adding the version number as a tag to a specific commit. + +You can do so in GitHub when creating a new release (on the `Code` page of your repository.) There, you can enter a name for your tag and select one of your branches or recent commits: + +```{figure} figures/tags_github.png +--- +width: 500px +align: center +--- + +``` + +Locally, you can do so in GitHub Desktop by clicking 'Create Tag...` for a specific commit in the History tab. ```{figure} figures/tags.png --- @@ -61,4 +73,8 @@ align: center ``` -Once the tags is pushed to GitHub/GitLab. You can create a release of the version by clicking `Release` on the `Code` page of your repository. There you can select a tag and generate release notes. It's recommended to add the relevant part of the changelog too. An example can be found [here](https://github.com/CIEM5000-2025/book/releases/tag/v2025.2.0) +Once the tags is pushed to GitHub/GitLab. You can create a release of the version by clicking `Release` on the `Code` page of your repository. There you can select a tag and generate release notes. + +It's recommended to add the relevant part of the changelog to the release notes on GitHub. An example can be found [here](https://github.com/CIEM5000-2025/book/releases/tag/v2025.2.0) + + From fe04a2fb32210f0cb7f823b0d632cacfecd5b917 Mon Sep 17 00:00:00 2001 From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com> Date: Tue, 25 Feb 2025 16:22:01 +0000 Subject: [PATCH 21/32] Bump book/external/Nested-Books from `94d5835` to `21c0a70` Bumps [book/external/Nested-Books](https://github.com/TeachBooks/Nested-Books) from `94d5835` to `21c0a70`. - [Commits](https://github.com/TeachBooks/Nested-Books/compare/94d583570178ede097f8216b2aa06996d6e4b9ee...21c0a704f4b4a932e204991ddeb051f7487d9ac4) --- updated-dependencies: - dependency-name: book/external/Nested-Books dependency-type: direct:production ... Signed-off-by: dependabot[bot] --- book/external/Nested-Books | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/book/external/Nested-Books b/book/external/Nested-Books index 94d5835..21c0a70 160000 --- a/book/external/Nested-Books +++ b/book/external/Nested-Books @@ -1 +1 @@ -Subproject commit 94d583570178ede097f8216b2aa06996d6e4b9ee +Subproject commit 21c0a704f4b4a932e204991ddeb051f7487d9ac4 From c373899f642f7a0f1e3f2ca766a4d1253151ffe4 Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Wed, 26 Feb 2025 08:26:17 +0100 Subject: [PATCH 22/32] Update publisher.md --- book/installation-and-setup/publisher.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/book/installation-and-setup/publisher.md b/book/installation-and-setup/publisher.md index 55111a0..236715f 100644 --- a/book/installation-and-setup/publisher.md +++ b/book/installation-and-setup/publisher.md @@ -1,6 +1,6 @@ # Publishing your book with a 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 +You can choose to publish your online book with a publisher. This could increase findability of your book, but may have consequenses on the ease of editing, choice of platforms, versioning restrictions, and copyright and licensing considerations. 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. From 9a1d306867bdb4542eff53996a3a79deedc8b010 Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Thu, 27 Feb 2025 16:21:27 +0100 Subject: [PATCH 23/32] Toolbar options @douden Co-Authored-By: Dennis den Ouden-van der Horst <49307154+douden@users.noreply.github.com> --- book/features/figures/toolbar.png | Bin 0 -> 3503 bytes book/features/widgets.ipynb | 19 ++++++++++++++++++- 2 files changed, 18 insertions(+), 1 deletion(-) create mode 100644 book/features/figures/toolbar.png diff --git a/book/features/figures/toolbar.png b/book/features/figures/toolbar.png new file mode 100644 index 0000000000000000000000000000000000000000..1960d9c6da976bfcaa69af204b091a120572ddab GIT binary patch literal 3503 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 literal 0 HcmV?d00001 diff --git a/book/features/widgets.ipynb b/book/features/widgets.ipynb index 2d441bb..cf1f593 100644 --- a/book/features/widgets.ipynb +++ b/book/features/widgets.ipynb @@ -40,7 +40,24 @@ "```python\n", "input_slider = widgets.FloatSlider(value=0, min=0, max=10, step=1, description='Input variable:') # Defines a widget, more options than just FloatSlider\n", "widgets.interact(update_plot, input_variable_from_widget = input_slider);\n", - "```\n" + "```\n", + "\n", + "Finally, When using `%matplotlib widget`, there's the following toolbar:\n", + "\n", + "![](./figures/toolbar.png)\n", + "\n", + "Which only shows up when you hoover above. If you want to disable the toolbar you can use:\n", + "```python\n", + "fig = plt.gcf()\n", + "fig.canvas.toolbar_visible = False\n", + "```\n", + "\n", + "If you want it to be visible even if you don't hoover above it, use:\n", + "\n", + "```python\n", + "fig = plt.gcf()\n", + "fig.canvas.toolbar_visible = True\n", + "```" ] }, { From 5d2be819fad59d2827cef9485305a2a001f7384a Mon Sep 17 00:00:00 2001 From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com> Date: Fri, 28 Feb 2025 07:57:39 +0000 Subject: [PATCH 24/32] Bump book/external/sphinx-iframes from `7663b1f` to `077ba23` Bumps [book/external/sphinx-iframes](https://github.com/TeachBooks/sphinx-iframes) from `7663b1f` to `077ba23`. - [Release notes](https://github.com/TeachBooks/sphinx-iframes/releases) - [Commits](https://github.com/TeachBooks/sphinx-iframes/compare/7663b1f326e11617a8a35aec7cda0f3d67135551...077ba23fa29ef1f0dd454f2ebf93c107923d1068) --- updated-dependencies: - dependency-name: book/external/sphinx-iframes dependency-type: direct:production ... Signed-off-by: dependabot[bot] --- book/external/sphinx-iframes | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/book/external/sphinx-iframes b/book/external/sphinx-iframes index 7663b1f..077ba23 160000 --- a/book/external/sphinx-iframes +++ b/book/external/sphinx-iframes @@ -1 +1 @@ -Subproject commit 7663b1f326e11617a8a35aec7cda0f3d67135551 +Subproject commit 077ba23fa29ef1f0dd454f2ebf93c107923d1068 From eb538859fbb48662038882aea13cfb8f0832ba68 Mon Sep 17 00:00:00 2001 From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com> Date: Fri, 28 Feb 2025 08:08:00 +0000 Subject: [PATCH 25/32] Bump book/external/Nested-Books from `21c0a70` to `a8e57da` Bumps [book/external/Nested-Books](https://github.com/TeachBooks/Nested-Books) from `21c0a70` to `a8e57da`. - [Commits](https://github.com/TeachBooks/Nested-Books/compare/21c0a704f4b4a932e204991ddeb051f7487d9ac4...a8e57da25302d47806ad1fe4288950c438562199) --- updated-dependencies: - dependency-name: book/external/Nested-Books dependency-type: direct:production ... Signed-off-by: dependabot[bot] --- book/external/Nested-Books | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/book/external/Nested-Books b/book/external/Nested-Books index 21c0a70..a8e57da 160000 --- a/book/external/Nested-Books +++ b/book/external/Nested-Books @@ -1 +1 @@ -Subproject commit 21c0a704f4b4a932e204991ddeb051f7487d9ac4 +Subproject commit a8e57da25302d47806ad1fe4288950c438562199 From 8bb6a02ae6f255a87064bfe98719e7fe4f8a5c54 Mon Sep 17 00:00:00 2001 From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com> Date: Sun, 2 Mar 2025 22:49:21 +0000 Subject: [PATCH 26/32] Bump sphinx-iframes from 1.0.3 to 1.0.5 Bumps [sphinx-iframes](https://github.com/TeachBooks/sphinx-iframes) from 1.0.3 to 1.0.5. - [Release notes](https://github.com/TeachBooks/sphinx-iframes/releases) - [Commits](https://github.com/TeachBooks/sphinx-iframes/compare/v1.0.3...v1.0.5) --- updated-dependencies: - dependency-name: sphinx-iframes dependency-type: direct:production update-type: version-update:semver-patch ... Signed-off-by: dependabot[bot] --- requirements.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/requirements.txt b/requirements.txt index e0559d4..1d686bb 100644 --- a/requirements.txt +++ b/requirements.txt @@ -7,7 +7,7 @@ sphinx-image-inverter == 1.1.2 sphinx-exercise == 1.0.1 sphinx-proof == 0.2.0 sphinx-named-colors == 1.0.1 -sphinx-iframes == 1.0.3 +sphinx-iframes == 1.0.5 sphinx-prime-applets == 1.0.1 git+https://github.com/TeachBooks/Sphinx-Thebe From 76a30708897b63ee80efd6738313480112e3300a Mon Sep 17 00:00:00 2001 From: Robert Lanzafame Date: Tue, 4 Mar 2025 09:06:50 +0100 Subject: [PATCH 27/32] remove duplicate header --- book/features/teachbooks.md | 5 +---- 1 file changed, 1 insertion(+), 4 deletions(-) diff --git a/book/features/teachbooks.md b/book/features/teachbooks.md index 570536c..7b9b14f 100644 --- a/book/features/teachbooks.md +++ b/book/features/teachbooks.md @@ -1,5 +1,5 @@ (teachbooks-package)= -# Draft-release workflow +# Draft-Release Workflow ```{admonition} User types :class: tip @@ -8,9 +8,6 @@ This page is useful for user type 3-5. {bdg-secondary}`Python Package` -(teachbooks-draft-release)= -### Draft-Release Workflow - Often it is necessary to prepare, review and edit materials in parallel to material that is currently being used by students, or another target audience. This workflow enables an author to easily maintain separate versions of a book without having to repeatedly comment out lines of a table of contents or page when building different versions. It is also easy to implement in CI/CD settings (it is already implemented in the {ref}Deploy Book Workflow `, which builds our TeachBooks). ```{admonition} Why is this useful? From d470c60f26d2ddaae83c3cd68d22613183508de3 Mon Sep 17 00:00:00 2001 From: Robert Lanzafame Date: Tue, 4 Mar 2025 09:35:42 +0100 Subject: [PATCH 28/32] why git? tips --- book/installation-and-setup/git.md | 30 ++++++++++++++++++++++++------ 1 file changed, 24 insertions(+), 6 deletions(-) diff --git a/book/installation-and-setup/git.md b/book/installation-and-setup/git.md index b9559d2..281af53 100644 --- a/book/installation-and-setup/git.md +++ b/book/installation-and-setup/git.md @@ -5,23 +5,41 @@ This page is useful for user type 3-5. ``` -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? +You will need to interact with Git to collaborate on a TeachBook, even if you are working by yourself! 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" that sounds suspiciously like something only a computer scientist would want to use? + +```{tip} + +Perhaps you are wondering: _Why a new tool? Why not something I already know like Microsoft Word and Track Changes? Or something like OneDrive or Dropbox?_ + +- Git is 100% free, and online tools like GitHub extend this functionality for free. +- Git is explicitly designed for text-based files, which is how the content of a TeachBook is written. +- You will never have to work with many versions of the same file again (e.g., no more "My_Doc_FINAL_v3_RL_again_final.docx"!). +- Online tools like GitHub provide an easy way to backup your work _and_ to allow others to see it. +- Online tools like GitHub also provide a great way to collaborate, for example: discuss changes to your content, allow others to make suggestions for improvement and fix software issues. +- Online tools like Zenodo allow for long term (decades!) preservation of your work and the ability to update your work with version numbers, dates and DOI's. + +We don't deny that it can take some time to get familiar to the new terminology and workflow associated with Git, and even longer to feel comfortable with it. However, we _promise_ that if you dedicate a little bit of time to learning about this tool it will make your new life creating online interactive textbooks much easier and more enjoyable. + +``` ## 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. - +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. It is especially useful for TeachBooks because it is explicitly designed to handle text-based files, which are essential for writing the contents of a book. ### What is GitHub? -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. +GitHub is a software service that is accessed primarily via a web browser at `github.com`; since 2018 it is owned by Microsoft. It is the most well-known cloud-based Git provider and provides a lot of functionalities for free for open source projects, and even more free services for education. Via a service called GitHub Pages, it also allows you to host websites on `github.io` for free eliminating the need for your own web server (however, you don't have full control over the server setup and operation). -For first users, we advise you to use GitHub. +For new TeachBooks users, we advise you to use GitHub. In addition, we recommend you start by making all of your respositories public (unless they contain sensitive information); this will make it easier for others to collaborate with and help you if you get stuck! ### 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. +GitLab is a cloud-based version control system built around Git; it is a competitor of GitHub, as the two provide many of the same services (but note the names of things can differ, for example, a _Pull Request_ on GitHub is a _Merge Request_ on GitLab). GitLab provides a lot more features to extent Git 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 undesirable (physical) location. This is also why we have our “own” GitLab located at `gitlab.tudelft.nl`, rather than the “normal” GitLab at `gitlab.com`. + +One reason we don't recommend beginning TeachBooks users at TU Delft start with the TU Delft GitLab is that it does not have an automatic website hosting service set up; instead, it must be manually set up on a TU Delft web server (this is straightforward to do, for exmaple, by BSc students from the Computer Science faculty). GitHub Pages provides this service for free and has proven to be very reliable, so start there! ### 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 From c2beaec0f24dfea51bbb6dfb19756bd9b0fe09e8 Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Tue, 4 Mar 2025 10:44:57 +0100 Subject: [PATCH 29/32] Clarified TU Delft internal part --- book/installation-and-setup/git.md | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/book/installation-and-setup/git.md b/book/installation-and-setup/git.md index 281af53..4434739 100644 --- a/book/installation-and-setup/git.md +++ b/book/installation-and-setup/git.md @@ -36,10 +36,8 @@ For new TeachBooks users, we advise you to use GitHub. In addition, we recommend GitLab is a cloud-based version control system built around Git; it is a competitor of GitHub, as the two provide many of the same services (but note the names of things can differ, for example, a _Pull Request_ on GitHub is a _Merge Request_ on GitLab). GitLab provides a lot more features to extent Git 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 undesirable (physical) location. This is also why we have our “own” GitLab located at `gitlab.tudelft.nl`, rather than the “normal” GitLab at `gitlab.com`. - -One reason we don't recommend beginning TeachBooks users at TU Delft start with the TU Delft GitLab is that it does not have an automatic website hosting service set up; instead, it must be manually set up on a TU Delft web server (this is straightforward to do, for exmaple, by BSc students from the Computer Science faculty). GitHub Pages provides this service for free and has proven to be very reliable, so start there! +For TU Delft employees: 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 undesirable (physical) location. This is also why we have our “own” GitLab located at `gitlab.tudelft.nl`, rather than the “normal” GitLab at `gitlab.com`. One reason we don't recommend beginning TeachBooks users at TU Delft start with the TU Delft GitLab is that it does not have an automatic website hosting service set up; instead, it must be manually set up on a TU Delft web server (this is straightforward to do, for example, by BSc students from the Computer Science faculty). GitHub Pages provides this service for free and has proven to be very reliable, so start there! ### 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 +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) From 18b966af83fa2a2b6f13f5868fce1f0d0d79420e Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Tue, 4 Mar 2025 11:00:46 +0100 Subject: [PATCH 30/32] Update versions_URLs.md --- book/installation-and-setup/versions_URLs.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/book/installation-and-setup/versions_URLs.md b/book/installation-and-setup/versions_URLs.md index c4c24fe..836ebaf 100644 --- a/book/installation-and-setup/versions_URLs.md +++ b/book/installation-and-setup/versions_URLs.md @@ -5,14 +5,14 @@ As soon as you have different versions online, you have to make a decision about 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. To share the built book / website of old versions for your book on GitHub you have a few options: -- create a branch for each version. When doing this, [the GitHub workflow](../external/deploy-book-workflow/README.md) will build it on GitHub pages. Here's a few tips: +- Create a branch for each version. When doing this, [the GitHub workflow](../external/deploy-book-workflow/README.md) will build it on GitHub pages. Here's a few tips: - It's advised to use the version as branch name. In case of versions per academic year, you can just name each branch to the current academic year, this leads to the URL with the same name. In that case. - It is recommended to update the primary branch as the `PRIMARY BRANCH` when using the [GitHub workflow](gh-workflow-settings) whenever a new version is considered to be the most primary one. This ensures that readers 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. Alternatively, you can add a banner manually to `_config.yml`, as explained [here](../basic-features/banner.md). - If you're using tags (as will be explained in [later](./versioning_changelog.md)), you can create a branch from a tag locally by running: `git branch `. - If you have many version of the book, at some point you might reach the 1 GB GitHub Pages limit. This is only expected for extremely large books with a lot of non-text-based (binary) content. To prevent going over that limit, store large content not used for building the website (like images) on an external server. This can be another GitHub repository or a (paid) object store. - An example can be found in the book 'Engineering Systems Optimization': it has two versions for readers online, the [2023-version](https://oit.tudelft.nl/CME4501/2023) and the [2024-version](https://oit.tudelft.nl/CME4501/2024), recognizable by the URL. Both versions originate from their respective branches in the [GitHub-repository](https://github.com/TUDelft-books/CME4501) -- add a zip of the built book to the release in GitHub as binary asset. This requires readers to download the zip and open the html files locally, but doesn't require you to host it somewhere. This zip can be easily downloaded as an artifact from [the GitHub action](../external/deploy-book-workflow/README.md). An example can be found [here](https://github.com/TUDelft-books/CME4501/releases/tag/v2024.1.0). Note that this requires you to set up tags and releases, as explained in [](versioning_changelog.md) +- Add a zip of the built book to the release in GitHub as binary asset. This requires readers to download the zip and open the html files locally, but doesn't require you to host it somewhere. This zip can be easily downloaded as an artifact from [the GitHub action](../external/deploy-book-workflow/README.md). An example can be found [here](https://github.com/TUDelft-books/CME4501/releases/tag/v2024.1.0). Note that this requires you to set up tags and releases, as explained in [](versioning_changelog.md) - Use [Read the Docs](../features/pull_request_build.md) to build a website for all your branches, forks and tags as Read the docs doesn't have a 1 GB limit, but has a very different URL structure and the free community version has advertisement. In case you're using tags and releases, refer to the URL of this built from your GitHub release to make sure that GitHub visitors find their way to Read the Docs. If you have your own webserver, you can publish each version on it manually. From 7c8af856036fa6601dbd3a7c76df4737353ede7c Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Tue, 4 Mar 2025 11:07:47 +0100 Subject: [PATCH 31/32] Update template.md --- book/intro/template.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/book/intro/template.md b/book/intro/template.md index 118547d..9e4fb0c 100644 --- a/book/intro/template.md +++ b/book/intro/template.md @@ -26,9 +26,9 @@ Go to the [TeachBooks Template repository on GitHub](https://github.com/TeachBoo ``` ## 3. Let's practice! -Getting used to the syntax of writing in a Jupyter Book can be a bit daunting at the start, not to mention becoming familiar with the various tools and workflows required. To help make the learning curve somewhat easier to travel, a number of exercises have been prepared for you The exercises are designed such that no prior experience with any tools or programming is required, as long as you have read the preceding introductory pages. +Getting used to the syntax of writing in a Jupyter Book can be a bit daunting at the start, not to mention becoming familiar with the various tools and workflows required. To help make the learning curve somewhat easier to travel, a number of exercises covering the TeachBooks workflow have been prepared for you. The exercises are designed such that no prior experience with any tools or programming is required, as long as you have read the preceding introductory pages. -The exercises can be found in your book at `https://.github.io//exercises/exercises` (case sensitive) or at https://teachbooks.io/template/exercises.html. +The exercises on the TeachBooks Workflow can be found in your book at `https://.github.io//exercises/exercises` (case sensitive) or at https://teachbooks.io/template/exercises.html. ```{figure} https://raw.githubusercontent.com/TeachBooks/template_figures/refs/heads/main/exercises.png --- From fabdef87ef55e2e88afed28b721134581b89c9fc Mon Sep 17 00:00:00 2001 From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com> Date: Wed, 5 Mar 2025 13:24:18 +0000 Subject: [PATCH 32/32] Bump book/external/JupyterBook-Patches from `370986c` to `3a1ed37` Bumps [book/external/JupyterBook-Patches](https://github.com/TeachBooks/JupyterBook-Patches) from `370986c` to `3a1ed37`. - [Release notes](https://github.com/TeachBooks/JupyterBook-Patches/releases) - [Commits](https://github.com/TeachBooks/JupyterBook-Patches/compare/370986ca6fd124a0243311647a20c1aeb372bd3a...3a1ed3738693931fb735810cbc7a9a5734e85788) --- updated-dependencies: - dependency-name: book/external/JupyterBook-Patches dependency-type: direct:production ... Signed-off-by: dependabot[bot] --- book/external/JupyterBook-Patches | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) mode change 160000 => 100644 book/external/JupyterBook-Patches diff --git a/book/external/JupyterBook-Patches b/book/external/JupyterBook-Patches deleted file mode 160000 index 370986c..0000000 --- a/book/external/JupyterBook-Patches +++ /dev/null @@ -1 +0,0 @@ -Subproject commit 370986ca6fd124a0243311647a20c1aeb372bd3a diff --git a/book/external/JupyterBook-Patches b/book/external/JupyterBook-Patches new file mode 100644 index 0000000..d5efad9 --- /dev/null +++ b/book/external/JupyterBook-Patches @@ -0,0 +1 @@ +3a1ed3738693931fb735810cbc7a9a5734e85788 \ No newline at end of file