Add a GitHub workflow to update the translated manual pages regularly

After taking care of the English manual pages, let's also have a
scheduled workflow that takes care of updating the translated manual
pages.

Just like the scheduled workflow that takes care of the original,
English manual pages, here we also need a flag to toggle complete
rebuilds in case the script, the style sheets, or the layouts changed.

Signed-off-by: Johannes Schindelin <[email protected]>

Author: dscho

.github/workflows/update-translated-manual-pages.yml

@@ -0,0 +1,89 @@
+name: Update translated manual pages
+
+on:
+  workflow_dispatch:
+    inputs:
+      force-rebuild:
+        description: Force re-building all manual pages (e.g. after a script change)
+        type: boolean
+        default: false
+  schedule:
+    # check daily for updates
+    - cron: '41 19 * * *'
+
+jobs:
+  check-for-updates:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          sparse-checkout: |
+            external/docs/sync
+            script
+      - uses: actions/github-script@v7
+        id: get-pending
+        with:
+          script: |
+            const { areTranslatedManualPagesUpToDate } = require('./script/ci-helper.js')
+
+            return await areTranslatedManualPagesUpToDate(github)
+    outputs:
+      up-to-date: ${{ steps.get-pending.outputs.result }}
+  update-translated-manual-pages:
+    needs: [check-for-updates]
+    if: inputs.force-rebuild == true || needs.check-for-updates.outputs.up-to-date == 'false'
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write # to push changes (if any)
+      pages: write # to deploy to GitHub Pages
+      id-token: write # to verify that the deployment source is legit
+    environment:
+      name: github-pages
+      url: ${{ steps.deploy.outputs.url }}
+    steps:
+      - uses: actions/checkout@v4
+      - name: ruby setup
+        uses: ruby/setup-ruby@v1
+        with:
+          bundler-cache: true
+      - name: clone jnavila/git-html-l10n
+        run: git clone --bare https://github.com/jnavila/git-html-l10n '${{ runner.temp }}/git-html-l10n'
+      - name: update translated manual pages
+        run: |
+          if test true = '${{ inputs.force-rebuild }}'
+          then
+            export RERUN=true
+          fi
+          bundle exec ruby script/update-docs.rb '${{ runner.temp }}/git-html-l10n' l10n
+      - name: commit translated manual pages
+        id: manual-pages
+        run: |
+          mkdir -p external/docs/sync &&
+          git -C '${{ runner.temp }}/git-html-l10n' rev-parse HEAD >external/docs/sync/git-html-l10n.sha &&
+          git add external/docs/sync/git-html-l10n.sha &&
+
+          git add -A external/docs &&
+          if test true = '${{ inputs.force-rebuild }}' && git diff-index --cached --quiet HEAD --
+          then
+            echo '::notice::Rebuild of the translated manual pages was requested but resulted in no changes' >&2
+            exit 0
+          fi &&
+          git \
+            -c user.name=${{ github.actor }} \
+            -c user.email=${{ github.actor }}@noreply.github.com \
+            commit -m "Update translated manual pages" \
+              -m 'Updated via the `update-translated-manual-pages.yml` GitHub workflow.' &&
+          echo "result=modified" >>$GITHUB_OUTPUT
+      - name: verify that there are no uncommitted changes
+        run: |
+          git update-index --refresh &&
+          if test -n "$(git diff HEAD)$(git ls-files --exclude-standard --other)"
+          then
+            echo '::error::there are uncommitted changes!' >&2
+            git status >&2
+            exit 1
+          fi
+      - name: deploy to GitHub Pages
+        if: steps.manual-pages.outputs.result != ''
+        id: deploy
+        uses: ./.github/actions/deploy-to-github-pages

script/ci-helper.js

@@ -54,14 +54,40 @@ const getPendingBookUpdates = async (octokit, forceRebuild) => {
   return result
 }
 
+const areTranslatedManualPagesUpToDate = async (octokit) => {
+  try {
+    const localSha = await getFileContents(`external/docs/sync/git-html-l10n.sha`)
+
+    const [owner, repo] = 'jnavila/git-html-l10n'.split('/')
+    const { data: { default_branch: remoteDefaultBranch } } =
+    await octokit.rest.repos.get({
+      owner,
+      repo
+    })
+    const { data: { object: { sha: remoteSha } } } =
+      await octokit.rest.git.getRef({
+        owner,
+        repo,
+        ref: `heads/${remoteDefaultBranch}`
+      })
+
+    if (localSha === remoteSha) return true
+  } catch (e) {
+    // It's okay for the `.sha` file not to exist yet.`
+    if (e.code !== 'ENOENT') throw e
+  }
+  return false
+}
+
 // for testing locally, needs `npm install @octokit/rest` to work
 if (require.main === module) {
   (async () => {
     const { Octokit } = require('@octokit/rest')
-    console.log(await getPendingBookUpdates(new Octokit()))
+    console.log(await areTranslatedManualPagesUpToDate(new Octokit()))
   })().catch(console.log)
 }
 
 module.exports = {
-  getPendingBookUpdates
+  getPendingBookUpdates,
+  areTranslatedManualPagesUpToDate
 }