In pull requests

In pull requests

The system diff as a comment

Copy .github/workflows/system-diff.yml into your repository, and change its install step to install system-diff (pip install system-diff). On every pull request it:

1. runs system-diff diff --base origin/<base branch> --head HEAD (the checkout is the pull request merged into its base, so this is exactly what merging would do);
2. writes the headline and the plan to the run's summary, and as a comment on the pull request (updated, not repeated, on every push);
3. uploads diff.svg and the rest as the run's system-diff artifact.

A pull request from a fork gets a read-only token, so it has the summary and the artifact but no comment.

The README map stays current

This repository's ci.yml fails when the map is out of date:

system-diff map --dir . --out docs/diagrams --check
system-diff readme --json docs/diagrams/system.json --check

Fix it with the same two commands without --check, and commit.

Other CI systems

Nothing is GitHub-specific apart from the comment: any CI that has git and Python can run system-diff diff and post headline.txt and plan.txt. Where the page cannot show SVG, system-diff png makes PNGs.