Update multilingual programming language monitoring

Author: johnsamuelwrites

.github/workflows/docs-ci.yml

@@ -25,7 +25,7 @@ jobs:
       - name: Install Python dependencies
         run: |
           python -m pip install --upgrade pip
-          python -m pip install pytest PyYAML multilingualprogramming
+          python -m pip install pytest PyYAML -r requirements-build.txt
 
       - name: Validate multilingual docs metadata
         run: python scripts/validate_multilingual_docs.py --strict-freshness

.github/workflows/docs-deploy-pages.yml

@@ -40,7 +40,7 @@ jobs:
       - name: Install Python dependencies
         run: |
           python -m pip install --upgrade pip
-          python -m pip install PyYAML multilingualprogramming
+          python -m pip install PyYAML -r requirements-build.txt
 
       - name: Validate multilingual docs metadata
         run: python scripts/validate_multilingual_docs.py --strict-freshness

.github/workflows/monitor-multilingual.yml

@@ -0,0 +1,125 @@
+name: Docs multilingual compatibility monitor
+
+on:
+  schedule:
+    - cron: "40 5 * * *"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  issues: write
+
+jobs:
+  compat:
+    name: Docs compatibility (${{ matrix.channel.name }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        channel:
+          - name: pinned
+            install_command: python -m pip install -r requirements-build.txt
+          - name: latest
+            install_command: python -m pip install multilingualprogramming
+          - name: upstream-main
+            install_command: python -m pip install "multilingualprogramming @ git+https://github.com/johnsamuelwrites/multilingual.git@main"
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install Python dependencies
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install pytest PyYAML
+          ${{ matrix.channel.install_command }}
+
+      - name: Capture dependency metadata
+        env:
+          CHANNEL_NAME: ${{ matrix.channel.name }}
+        run: |
+          python - <<'PY'
+          import json
+          import os
+          import pathlib
+          import subprocess
+
+          data = {
+              "channel": os.environ["CHANNEL_NAME"],
+              "pip_freeze": subprocess.check_output(["python", "-m", "pip", "freeze"], text=True).splitlines(),
+          }
+          try:
+              from multilingualprogramming.version import __version__
+              data["multilingual_version"] = __version__
+          except Exception as exc:
+              data["multilingual_version_error"] = str(exc)
+
+          out = pathlib.Path("build")
+          out.mkdir(exist_ok=True)
+          path = out / f"multilingual-metadata-{os.environ['CHANNEL_NAME']}.json"
+          path.write_text(json.dumps(data, indent=2), encoding="utf-8")
+          print(path.read_text(encoding="utf-8"))
+          PY
+
+      - name: Validate multilingual docs metadata
+        run: python scripts/validate_multilingual_docs.py --strict-freshness
+
+      - name: Run docs tests
+        run: python -m pytest _tests -q
+
+      - name: Set up Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: "3.3"
+          bundler-cache: true
+
+      - name: Build Jekyll site
+        run: bundle exec jekyll build --baseurl "/docs"
+
+      - name: Check internal links
+        run: python scripts/check_internal_links.py --site-dir _site --base-path /docs
+
+      - name: Check Pages artifact
+        run: python scripts/check_pages_artifact.py --site-dir _site --base-path /docs
+
+      - name: Upload metadata artifact
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: docs-multilingual-${{ matrix.channel.name }}
+          path: build/multilingual-metadata-${{ matrix.channel.name }}.json
+
+  notifier:
+    name: Open issue on scheduled failure
+    if: failure() && github.event_name == 'schedule'
+    runs-on: ubuntu-latest
+    needs: compat
+
+    steps:
+      - name: Create or update compatibility issue
+        uses: actions/github-script@v7
+        with:
+          script: |
+            const title = 'Compatibility alert: docs monitor failed against multilingual';
+            const { owner, repo } = context.repo;
+            const existing = await github.rest.issues.listForRepo({ owner, repo, state: 'open', per_page: 100 });
+            const match = existing.data.find((issue) => issue.title === title);
+            const body = [
+              'The scheduled multilingual compatibility monitor for the docs site failed.',
+              '',
+              `Workflow: ${context.serverUrl}/${owner}/${repo}/actions/runs/${context.runId}`,
+              `Date: ${new Date().toISOString()}`,
+              '',
+              'Check the `latest` and `upstream-main` jobs first to see whether the regression is upstream or in the docs assumptions.',
+            ].join('\n');
+
+            if (match) {
+              await github.rest.issues.createComment({ owner, repo, issue_number: match.number, body });
+              return;
+            }
+
+            await github.rest.issues.create({ owner, repo, title, body, labels: ['bug'] });

README.md

@@ -39,7 +39,7 @@ Prerequisites:
 Install the Python package used by the docs tests:
 
 ```bash
-pip install multilingualprogramming
+pip install -r requirements-build.txt
 ```
 
 Install dependencies:
@@ -77,6 +77,8 @@ bundle exec jekyll build
 3. Run `bundle exec jekyll serve` and verify pages render correctly.
 4. Submit a pull request.
 
+The stable docs-test baseline for `multilingualprogramming` is pinned in `requirements-build.txt`, and a scheduled compatibility workflow also checks the latest published package and upstream `main`.
+
 For multilingual EN/FR documentation operations (metadata model, localized routing, snippets, CI checks, and Pages-safe deploy), see [contributing/multilingual-docs.md](contributing/multilingual-docs.md).
 
 For language/runtime contribution workflow, see `contributing/` and the [main repository](https://github.com/johnsamuelwrites/multilingual).

requirements-build.txt

@@ -0,0 +1 @@
+multilingualprogramming==0.6.0