From dedfdd7d973f452ea8b2d7bccdf807675b6dfdf2 Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Mon, 24 Feb 2025 21:29:44 +0100 Subject: [PATCH] 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