Improve file diff display in GitHub PR comments by ericholscher · Pull Request #12918 · readthedocs/readthedocs.org

ericholscher · 2026-04-07T05:33:39Z

Summary

Redesigns the file diff section of the build overview comment posted on pull requests. Added files are now sorted first, the display adapts based on the number of changes, and large lists are capped to keep comments scannable.

Sort added files first (most relevant for review)
Two distinct layouts: simple (< 5 files) and complex (>= 5 files)
Code-styled symbols (+, ±, -) matching the addons convention
Code-formatted paths for visual distinction
Cap each group at 10 files with "and N more..." overflow
Auto-expand <details> for small diffs
Hide zero-count categories from summary line

Output examples

Simple layout (< 5 files total — auto-expanded)

Clean lines with code-styled status symbols and paths. No bullets, no headings:

3 files changed

+ conf/portland/2026/news/one-month-out/index.html
± blog/index.html
- legacy/old-page.html

Simple layout — only added files

2 files changed

+ guides/new-tutorial.html
+ guides/new-tutorial/setup.html

Complex layout (>= 5 files — collapsed)

Grouped by status with bold headings, bullet lists, and a full breakdown in the summary:

8 files changed · + 1 added · ± 6 modified · - 1 deleted

+ Added

conf/portland/2026/news/one-month-out/index.html

± Modified

- Deleted

legacy/old-page.html

Complex layout with truncation (large diff)

Groups are capped at 10 files each:

27 files changed · + 2 added · ± 25 modified

+ Added

± Modified

Test plan

Verify simple layout renders for < 5 files (auto-expanded, no headings, no bullets)
Verify complex layout renders for >= 5 files (collapsed, grouped headings)
Verify truncation works when a group exceeds 10 files
Verify added files sort before modified/deleted in both layouts
Run existing TestPostBuildOverview tests

https://claude.ai/code/session_01537nbMDhPg49b2qpqEjftP

… diffs Show added files at the top of the files changed table with a separator row between added and non-added files. Auto-expand the details view when there are added files and fewer than 5 total files, since those are the most relevant to review. https://claude.ai/code/session_01537nbMDhPg49b2qpqEjftP

Simplify the summary line: drop verbose "Show files changed (N in total):" prefix, hide zero-count categories, reorder counts to match table order (added first), and use middot separators for a cleaner look. https://claude.ai/code/session_01537nbMDhPg49b2qpqEjftP

Switch from markdown table to HTML <table> inside the <details> element, removing the visual gap between the summary and table content. Separate added, modified, and deleted files into distinct groups with empty row separators between each. https://claude.ai/code/session_01537nbMDhPg49b2qpqEjftP

Replace the repeated status column on every file row with section headings (➕ Added, 📝 Modified, ➖ Deleted) that group files by change type, similar to the optgroup pattern used in the addons file diff selector. Files are indented under their group heading for visual hierarchy. https://claude.ai/code/session_01537nbMDhPg49b2qpqEjftP

Replace the HTML table with a more natural display pattern: - Single added file shown inline (no list wrapper needed) - Multiple files use <ul> lists (not tabular data) - When < 5 added files: auto-expand and show them prominently, collapse modified/deleted into nested <details> sections - Group headings on the nested details summaries replace the redundant per-file status labels - Remove unused non_added property - Change should_auto_expand to key off added count, not total https://claude.ai/code/session_01537nbMDhPg49b2qpqEjftP

Remove nested <details> complexity in favor of a simple flat layout: - < 5 total files → auto-expand (open), regardless of change type - Single file in a group → inline with emoji prefix (➕ path) - Multiple files in a group → bold heading + <ul> list - Groups always ordered: added, modified, deleted - No nested collapsing, no conditional nesting logic https://claude.ai/code/session_01537nbMDhPg49b2qpqEjftP

Switch from HTML elements to native markdown inside <details>: - Code-formatted paths with backticks for visual distinction - Consistent section headings (➕ Added, 📝 Modified, ➖ Deleted) - Native markdown bullet lists instead of <ul>/<li>/<table> - Simpler template with no conditional nesting or single-file special cases — every group gets a heading + list https://claude.ai/code/session_01537nbMDhPg49b2qpqEjftP

Large diffs (e.g. 50 modified files) now show the first 10 files per group with "and N more..." at the end, keeping the comment scannable. Uses Django's slice filter — no Python changes needed. https://claude.ai/code/session_01537nbMDhPg49b2qpqEjftP

Simple layout (< 5 files, auto-expanded): no headings, no breakdown in summary — just emoji + code-formatted path per file. Clean and compact. Complex layout (>= 5 files, collapsed): full summary breakdown, grouped sections with bold headings, bullet lists capped at 10 per group with "and N more..." overflow. https://claude.ai/code/session_01537nbMDhPg49b2qpqEjftP

Bare lines with blank lines between them render as separate <p> tags in GitHub. Switch to a markdown list (- ➕ path) so items stay tight in a single <ul>. https://claude.ai/code/session_01537nbMDhPg49b2qpqEjftP

Drop the bullet markers — they're redundant alongside the emoji. Use HTML <br> line breaks with <code> paths instead, giving a clean display without bullets or <p> wrappers. https://claude.ai/code/session_01537nbMDhPg49b2qpqEjftP

Replace emoji (➕, 📝, ➖) with code-formatted text symbols for consistent visual weight. Uses <code> tags in HTML contexts and backtick spans in markdown contexts. The ± symbol for modified matches the convention already used in the addons file diff selector. https://claude.ai/code/session_01537nbMDhPg49b2qpqEjftP

humitos

Looks good. I'd like to use icons instead of code text since they render better and are easier to scan quickly.

humitos · 2026-04-08T08:07:03Z

readthedocs/templates/core/build-overview.md

+<details open>
+<summary>{{ diff.files|length }} files changed</summary>
+<br>
+{% for file in diff.added %}<code>+</code> <a href="{{ file.url }}"><code>{{ file.path }}</code></a><br>


Is there a reason why you removed the icons we had? I personally can't distinguish the -, ± and +. They are rendered pretty small and look very similar.

📝 was a weird one that didn't match the others, so I used a matching icon, but the colors are interesting 🤔

The current icons match the Addons approach:

The current icons match the Addons approach

That's a good point, actually.

However, when looking at that in addons I don't really look at the icons since they are split in sections which is a lot more relevant.

My main problem with the -, + and ± is when there is no section separator, like in the compact form of the comment (less than 5 files). It's probably irrelevant, tho.

This one works fine:

This one is confusing to me; they all look the same:

Ideally, I would like to have the symbols you've used - and + with colors, like GitHub:

but not sure how easy is to have that.

Yea the AI tried color bubbles but they were pretty visually loud. 🔴🟢

I think if we were investing in this, we would do some images or custom art... I don't think it would really be hard to do it. We're just trying to keep things pretty constrained with the current approach.

I'm happy to move forward here. We can always come back and change the icons. That shouldn't block the PR.

readthedocs/templates/core/build-overview.md

Replace code-styled text symbols with colored circle emoji that are all the same shape/size for consistent visual weight and easy scanning. Green=added, yellow=modified, red=deleted — matching common diff color conventions. Also adds <br> after summary in complex layout per review feedback. https://claude.ai/code/session_01537nbMDhPg49b2qpqEjftP

read-the-docs-community · 2026-04-08T08:16:23Z

Documentation build overview

📚 dev | 🛠️ Build #32177485 | 📁 Comparing e1dedf9 against latest (4b70d1c)

🔍 Preview build

Show files changed (1 files in total): 📝 1 modified | ➕ 0 added | ➖ 0 deleted

File	Status
tests.html	📝 modified

Go back to ➕ and ➖ for added/deleted, use ± for modified to match the addons file diff selector convention. Simpler than colored circles and consistent with the existing UI. https://claude.ai/code/session_01537nbMDhPg49b2qpqEjftP

https://claude.ai/code/session_01537nbMDhPg49b2qpqEjftP

claude added 9 commits April 7, 2026 00:34

ericholscher requested a review from a team as a code owner April 7, 2026 05:33

auto-assign bot assigned ericholscher Apr 7, 2026

ericholscher requested a review from agjohnson April 7, 2026 05:33

claude added 3 commits April 7, 2026 05:38

Use markdown list for simple layout to avoid <p> per file

e5deb9e

Bare lines with blank lines between them render as separate <p> tags in GitHub. Switch to a markdown list (- ➕ path) so items stay tight in a single <ul>. https://claude.ai/code/session_01537nbMDhPg49b2qpqEjftP

ericholscher requested a review from humitos April 8, 2026 03:28

humitos approved these changes Apr 8, 2026

View reviewed changes

claude added 3 commits April 9, 2026 00:39

Use ➕/±/➖ icons matching addons convention

77fdadc

Go back to ➕ and ➖ for added/deleted, use ± for modified to match the addons file diff selector convention. Simpler than colored circles and consistent with the existing UI. https://claude.ai/code/session_01537nbMDhPg49b2qpqEjftP

Revert to original ➕/📝/➖ icons

4a840d7

https://claude.ai/code/session_01537nbMDhPg49b2qpqEjftP

Use code-styled +/±/- symbols for file status indicators

e1dedf9

https://claude.ai/code/session_01537nbMDhPg49b2qpqEjftP

ericholscher added this to 📍Roadmap Apr 9, 2026

github-project-automation bot moved this to Planned in 📍Roadmap Apr 9, 2026

ericholscher merged commit e8a2840 into main Apr 9, 2026
10 checks passed

ericholscher deleted the claude/github-comment-file-sorting-8JffF branch April 9, 2026 09:20

github-project-automation bot moved this from Planned to Done in 📍Roadmap Apr 9, 2026

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Improve file diff display in GitHub PR comments#12918

Improve file diff display in GitHub PR comments#12918
ericholscher merged 16 commits intomainfrom
claude/github-comment-file-sorting-8JffF

ericholscher commented Apr 7, 2026 •

edited

Loading

Uh oh!

humitos left a comment

Uh oh!

humitos Apr 8, 2026

Uh oh!

ericholscher Apr 8, 2026 •

edited

Loading

Uh oh!

humitos Apr 9, 2026

Uh oh!

humitos Apr 9, 2026

Uh oh!

ericholscher Apr 9, 2026 •

edited

Loading

Uh oh!

humitos Apr 9, 2026

Uh oh!

Uh oh!

read-the-docs-community bot commented Apr 8, 2026 •

edited

Loading

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Uh oh!

Conversation

ericholscher commented Apr 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Output examples

Simple layout (< 5 files total — auto-expanded)

Simple layout — only added files

Complex layout (>= 5 files — collapsed)

Complex layout with truncation (large diff)

Test plan

Uh oh!

humitos left a comment

Choose a reason for hiding this comment

Uh oh!

humitos Apr 8, 2026

Choose a reason for hiding this comment

Uh oh!

ericholscher Apr 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

humitos Apr 9, 2026

Choose a reason for hiding this comment

Uh oh!

humitos Apr 9, 2026

Choose a reason for hiding this comment

Uh oh!

ericholscher Apr 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

humitos Apr 9, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

read-the-docs-community bot commented Apr 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Documentation build overview

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

ericholscher commented Apr 7, 2026 •

edited

Loading

ericholscher Apr 8, 2026 •

edited

Loading

ericholscher Apr 9, 2026 •

edited

Loading

read-the-docs-community bot commented Apr 8, 2026 •

edited

Loading