Document the diff-block convention in CLAUDE.md - #203
Merged
Conversation
Closes the open decisions on TW-1804. Oliver's `diff` support (#145) merged on 19 Aug and is live, but only on the CodePush page, and nothing tells an author — human or agent — when to reach for it. The docs currently show "edit a file you already have" three different ways (bare `...`, `// ...existing`, commented placeholders), and diff blocks are a fourth. Two changes: 1. Adds `diff` to the Prism language list in CLAUDE.md, which #145 made stale — as written, CLAUDE.md tells authors `diff` isn't available when it is (verified: docusaurus.config.ts line 1521 includes it). 2. Adds a short convention: diff block for editing a file the reader already has, full snippet for a new or whole file, one convention per page. The copy-paste question from TW-1804 is resolved by the rule rather than by code: copying a diff block does include the `+`/`-` characters, but a snippet meant to be pasted whole shouldn't be a diff block in the first place. No retrofit in this PR. A survey of the 12 pages still using the older notations is on TW-1804; the proposal there is to apply the convention going forward and clean up opportunistically, rather than open 12 PRs for no reader-visible gain. Green-light or discard — either is a decision, and the ticket has been open since July waiting for one.
ilanazholobovsky
requested review from
aorcsik,
matenadasdi and
zoltan-baba
as code owners
August 27, 2026 09:47
zoltan-baba
approved these changes
Aug 27, 2026
7 tasks
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Closes the open decisions on TW-1804.
Oliver's
diffsupport (#145) merged on 19 Aug and is live, but only on the CodePush page, and nothing tells an author — human or agent — when to reach for it. The docs currently show "edit a file you already have" three different ways (bare...,// ...existing, commented placeholders), and diff blocks are a fourth.Two changes:
diffto the Prism language list in CLAUDE.md, which Add diff language to Prism syntax highlighting #145 made stale — as written, CLAUDE.md tells authorsdiffisn't available when it is (verified: docusaurus.config.ts line 1521 includes it).The copy-paste question from TW-1804 is resolved by the rule rather than by code: copying a diff block does include the
+/-characters, but a snippet meant to be pasted whole shouldn't be a diff block in the first place.No retrofit in this PR. A survey of the 12 pages still using the older notations is on TW-1804; the proposal there is to apply the convention going forward and clean up opportunistically, rather than open 12 PRs for no reader-visible gain.
Green-light or discard — either is a decision, and the ticket has been open since July waiting for one.