Merge pull request #91 from TeachBooks/deploy_book

Deploy book

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

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://<username>.github.io/<repository-name>/
+   ````
+
+   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://<username>.github.io/<repository-name>/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?  
+```