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

Update after review Dennis

Browse source
This commit is contained in:
Tom van Woudenberg 2025-02-25 08:24:49 +01:00
parent deebd66b1d
commit 33d160caaf
5 changed files with 21 additions and 22 deletions
Download patch file Download diff file Expand all files Collapse all files

1
book/_toc.yml
View file

@ -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

18
book/installation-and-setup/versioning.md
View file

@ -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.

5
book/installation-and-setup/versioning_archived.md
View file

@ -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)

6
book/installation-and-setup/versioning_changelog.md
View file

@ -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.

13
book/installation-and-setup/versions_URLs.md
View file

@ -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 <new_branch name> <tag/version>`.
- 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 `<link to root URL>` to view the most recent version of this book, or adapt the year in `<link to root URL>/<year>` to the year when you took the course.
> This is the `<version_number>`-version of this book. Go to `<link to root URL>` to view the most recent version of this book, or adapt the year in `<link to root URL>/<year>` to the year when you took the course.