tally-rewind
Tally rewind
Past performance fixes show where a project's hot paths are and how fast that code has already been. This workflow turns each fix into a Tally benchmark, finds the best numbers the code reached between the fix and today, and then improves today's code past them.
It delivers two things to the project, each as its own commits:
- The benchmarks, committed to the project with Tally set up and running in CI, so the fixes stay guarded after this work ends.
- Improvements of today's code, each one counting only when it makes a real workload measurably faster in wall-clock time.
Rules for every step
- Every number you compare must come from the same machine, PHP build, and Tally version, because Tally's counts depend on all three.
scripts/measure.shin this skill's directory keeps the Tally version and configuration the same at every commit. - Tally runs on Linux, x86_64 or aarch64, with PHP 8.2 or later and the POSIX extension. On another OS, do all the work in a Linux container with the newest PHP the project supports.
- Work on the line where new development lands, which is not always the default branch. Replay points and best numbers come only from that line's first-parent history. A fix made on another branch counts where it arrives on this line.
- Keep notes in
$TALLY_REWIND_DIR/notes.md, by default under${TMPDIR:-/tmp}/tally-rewind/<project directory name>/: the period, the workload and its profile, the fixes and their commits, the bench files, the replay points, the best numbers, and the decisions you made.measure.shappends every measurement tomeasurements.tsvin the same directory. Update the notes after each phase; after a context reset, read both files and continue from there.
How to measure
bash scripts/measure.sh <commit>... -- <bench file or directory>... copies the bench files as they are in the working copy, with the data files of a directory, into a git worktree at each commit. It installs the project's dependencies there and runs Tally, in the working copy's version and with its tally.php, and prints one line per case with instructions, cycles, and memory in bytes. The commits and files are fixed when it starts, so you can keep editing while a batch runs. Options such as --filter=<text> go to tally run. Exit code 1 means a commit could not be measured, and the output says why. Set TALLY_REWIND_PREPARE to a command that makes old commits installable or bootable, such as cp .env.example .env. Run measure.sh --help for the rest.