[v0lumehi]

Update: rebased on main c9d555a, after #401 landed with the union rule for gallery.tsv only. .gitattributes now has #401's line plus this PR's two lines for docs/reference/*.md and docs/agents/symptoms.md. test_docs.py keeps #401's Gallery tests and adds this PR's UnionMerge guard; test_docs passes.

Part of #313 ("Conflicts out of the way"). Separate from #398 (the game count in AGENTS.md); the two don't depend on each other.

Problem

About four in five new reference entries go at the end of their file: 437 of 551 new ### entries in the last 400 commits to docs/reference (a rough count over the diff hunks). docs/agents/symptoms.md is generated from those entries line for line, in the same order. So two PRs that each add an entry to the same file (rendering.md with 117 new entries and shaders.md with 109 lead) conflict twice: in the reference file, and in the index at the end of the same group. symptoms.md was touched by 82 commits.

Change

• .gitattributes: merge=union for docs/reference/*.md and docs/agents/symptoms.md. Git's built-in union driver keeps both sides' new lines. It needs no setup and applies to merges, rebases and cherry-picks, so also when you take a PR in by rebasing or squashing it locally.
• test_docs.py, the guard. When both sides change the same line, union keeps both versions without a conflict marker. The likely case is two PRs that each add a game to the same "Found on" line. The test fails on an entry with a Symptom, Cause, Fix or Found on bullet more than once, or a ### heading twice in one file. Seven entries already have a bullet twice today. They are listed as the baseline, and a count there may only go down; you may want to merge those by hand at some point.

Risk

Prose outside the four bullets (a paragraph two sides reword at the same time) isn't guarded: union would keep both wordings. Entries are mostly bullets, and docs_symptoms.py --check still catches an index that comes out of order. If you'd rather not have union on the reference files, the attribute for symptoms.md alone is safe (it's generated and fully checked), but then the reference files keep conflicting.

Checked

In a throwaway clone:

1. Two branches each append an entry to rendering.md and regenerate the index. With the attribute, rebasing one onto the other gives no conflict, both entries are there, and docs_symptoms.py --check says the index is current. Without the attribute, the same rebase conflicts in both rendering.md and symptoms.md.
2. Two branches each add a different game to the same "Found on" line of audio.md. The union rebase keeps two "Found on" lines without a conflict, and the new test reports audio.md: "SDK 8's longer AudioRendererParameter": Found on 2 times.

• python3 -m unittest dm/tools/tests/test_docs.py: OK. Lint ratchet: 0 new.
• Not verified: whether GitHub's own "This branch has conflicts" check applies the attribute. Local merges and rebases do.

[seedds]

Thanks for this. The implementation does what it says, but I'm closing it: measured against the open PRs, the benefit is small, and it trades a visible conflict for a silent one.

I merged all 132 open PRs that touch docs/reference or the symptom index against main (c7da003), with and without the rule:

• 43 conflict in those files today. 38 of them still conflict in other files with the rule on, so only 5 are held back by these files alone.
• Of those 5, 4 merge cleanly. The fifth, South Park: The Fractured But Whole (01008F2005154000): profile for 1.05, bare zlib Snowdrop shader caches #843, gets a whole entry's bullets doubled.
• The attribute on symptoms.md alone fully unblocks none of them: all 5 need the reference rule too.

The problems I found:

• Silent doubling is common. 17 of the 53 conflict hunks in reference files are places where both sides edited the same text, and union keeps both versions with no marker. This is the concern README's games gallery is written from docs/images/gallery.tsv #401 raised when it kept the rule to gallery.tsv.
• The guard misses cases. In SHIN MEGAMI TENSEI V (010063B012DC6000, 1.0.0): game profile, version 8 Unreal paks, UE 4.23's FMalloc layout and engine region, 60 fps and an iOS Screen setting #173 both sides rewrite the Engine-wide bullet in memory.md, and the guard stays silent because it knows four bullet kinds. Check (303 bullets) and Note (125) aren't covered either. The PR does disclose that prose outside those bullets isn't guarded.
• The guard also fires wrongly. Applied to today's main, which has no union rule on these files, it fails on 3 entries over its baseline. Entries do legitimately gain a second Fix bullet, so a baseline that may only go down can't hold.
• When it does fire, the fix is harder. 9 PRs would trip it, and by then the conflict markers are gone, so someone has to untangle the text by hand.
• Blank lines are lost. In 21 of the 43 PRs, a ### heading ends up directly under the previous entry's last line, and no test catches it.
• The index can still go stale. In 11 of the 43 PRs the merged index no longer matched the generator, though each PR's own index was current. test_docs catches this, so it isn't silent, but those merges need the script rerun anyway.

These counts are one snapshot, and I have no timing for how long hand resolution takes. For comparison, a conflict on two new entries is one hunk to resolve by keeping both, and rerunning docs_symptoms.py fixes the index.

#472 is stacked on this PR, so it would need rebasing onto main. Whether CI should regenerate the index is its own question, which this doesn't decide.