# Reporting as code: explainer video

The source of the 1:51 video "Reporting as code" on www.bino.bi. Everything on screen
comes from a real run on the Kestrel project of the homepage (`homepage/showcase`, also
served at www.bino.bi/showcase/files).

## The run

`session.sh` copies the Kestrel project into a fresh git repo and runs every command the
video shows. The output goes to `session/`:

| File | What it is |
| --- | --- |
| `tree.txt`, `files/` | The project files, and the four files the video shows |
| `build-1.txt`, `build-again.txt` | The first build and a second build of the same files |
| `sha-1.txt`, `sha-2.txt` | SHA-256 of the PDF after each build, with `SOURCE_DATE_EPOCH` set |
| `change.diff`, `build-2.txt`, `page-2-plan.png` | The chart compared against plan instead of last year: the diff, the build, the new page |
| `log.txt` | The two commit messages |
| `build-error.txt`, `typo-line.txt`, `build-error-pdfs.txt` | One wrong letter in the SQL (`revenue_pln`): the error, exit code 2, no PDF |

```bash
./session.sh            # needs bino, git and pdftoppm; bino 0.104.0 was used
```

`session/lint.txt` is the output of `bino lint` on the same files.

## The pull requests and CI

The CI part runs in the private repo `bino-bi/kestrel-report`: the same project in `report/`,
and `.github/workflows/report.yml`, which installs bino, runs `bino lint --fail-on-warnings`
and `bino build`, and attaches the PDF to the run.

- Pull request 1, "Compare regions against plan": the three-line change, CI green, a review
  comment on the changed line, merged.
- Pull request 2, "Use the new plan column": `revenue_pln` in the SQL, the Build step fails
  with exit code 2, the PDF upload is skipped. It stays open on purpose.

`ci.sh` saves the workflow, both pull requests, their check steps, the artifact, the review
comment and the failed log to `ci/` (needs `gh` with access to the repo).

Two things in the workflow are workarounds: `bino-bi/cli-action@v1.0.0` calls flags that
bino 0.104.0 no longer has, so the workflow installs bino itself, and `bino lint` reads every
YAML file below its work dir, including the workflow, so the project lives in `report/`.

The video shows `build-again.txt`, the second build of the same files. The very first build
in a fresh folder takes longer (1.7 to 2.5 s against about 1.1 s).

## The video

`video/` is made from the house template of the bino explainer videos. `prepare.sh` reads
`session/` and `ci/` into `assets/data.json` (`make_data.py`) and copies the page images.

| File | What it does |
| --- | --- |
| `scene.html` | The 13 scenes. Every frame depends only on the time. |
| `assets/vo.mp3` | The voiceover, ElevenLabs voice "Martin, Calm Clear Narrator", model `eleven_v4`. bino is spelled "Beeno" in the script so it is said the German way. |
| `assets/music.mp3` | The music bed, ElevenLabs Music `eleven_music_v2_5`, checked for vocals with a transcription (empty). |
| `timing.json` | Scene cuts and sentence times from the pauses in `vo.mp3` (`timing.py`). |
| `cues.json`, `reporting-as-code.en.vtt` | English captions (`make_vtt.py`). |
| `build.sh` | Renders the frames in headless Chrome and encodes MP4, WebM and the poster to `out/`. |

```bash
./session.sh
./ci.sh
cd video && ./build.sh
```

## On the website

`publish.sh` copies the text output of `session/` and `ci/`, this README and the two scripts to
`homepage/public/reporting-as-code/files`, and the two chart images to the homepage assets. The
pull request JSON is cut down to the fields the page shows, because the full output has the
commit author's email. The `video/` folder, `session/files/` and the PNGs are not published.

You need node, python3, ffmpeg with libx264, libvpx-vp9 and libopus, ImageMagick, and the
Chrome headless shell that `bino setup` installs.