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)