Cherry Pick 2 55

---
name: cherry-pick-2-55
description: Instructions for how to cherry-pick changes from main to the releases/2.55 branch
---

You MUST be on the releases/2.55 branch for this. Per CLAUDE.md, use the
`../ZQuestClassic-2.55` worktree rather than switching the main checkout, and run
all git/build/test commands from there (the worktree gets its own build folder).

Here is how to help cherry-pick changes from main to the releases/2.55 branch.

We first need a list of candidate commits, saved to a file (for example
/Users/connorclark/Downloads/2.55.15.txt). The user will need to create this list
manually to start, and prune what isn't relevant before cherry-picking begins.

It should look like this: the commit sha followed by the oneline message:

```
624a236d28c6 misc(zq)!: improve infotext for string editor 'Layer'
a139c83ab090 fix(zc): non-triggering weapons still trigger secret flags
5dffacbc8471 fix(zc): pushblock lens hints not drawing over block sprite layer
b8a56512ae6f refactor(zc): greatly speed up dithercircfill
a6d3ae970117 fix(zc): Heart Container / Magic Container cheats using outdated values
```

You can use `manage_commits.py path/to/file.txt` to normalize this list of commits (dropping ones already cherry-picked), and print ready-to-run `git cherry-pick -x` commands for the ones that apply without conflict. The list is ordered most recent first, so start at the end of the list.

Some guidelines:

- Cherry-pick starting from the oldest candidates.
- use `git cherry-pick -x`, and resolve the conflict for me. Do not EVER change the commit message, with one exception: "Regressed in" lines (see below).
- If the commit message has a "Regressed in <version> (<hash>)" line referencing a 3.0 version/commit, rewrite it to reference the 2.55 equivalent (via `git commit --amend`, keeping everything else — including the "(cherry picked from ...)" trailer — intact):
  1. Find the 2.55 commit that introduced the regression. Usually it's the 2.55 cherry-pick of the cited main commit: search with `git log releases/2.55 --grep="cherry picked from commit <full-hash>"`, or by subject (`git log releases/2.55 --grep="<subject>"`) since older picks lack the trailer.
  2. Verify that 2.55 commit actually introduces the bug there (inspect its diff) — don't blindly map.
  3. Find the first 2.55 release containing it: `git tag --contains <sha> | grep -E '^2\.55' | sort -V | head -1`. Ignore nightly tags — this branch's convention only cites alpha/numbered releases.
  4. Cite as `Regressed in 2.55.<x> (<10-char sha>).`
  5. If the regressing commit was never cherry-picked to 2.55, investigate how the bug got into 2.55; if the fix is still relevant but no 2.55 commit can be cited, drop the "Regressed in" line rather than citing a 3.0 commit.
- Write a file .tmp/CHERRY_PICK_PROGRESS.md and record notes for every commit you assess. Be sure to append to the file, not overwrite it.
- Validate each cherry-pick'd commit via `cmake --build build --config Release -t all` and `python tests/run_replay_tests.py --filter playground`
- If a commit modifies anything in `tests`, you should probably take only the .zs changes and drop playground.qst or .zplay changes. Will need to regenerate those for 2.55.
- I'm pretty certain most candidate commits are relevant to cherry-pick, but I may be wrong about some. If the merge conflict suggests many things are missing, skip it and make a note about why
- Never update the replay version in replay.cpp - when a cherry-pick'd commit uses a new replay check, you must add a new function in replay_compat.cpp and use that instead.
- The main branch may have other changes that make cherry-picks not apply cleanly. If possible, make as minimal a change as possible to adapt the commit. If too much is missing, just skip it and move on.
- The qst file format reading code is split across many files on main, but for the 2.55 branch it still is in one file qst.cpp (for example, main has src/core/qst_rules.cpp but in this branch src/qst.cpp has the rules section, and all other sections)
- When a cherry-pick'd commit increases V_COMPATRULE, instead of changing it in 2.55 (we cannot) check the ZC version w/ tempheader.compareVer. See the bottom of readrules in qst.cpp