Update 015.md

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?  
+```