Add max-min (Rawlsian) fairness explainer #97
Workflow file for this run
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| name: Build Explainers | |
| # Verifies explainers/*.html, assets/explainers-data.js, sitemap.xml, and | |
| # llms-full.txt are byte-exact with their sources (explainers/*.md, | |
| # assets/explainers-data.json), and that assets/og/*.png + | |
| # assets/og-light/*.png (dark and light OG/Twitter social-preview cards) | |
| # exist, are non-empty, and are correctly sized for every current | |
| # explainer - not byte- or pixel-compared against this job's own fresh | |
| # regeneration, since Pillow's bundled FreeType renders text with | |
| # genuinely different pixels across platforms (see | |
| # scripts/check_generated_files_current.py's docstring). Also verifies the | |
| # plain-prose "N explainers" mentions in README.md, CONTRIBUTORS.md, | |
| # METRICS.md, and ROADMAP.md haven't drifted from the real count of | |
| # explainers/*.md (scripts/check_explainer_count.py), and that | |
| # faircode/_results_frozen/*.csv (the MCP get_benchmark_results tool's | |
| # package-internal mirror) is byte-exact with paper/results-frozen/*.csv. | |
| # | |
| # main requires a PR (branch protection), and github-actions[bot] isn't in | |
| # that ruleset's bypass list, so this can no longer auto-commit a fix by | |
| # pushing straight to main. Contributors already run `make build-explainers` | |
| # locally before opening a PR (see CONTRIBUTING.md) - this job just fails | |
| # the check if that step was skipped, instead of silently drifting or | |
| # erroring out trying to push. | |
| on: | |
| push: | |
| branches: [main] | |
| paths: | |
| - "explainers/**.md" | |
| - "assets/explainers-data.json" | |
| - "assets/explainers-ui.js" | |
| - "faircode/_explainers/**" | |
| - "faircode/_results_frozen/**" | |
| - "paper/results-frozen/**" | |
| - "scripts/build_explainers.py" | |
| - "scripts/generate_og_images.py" | |
| - "scripts/freeze_paper_results.py" | |
| - "scripts/check_generated_files_current.py" | |
| - "scripts/check_explainer_count.py" | |
| - "README.md" | |
| - "CONTRIBUTORS.md" | |
| - "METRICS.md" | |
| - "ROADMAP.md" | |
| pull_request: | |
| paths: | |
| - "explainers/**.md" | |
| - "assets/explainers-data.json" | |
| - "assets/explainers-ui.js" | |
| - "faircode/_explainers/**" | |
| - "faircode/_results_frozen/**" | |
| - "paper/results-frozen/**" | |
| - "scripts/build_explainers.py" | |
| - "scripts/generate_og_images.py" | |
| - "scripts/freeze_paper_results.py" | |
| - "scripts/check_generated_files_current.py" | |
| - "scripts/check_explainer_count.py" | |
| - "README.md" | |
| - "CONTRIBUTORS.md" | |
| - "METRICS.md" | |
| - "ROADMAP.md" | |
| permissions: | |
| contents: read | |
| jobs: | |
| check: | |
| runs-on: ubuntu-latest | |
| steps: | |
| - uses: actions/checkout@v7 | |
| with: | |
| fetch-depth: 0 | |
| - uses: actions/setup-python@v7 | |
| with: | |
| python-version: "3.11" | |
| - name: Install Pillow (OG image generation) | |
| run: python -m pip install --upgrade pip "pillow==11.1.0" | |
| - name: Generate explainer pages, data.js, and sitemap | |
| run: python3 scripts/build_explainers.py | |
| - name: Generate OG/Twitter social preview images | |
| run: python3 scripts/generate_og_images.py | |
| - name: Regenerate the MCP results-frozen mirror | |
| # mirror_for_mcp() is a plain byte-for-byte copy of paper/results-frozen/*.csv | |
| # into faircode/_results_frozen/ (stdlib-only, no scikit-learn/pyyaml | |
| # needed) - the same "regenerate fresh, then diff against HEAD" pattern | |
| # the explainer steps above already use. | |
| run: python3 -c "from scripts.freeze_paper_results import mirror_for_mcp; mirror_for_mcp()" | |
| - name: Fail if generated files are out of date | |
| # scripts/check_generated_files_current.py deliberately does NOT | |
| # compare the OG PNGs against this job's own fresh regeneration - | |
| # Pillow's bundled FreeType renders the same text with different | |
| # pixels on this Ubuntu runner than on a contributor's machine (see | |
| # #262 and its follow-up), so byte- or pixel-level comparison always | |
| # false-positives here regardless of how the PNG is saved. It checks | |
| # existence/size/dimensions instead, which is platform-independent. | |
| # Text-based generated files still get an exact git diff. | |
| run: python3 scripts/check_generated_files_current.py | |
| - name: Fail if a "current explainer count" mention has drifted | |
| # CI intentionally only checks, never writes back: a pull_request | |
| # run from a fork gets a read-only GITHUB_TOKEN, so it couldn't push | |
| # a fix to the contributor's branch even if it tried (the same | |
| # reason this workflow stopped auto-committing generated files | |
| # straight to main - see the top-of-file comment). Run with --fix | |
| # locally (`make fix-explainer-count`) to correct drift in one step | |
| # instead of hand-editing four files. | |
| run: python3 scripts/check_explainer_count.py |