diff --git a/AGENTS.md b/AGENTS.md index f555284..05a4984 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -97,6 +97,18 @@ luajit tests/run.lua workbench -t "preview" - Offline mocks cannot prove rendering, taint safety or combat behaviour. For visual/lifecycle changes, report what still needs in-game verification: Workbench entry switching/release, repeated toggles, sample/live sources, real combat, unit disappearance/replacement, full-health shields, and Edit Mode as relevant. - Do not hard-code a historical passing-test count as a requirement; report the current run's result. +## Visual proof for pull requests + +Every change that can affect what a frame, preview or Workbench panel looks like ships with UI proof rendered by `wowproof`: in the pull request and, when working in Beluga, in the chat and on the task. + +1. Pick the scenarios in `tests/proof/units.lua` and `tests/proof/workbench.lua` that show the change. When none does (a new setting, state or layout), add one: a name plus a `build` that configures through `Config:SetUnitValue` and feeds sample values. Prefer one scenario per state the change touches (like `player-idle` beside `player`) over one busy frame. +2. Render and look at them with `bash scripts/proof.sh ` before claiming the change works. Dashed placeholders mean missing art, an atlas or a portrait model, not a bug; mention them if they hide the change. +3. When opening or updating the pull request, run `bash scripts/proof-publish.sh --out .beluga/scratch/proof `. It renders the scenarios, commits the PNGs to the orphan `ui-proof` branch under `/` (it never touches the working tree or the current branch) and prints a `### UI proof` Markdown section with images pinned to that commit. Paste that section into the PR body (`gh pr create --body-file` or `gh pr edit --body-file`). Re-run it after visual changes in review; old links keep showing the earlier images. `--dry-run` skips the push. +4. In Beluga, show the same PNGs in the answer as Markdown images with their absolute paths under `.beluga/scratch/proof/`, and attach each one to the worktree's task with `task_attach_proof` (kind `image`). +5. Proof shows mocked rendering only. Still list what needs in-game verification (see Verification above): combat, secret values, taint, Edit Mode and live unit changes. + +Changes with no visual effect (tracking data, tests, tooling) say so in the PR body instead of attaching proof. + ## Local installation - Default client AddOns directory: `/mnt/data02/Games/Faugus/battlenet/drive_c/Program Files (x86)/World of Warcraft/_forever_/Interface/AddOns/`. `scripts/install.sh` supports `WOW_DIR` overrides; validate the actual target before deploying. diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..43c994c --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1 @@ +@AGENTS.md diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md index 9da05cb..7385c10 100644 --- a/DEVELOPMENT.md +++ b/DEVELOPMENT.md @@ -249,6 +249,11 @@ render. `tests/proof/setup.lua` is the only coupling to the renderer: it hands also call `Helpers.Snapshot(name, region)`, which renders only with `UF_PROOF=1`. CI uploads the images as the `ui-proof` artifact. +For a pull request body, `bash scripts/proof-publish.sh ` renders the +matching scenarios, commits their PNGs to the orphan `ui-proof` branch under +`/` and prints Markdown images pinned to that commit (`--dry-run` skips +the push, `--out DIR` keeps the files). + The images show real anchoring, sizes, colours, bar fill, text, clipping, texture coordinates and paint order. Blizzard textures and icons (`Interface\...`) are downloaded on demand from the public diff --git a/scripts/proof-publish.sh b/scripts/proof-publish.sh new file mode 100755 index 0000000..7393bf8 --- /dev/null +++ b/scripts/proof-publish.sh @@ -0,0 +1,97 @@ +#!/usr/bin/env bash +set -euo pipefail + +usage() { + cat <<'EOF' +Usage: scripts/proof-publish.sh [--dry-run] [--out DIR] SCENARIO_FILTER... + +Renders the UI proof scenarios whose names contain a filter, commits their +PNGs to the orphan `ui-proof` branch under / and prints +Markdown image links pinned to that commit, for a pull request body. + + --dry-run create the commit locally but do not push it + --out DIR keep the rendered files in DIR (default: a temporary folder) +EOF +} + +repo_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)" +cd "$repo_dir" + +proof_branch=ui-proof +push=1 +out_dir= +filters=() +while (($#)); do + case "$1" in + --dry-run) push=0 ;; + --out) out_dir="$2"; shift ;; + -h|--help) usage; exit 0 ;; + *) filters+=("$1") ;; + esac + shift +done +if ((${#filters[@]} == 0)); then + usage >&2 + exit 2 +fi + +branch="$(git symbolic-ref --short HEAD)" +head_sha="$(git rev-parse --short HEAD)" +slug="$(gh repo view --json nameWithOwner -q .nameWithOwner)" + +if [[ -z "$out_dir" ]]; then + out_dir="$(mktemp -d)" + trap 'rm -rf "$out_dir"' EXIT +fi +mkdir -p "$out_dir" +rm -f "$out_dir"/*.png + +UF_PROOF_DIR="$out_dir" bash scripts/proof.sh "${filters[@]}" >&2 + +shopt -s nullglob +pngs=("$out_dir"/*.png) +if ((${#pngs[@]} == 0)); then + echo "No PNGs rendered for: ${filters[*]}" >&2 + exit 1 +fi + +parent= +if git fetch --quiet origin "$proof_branch" 2>/dev/null; then + parent="$(git rev-parse FETCH_HEAD)" +fi + +index_file="$(mktemp)" +rm -f "$index_file" +export GIT_INDEX_FILE="$index_file" +if [[ -n "$parent" ]]; then + git read-tree "$parent" +else + git read-tree --empty +fi +git rm -r --cached --quiet --ignore-unmatch -- "$branch" +for png in "${pngs[@]}"; do + blob="$(git hash-object -w "$png")" + git update-index --add --cacheinfo "100644,$blob,$branch/$(basename "$png")" +done +tree="$(git write-tree)" +rm -f "$index_file" +unset GIT_INDEX_FILE + +commit="$(git commit-tree "$tree" ${parent:+-p "$parent"} -m "Proof for $branch at $head_sha")" +if ((push)); then + git push --quiet origin "$commit:refs/heads/$proof_branch" +else + echo "Dry run: proof commit $commit not pushed." >&2 +fi + +echo "### UI proof" +echo +echo "Rendered by \`scripts/proof-publish.sh\` from \`$head_sha\`." +echo +for png in "${pngs[@]}"; do + name="$(basename "$png" .png)" + echo "**$name**" + echo + echo "![$name](https://raw.githubusercontent.com/$slug/$commit/$branch/$name.png)" + echo +done