Change the book to build from the latest tag instead of the latest commit on main

[nicholasbishop]

Problem

We've had a few issues where it caused confusion that the book is for the latest git commit instead of for the latest release. Especially with #893, this seems likely to come up again in the future.

Solution

Start building the book for the highest release tag.

There is some subtlety though, which is why I'm making an issue to write up all my thoughts :)

Questions

Do we keep building the book for main as well?

• Pros:
  • Avoids breaking existing links without requiring any redirects.
  • Makes it easy to see what the book will look like in the next release.
  • Helpful for anyone who is using uefi-rs as a git dependency because they need something not yet in the latest release.
• Cons:
  • More work to set up, to avoid confusion we'd want to make sure each build of the book clearly identifies if it's for a release tag or for main, and mdbook doesn't have builtin support for that (it's possible to do with some variable injection though).
  • Potentially still confusing for users who end up on the wrong one, e.g. due to search engine results.

For simplicity's sake, I think it's probably best to drop the build of main.

Do we build the book once for each release tag, or just have a latest-release build?

Similar pros and cons to having a main build; it introduces complexity for not a lot of gain. In the rare event that someone wants to see old docs, they are still there in the git repo and can be built locally with mdbook.

Implementation

Change the github workflow to trigger on tag pushes in addition to the existing trigger of pushes to main. Technically we only need to trigger on tag pushes, but if we also trigger on pushes to main then it's easier to make updates to the workflow's yaml file.

To get the highest release tag:

git tag --list | grep uefi-v | sort -V | tail -1

We currently put the latest git tag under a HEAD directory, and have book/head_redirect.html copied in as the top-level index.html to redirect. Let's drop that complexity and just have the book's index.html at the top level.

As a one-time measure we can manually modify the existing 20-ish html files in gh-pages/HEAD to redirect to the new locations.

We should also modify the rust-osdev.com/uefi-book redirect to go to new location. That redirect can be changed here: https://github.com/rust-osdev/homepage/blob/HEAD/static/uefi-book/index.html

[nicholasbishop]

All done: the workflow now builds from the latest tag instead of main, the https://rust-osdev.com/uefi-book/ redirect has been updated, and the old pages under HEAD have redirects to the new locations.