diff --git a/.github/workflows/build.sh b/.github/workflows/build.sh index 0911422c..f9fecb77 100755 --- a/.github/workflows/build.sh +++ b/.github/workflows/build.sh @@ -9,6 +9,8 @@ set -Eeuo pipefail # # The src/ and third_party/ directories are left in a dirty state so # you can run `mdbook test` and other commands afterwards. +# +# See also TRANSLATIONS.md. book_lang=${1:?"Usage: $0 "} dest_dir=${2:?"Usage: $0 "} diff --git a/.github/workflows/publish.yml b/.github/workflows/publish.yml index 53d547cf..26df445a 100644 --- a/.github/workflows/publish.yml +++ b/.github/workflows/publish.yml @@ -1,5 +1,7 @@ name: Publish +# See also TRANSLATIONS.md. + on: push: branches: diff --git a/TRANSLATIONS.md b/TRANSLATIONS.md index 20b23d56..33a8062d 100644 --- a/TRANSLATIONS.md +++ b/TRANSLATIONS.md @@ -215,6 +215,68 @@ the hard work, even if it is incomplete. [CODEOWNERS]: https://github.com/google/comprehensive-rust/blob/main/.github/CODEOWNERS +## Publication Workflow + +> This section is for the developers of Comprehensive Rust, but it might give +> you valuable background information on how the translations are published. + +When a change is made to the `main` branch, the [`publish.yml`] GitHub CI +workflow starts. + +The `publish` job in this workflow will: + +- Install dependencies as described in [`CONTRIBUTING`](CONTRIBUTING.md). + +- Build every translation of the course, including the original English, using + [`build.sh`]. The English HTML ends up in `book/html/`, the HTML for the `xx` + language ends up in `book/xx/html/`. + +- Publish the entire `book/html/` directory to + https://google.github.io/comprehensive-rust/. + +[`build.sh`]: https://github.com/google/comprehensive-rust/blob/main/.github/workflows/build.sh + +### `build.sh` + +The `build.sh` script is used both when testing code from a PR (with +[`build.yml`]) and when publishing the finished book (with [`publish.yml`]). + +[`build.yml`]: https://github.com/google/comprehensive-rust/blob/main/.github/workflows/build.yml +[`publish.yml`]: https://github.com/google/comprehensive-rust/blob/main/.github/workflows/publish.yml + +The job of the script is to call `mdbook build`, but with a few extra steps: + +- It will enable the PDF output using `mdbook-pandoc`. This is disabled by + default to make it easier for people to run `mdbook build` without having to + configure LaTeX. + +#### Restoring Translations + +When building a translation (languages other than English), `build.sh` will +restore all Markdown files to how they looked at the time recorded in the +POT-Creation-Date header. + +This means that: + +- A translation does not degrade when the English text is changed. +- A translation will not received the latest fixes to the English text. + +The script restores the Markdown with a simple + +```sh +$ git restore --source $LAST_COMMIT src/ third_party/ +``` + +command, where `$LAST_COMMIT` is the commit at the time of the POT-Creation-Date +header. + +A consequence of this is that we use the latest theme, CSS, JavaScript, etc for +each translation. + +After `build.sh` was run, the working copy is left in this dirty state. Beware +of this if you want to build the English version next, as you will have to clean +up manually. + ## Status reports Two translation status reports are automatically generated: