From 750102c78fc1f3ee1957204a308d325e43c2ab2b Mon Sep 17 00:00:00 2001 From: Katia Gatt Date: Mon, 22 Sep 2025 19:02:26 +0200 Subject: [PATCH 1/5] part 1 --- book/extension_exercises/015.md | 38 +++++++++++++++++++++++++++++++++ 1 file changed, 38 insertions(+) create mode 100644 book/extension_exercises/015.md diff --git a/book/extension_exercises/015.md b/book/extension_exercises/015.md new file mode 100644 index 0000000..12eb9e7 --- /dev/null +++ b/book/extension_exercises/015.md @@ -0,0 +1,38 @@ +# Exercise: Deploy Book Workflow + +The **Deploy Book Workflow (DBW)** automatically builds and publishes your TeachBook whenever changes are pushed to your repository. If you started your book from the TeachBooks Template, this workflow is already included. + +With this workflow, readers can see your latest book version online without manual intervention. This exercise will guide you through triggering the workflow, configuring branch-specific builds, and customising deployment options. + +::::::{topic} Exercise objective +Can you trigger, configure, and monitor the Deploy Book Workflow to publish your TeachBook automatically? +:::::: + + + +## Trigger the workflow + +1. Make a small edit in any page of your book (for example `book/intro.md`). +2. Commit the change and push it to the `main` branch. +3. Open the **Actions** tab of your repository. You should see a workflow called *Deploy Book* running. +4. When it finishes, visit the URL: + + ```` + https://.github.io// + ```` + + to see the updated book. + + +5. The workflow can also be triggered in a separate branch. Create a new branch, e.g., `draft-chapter`. +6. Push a change to this branch. +7. The DBW automatically builds a version of your book for that branch, available at: + + ```` + https://.github.io//draft-chapter/ + ```` + +```{tip} +Branch-specific builds are useful for previewing work in progress without affecting the main book. +``` + From 882279dbe5bc6366edf6c58ae3a14c539adbb49a Mon Sep 17 00:00:00 2001 From: Katia Gatt Date: Tue, 23 Sep 2025 14:55:24 +0200 Subject: [PATCH 2/5] Update 015.md --- book/extension_exercises/015.md | 90 +++++++++++++++++++++++++++++++++ 1 file changed, 90 insertions(+) diff --git a/book/extension_exercises/015.md b/book/extension_exercises/015.md index 12eb9e7..8307c81 100644 --- a/book/extension_exercises/015.md +++ b/book/extension_exercises/015.md @@ -36,3 +36,93 @@ Can you trigger, configure, and monitor the Deploy Book Workflow to publish your Branch-specific builds are useful for previewing work in progress without affecting the main book. ``` + +## Customise the workflow + +8. The behaviour of the Deploy Book Workflow can be adapted by defining **repository variables** in your GitHub repository, as explained [here](https://docs.github.com/en/actions/learn-github-actions/variables#creating-configuration-variables-for-a-repository) or using the [VS Code Extension GitHub Actions](https://marketplace.visualstudio.com/items?itemName=GitHub.vscode-github-actions). + + +```{admonition} Key repository variables +| Variable | Default | Purpose | +|-----------------------|-------------|-------------------------------------------------------------------------| +| `PRIMARY_BRANCH` | `main` | Which branch appears at the root URL. | +| `BEHAVIOR_PRIMARY` | `redirect` | How the root URL behaves: `redirect`, `copy`, or `move`. | +| `BRANCH_ALIASES` | *(blank)* | Space-separated list of aliases (custom URLs) for branches. | +| `BRANCHES_TO_DEPLOY` | `*` | Which branches are deployed (all by default). | +| `BRANCHES_TO_PREPROCESS` | *(blank)* | Branches preprocessed with TeachBooks (e.g. remove draft-only content). | +| `BRANCHES_ARCHIVED` | *(blank)* | Adds a banner to old versions marking them as archived. | +``` + +```{note} +You can also edit `.github/workflows/call-deploy-book.yml` to change which branches or folders trigger deployment. +``` + + +## Common usage scenarios + +### Scenario 1 — Academic years + +```{admonition} Context +Each year you release a new version of your book for students, but older cohorts still need access. +``` + +9. Create a branch for each year (e.g. `2024`, `2025`). +10. In repository variables, set: + + * `PRIMARY_BRANCH = 2025` + * `BEHAVIOR_PRIMARY = redirect` (so the root redirects to the current year). +11. Push a change to the `2025` branch. +12. Verify the URLs: + + * `.../my_book/2025/` (this year) + * `.../my_book/2024/` (last year) + * `.../my_book/` (redirects to current year). + +```{tip} +If you want the root URL to always show a complete book instead of the in-progress year, set +`PRIMARY_BRANCH = 2024` and `BEHAVIOR_PRIMARY = copy`, and mark `2025` as archived. +``` + + +### Scenario 2 — Draft and release workflow + +```{admonition} Context +You want a public release branch, an internal draft branch, and multiple author branches for parallel work. +``` + +13. Create branches: `release`, `draft`, `author_1`, `author_2`, etc. +14. Set your GitHub default branch to `draft`. +15. In repository variables, set: + + * `PRIMARY_BRANCH = release` + * `BEHAVIOR_PRIMARY = copy`. +16. Push changes to each branch and check the URLs: + + * `.../my_book/` (release version) + * `.../my_book/draft/` (draft version) + * `.../my_book/author_1/`, etc. + +```{note} +Making `draft` the default branch ensures pull requests are tested in draft first, avoiding accidental premature releases. +``` + + +17. When you are ready, commit your changes to the repository by clicking on the green `Commit changes` button. + +18. Add a commit message. + +19. To see your changes, go to {octicon}`play` `Actions` - The most recent workflow run `overview.md / the commit message of the commit you just made` - Wait for it to finish - In the summary, click on the link of your book shown in the table `Branches deployed` and under `Primary book at root` (getting bored of waiting? There'll be exercising on doing this locally which prevents you from waiting). + +20. Do you see your change? If you don't see it click `CTRL`+`F5`/`Control`+`F5`to refresh the page. + + + +```{admonition} Check your understanding +:class: note + + +Before moving on, make sure you understand: +- How can you trigger the Deploy Book Workflow? +- What is the purpose of `PRIMARY_BRANCH` and `BEHAVIOR_PRIMARY`? +- How would you set up the workflow so that both a release and a draft version of your book are available online? +``` \ No newline at end of file From 17a8feeca46faeeae0dfd09e73afcd770ba2f67f Mon Sep 17 00:00:00 2001 From: Katia Gatt Date: Tue, 23 Sep 2025 14:55:50 +0200 Subject: [PATCH 3/5] Update _toc.yml --- book/_toc.yml | 1 + 1 file changed, 1 insertion(+) diff --git a/book/_toc.yml b/book/_toc.yml index e128798..fb79f96 100644 --- a/book/_toc.yml +++ b/book/_toc.yml @@ -32,6 +32,7 @@ parts: sections: - file: exercises/007.md - file: extension_exercises/014.md + - file: extension_exercises/015.md - caption: Miscellaneous chapters: - file: references.md From af326c815e78e0c146755434643816898406a6a8 Mon Sep 17 00:00:00 2001 From: Katia Gatt Date: Tue, 23 Sep 2025 14:58:45 +0200 Subject: [PATCH 4/5] Update 015.md --- book/extension_exercises/015.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/book/extension_exercises/015.md b/book/extension_exercises/015.md index 8307c81..60e6278 100644 --- a/book/extension_exercises/015.md +++ b/book/extension_exercises/015.md @@ -1,4 +1,4 @@ -# Exercise: Deploy Book Workflow +# Deploy Book Workflow The **Deploy Book Workflow (DBW)** automatically builds and publishes your TeachBook whenever changes are pushed to your repository. If you started your book from the TeachBooks Template, this workflow is already included. @@ -47,10 +47,10 @@ Branch-specific builds are useful for previewing work in progress without affect |-----------------------|-------------|-------------------------------------------------------------------------| | `PRIMARY_BRANCH` | `main` | Which branch appears at the root URL. | | `BEHAVIOR_PRIMARY` | `redirect` | How the root URL behaves: `redirect`, `copy`, or `move`. | -| `BRANCH_ALIASES` | *(blank)* | Space-separated list of aliases (custom URLs) for branches. | +| `BRANCH_ALIASES` | | Space-separated list of aliases (custom URLs) for branches. | | `BRANCHES_TO_DEPLOY` | `*` | Which branches are deployed (all by default). | -| `BRANCHES_TO_PREPROCESS` | *(blank)* | Branches preprocessed with TeachBooks (e.g. remove draft-only content). | -| `BRANCHES_ARCHIVED` | *(blank)* | Adds a banner to old versions marking them as archived. | +| `BRANCHES_TO_PREPROCESS` | | Branches preprocessed with TeachBooks (e.g. remove draft-only content). | +| `BRANCHES_ARCHIVED` | | Adds a banner to old versions marking them as archived. | ``` ```{note} From c9414cb316de2eb7df0c994ce8fa9b04b352e203 Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Tue, 7 Oct 2025 19:33:07 +0200 Subject: [PATCH 5/5] Remove VS Code Extension reference from workflow section --- book/extension_exercises/015.md | 18 ++++++++++-------- 1 file changed, 10 insertions(+), 8 deletions(-) diff --git a/book/extension_exercises/015.md b/book/extension_exercises/015.md index 60e6278..72ae3d0 100644 --- a/book/extension_exercises/015.md +++ b/book/extension_exercises/015.md @@ -39,7 +39,7 @@ Branch-specific builds are useful for previewing work in progress without affect ## Customise the workflow -8. The behaviour of the Deploy Book Workflow can be adapted by defining **repository variables** in your GitHub repository, as explained [here](https://docs.github.com/en/actions/learn-github-actions/variables#creating-configuration-variables-for-a-repository) or using the [VS Code Extension GitHub Actions](https://marketplace.visualstudio.com/items?itemName=GitHub.vscode-github-actions). +8. The behaviour of the Deploy Book Workflow can be adapted by defining **repository variables** in your GitHub repository, as explained [here](https://docs.github.com/en/actions/learn-github-actions/variables#creating-configuration-variables-for-a-repository). ```{admonition} Key repository variables @@ -69,18 +69,20 @@ Each year you release a new version of your book for students, but older cohorts 9. Create a branch for each year (e.g. `2024`, `2025`). 10. In repository variables, set: - * `PRIMARY_BRANCH = 2025` - * `BEHAVIOR_PRIMARY = redirect` (so the root redirects to the current year). + - `PRIMARY_BRANCH = 2025` + - `BEHAVIOR_PRIMARY = redirect` (so the root redirects to the current year). 11. Push a change to the `2025` branch. 12. Verify the URLs: - * `.../my_book/2025/` (this year) - * `.../my_book/2024/` (last year) - * `.../my_book/` (redirects to current year). + - `.../my_book/2025/` (this year) + - `.../my_book/2024/` (last year) + - `.../my_book/` (redirects to current year). ```{tip} If you want the root URL to always show a complete book instead of the in-progress year, set -`PRIMARY_BRANCH = 2024` and `BEHAVIOR_PRIMARY = copy`, and mark `2025` as archived. +`PRIMARY_BRANCH = 2024` and `BEHAVIOR_PRIMARY = copy`, and mark `2025` as archived. However, we recommend +using redirects as students might bookmark pages. If the URL changes the next academic year their bookmark +becomes invalid or points to another page. ``` @@ -125,4 +127,4 @@ Before moving on, make sure you understand: - How can you trigger the Deploy Book Workflow? - What is the purpose of `PRIMARY_BRANCH` and `BEHAVIOR_PRIMARY`? - How would you set up the workflow so that both a release and a draft version of your book are available online? -``` \ No newline at end of file +```