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 diff --git a/book/extension_exercises/015.md b/book/extension_exercises/015.md new file mode 100644 index 0000000..72ae3d0 --- /dev/null +++ b/book/extension_exercises/015.md @@ -0,0 +1,130 @@ +# 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. +``` + + +## 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). + + +```{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` | | Space-separated list of aliases (custom URLs) for branches. | +| `BRANCHES_TO_DEPLOY` | `*` | Which branches are deployed (all by default). | +| `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} +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. 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. +``` + + +### 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? +```