From 7f764475c305a59e446f3d87fea8dc771fe344dd Mon Sep 17 00:00:00 2001 From: Mohammed Anas Nathani Date: Thu, 23 Jul 2026 01:51:30 +0530 Subject: [PATCH] docs: document publishing badge.json for shields.io Add a Verification badge section to usage.md with real badge shapes, orphan-branch and Pages publish routes, always() rationale, red vs missing badge behavior, README embed snippet, and a caching caveat. Link it from the 0.7.0 whats-new note. Closes #196 --- docs/usage.md | 128 +++++++++++++++++++++++++++++++++++++++- docs/whats-new-0.7.0.md | 2 +- 2 files changed, 128 insertions(+), 2 deletions(-) diff --git a/docs/usage.md b/docs/usage.md index 7a6c956..739cc49 100644 --- a/docs/usage.md +++ b/docs/usage.md @@ -65,4 +65,130 @@ readme2demo report runs/tool-20260702-... --json && echo "verified" || echo "gat Artifacts land in `runs//`: `tutorial.md`, `step_by_step.md`, `troubleshooting.md`, `commands.sh`, `demo.tape`, `demo.mp4`, `demo.gif`, -`howto.jsonld`, and `manifest.json`. +`howto.jsonld`, `manifest.json`, and `badge.json`. + +## Verification badge + +Every completed run mints a shields.io-compatible `badge.json` in the run +directory (written at the start of the tutorial stage, so an unverified run +still gets a **loud red** badge rather than a missing file). From the GitHub +Action, the path is `${{ steps..outputs.run-dir }}/badge.json`. + +### What the file looks like + +Verified (green) — shape from `render_badge` on a verified manifest: + +```json +{ + "schemaVersion": 1, + "label": "readme2demo", + "message": "verified 2026-07-05", + "color": "green", + "commit": "f677e21" +} +``` + +Unverified (red) — same shape when `manifest.verified` is false: + +```json +{ + "schemaVersion": 1, + "label": "readme2demo", + "message": "unverified", + "color": "red", + "commit": "f677e21" +} +``` + +The extra `commit` key is human provenance; shields.io ignores unknown keys. + +### Route A (recommended): orphan branch endpoint + +Publish `badge.json` to a dedicated `readme2demo-badge` branch so the stable +URL is: + +`https://raw.githubusercontent.com/OWNER/REPO/readme2demo-badge/badge.json` + +Copy-paste workflow (consumer repo — not part of this project's own CI): + +```yaml +name: README check + badge + +on: + push: + branches: [main] # default branch only — not pull_request + +jobs: + verify: + runs-on: ubuntu-latest + # Scoped write so the publish job can update the badge branch. + permissions: + contents: write + steps: + - uses: actions/checkout@v4 + + - name: Run readme2demo + id: r2d + # Use the published Action; wire secrets/API keys per its docs. + uses: alphacrack/readme2demo@v0 + with: + # repo / guide / engine inputs per action.yml + repo: ${{ github.repository }} + + # MUST be always(): the Action exits 1 when verified != true + # (action.yml gate). Without always(), a red/unverified run never + # publishes — and a stale green badge is worse than a red one. + - name: Publish badge.json + if: always() + env: + RUN_DIR: ${{ steps.r2d.outputs.run-dir }} + run: | + set -euo pipefail + # No run-dir / no badge.json → leave the previous badge untouched. + # (Pipeline died before tutorial; "no badge" ≠ "red badge".) + if [ -z "${RUN_DIR}" ] || [ ! -f "${RUN_DIR}/badge.json" ]; then + echo "No badge.json to publish; keeping previous endpoint." + exit 0 + fi + git fetch origin readme2demo-badge:readme2demo-badge 2>/dev/null || true + git checkout --orphan readme2demo-badge 2>/dev/null || git checkout readme2demo-badge + git rm -rf . >/dev/null 2>&1 || true + cp "${RUN_DIR}/badge.json" ./badge.json + git add badge.json + git -c user.name='github-actions[bot]' -c user.email='41898282+github-actions[bot]@users.noreply.github.com' \ + commit -m "chore: update readme2demo badge" || echo "No badge change" + git push -f origin HEAD:readme2demo-badge +``` + +Embed in your README (replace `OWNER` / `REPO`): + +```markdown +[![README verified](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/OWNER/REPO/readme2demo-badge/badge.json)](https://github.com/OWNER/REPO/actions/workflows/readme-check.yml) +``` + +### Route B: GitHub Pages — one deployment source only + +You *can* host `badge.json` via Pages (`actions/upload-pages-artifact` + +`actions/deploy-pages`), following the pattern in this repo's +`.github/workflows/docs.yml`. **A repository has a single Pages deployment +source.** A second Pages-deploying workflow replaces the whole site — if you +already publish docs via Pages, fold `badge.json` into that existing build as +an extra file; do not deploy a separate Pages job just for the badge. + +### Caching caveat + +Both shields.io and `raw.githubusercontent.com` cache responses, so a fresh +run can take a while to show up in the rendered badge. Expect lag; do not +assume an instant update. + +### Red badge vs no badge + +| Situation | `badge.json` | What to publish | +|---|---|---| +| Completed, verified | green | Publish | +| Completed, unverified | red | Publish (`if: always()`) | +| Failed before tutorial | missing | **Do not** invent a file; leave previous badge | + +For Action wiring, secrets, and cost notes, see the Action guide (tracked in +#149); this section only covers publishing the file the pipeline already +writes. diff --git a/docs/whats-new-0.7.0.md b/docs/whats-new-0.7.0.md index 4f9aa62..aa3ea66 100644 --- a/docs/whats-new-0.7.0.md +++ b/docs/whats-new-0.7.0.md @@ -59,7 +59,7 @@ written before the tutorial LLM pass, so nothing can suppress it. cat examples/readme2demo/badge.json ``` -Hosting it as a live badge endpoint is tracked in #63. +Hosting it as a live badge endpoint is documented in [Verification badge](usage.md#verification-badge) (slice of #63). ## Step 5 — the GitHub Action (the 0.7.0 flagship)