Skip to content

docs(j5): PR template asks for descriptive screenshot alt text - #826

Merged
Jacksondr5 merged 2 commits into
j5/mainfrom
j5code/descriptive-pr-image-alt-text
Oct 31, 2026
Merged

Jacksondr5 merged 2 commits into
j5/mainfrom
j5code/descriptive-pr-image-alt-text

Conversation

@Jacksondr5

Copy link
Copy Markdown
Owner

Problem

Before/after screenshots that agents write into PR tables by hand use bare ![Before] and ![After] alt text (#820, #814, #808, #807, #765). When a viewer shows the images on their own, as J5's does, that alt text is all that tells you which state an image shows. The row's first column says the state, but the image tag never gets it.

What changed

The comment in the template's "UI changes" section now points to scripts/j5/pr-evidence.ts, which uploads the images and prints the table. Its output already gets the alt text right (![<caption>, before]), as in #824, #823 and #797. The comment also says that a table written by hand should name the state and side in each image's alt text, with a good example next to a bad one.

The same rule is now in the developer's machine-wide agent instructions, outside this repo, so it applies in every repo.

Checklist

  • One concern: the description has no "also"
  • Tests cover the changed behavior: n/a, this changes template text only
  • UI changes: n/a, no UI change
  • Live testing: n/a, nothing to run
  • Upstream-owned files: the template is J5-owned (FORK.md, J5-owned files list)
  • Upstream product: not touched
  • Surfaces: only the PR template applies
  • Docs: docs/j5/process/pull-requests.md and the j5-live-test skill stay accurate; the skill already sends agents to the script

Claude Opus 5.5 in Claude Code (J5 Code).

🤖 Generated with Claude Code

Hand-written before/after tables used bare "Before" and "After" alt text,
which is all a viewer that shows images on their own (like J5's) displays.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@vercel

vercel Bot commented Oct 31, 2026 •

Copy link
Copy Markdown

The latest updates on your projects. Learn more about Vercel for GitHub.

Project Deployment Actions Updated
j5-code Ready Ready Preview Oct 31, 2026 9:32pm UTC

Request Review

@github-actions github-actions Bot added the vouch:trusted PR author is trusted by repo permissions or the VOUCHED list. label Oct 31, 2026
@github-actions github-actions Bot added the size:XS 0-9 effective changed lines (test files excluded in mixed PRs). label Oct 31, 2026
@coderabbitai

coderabbitai Bot commented Oct 31, 2026 •

Copy link
Copy Markdown

Review in Change Stack →

No actionable comments were generated in the recent review.

Recent review info
Run configuration
Commits

Reviewing files that changed from the base of the PR and between a0cd096 and dd00d2e.

Files selected for processing: 1
  • .github/pull_request_template.md
Files skipped from review as they are similar to previous changes: 1
  • .github/pull_request_template.md

Included review availability: This review used your included allowance. 0 included reviews remain after this review. Your included PR review attempts over the past 7 days set your current allowance at 2 reviews per hour.

Walkthrough

The pull request template now identifies the screenshot evidence upload script and specifies that manually written screenshot alt text must name the image’s UI state and whether it shows the before or after state.

Changes: Screenshot evidence

Layer / File(s) Summary
Screenshot evidence instructions
.github/pull_request_template.md
The template points to scripts/j5/pr-evidence.ts for screenshot uploads. It also requires manually written image alt text to identify the UI state and whether the image is before or after.

Estimated code review effort: 1 (Trivial) | ~3 minutes

Possibly related issues

  • Jacksondr5/j5code#698 — The template requires manually written screenshot alt text to identify the state and before-or-after side, and points to the evidence script.
Merge Risk: Minimal · up to dd00d

The screenshot guidance is consistent with the referenced script. No issue identified here needs to be resolved before merging.

Pre-merge checks: Passed 4
Check name Status Explanation
Title check Passed The title clearly describes the main change: updating the PR template to require descriptive screenshot alt text.
Description check Passed The description clearly explains the problem, the template change, scope, and checklist status. It omits the optional UI changes, Live testing, and Upstream impact sections, but the checklist explains…
Linked Issues check Passed Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check Passed Check skipped because no linked issues were found for this pull request.
Full details: Description check

Explanation

The description clearly explains the problem, the template change, scope, and checklist status. It omits the optional UI changes, Live testing, and Upstream impact sections, but the checklist explains why those sections do not apply. The description is sufficiently complete for this template-only change.

Finishing Touches
Generate unit tests (beta)
  • Commit to this branch
  • Create a new PR
  • Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Additional comments: 1
.github/pull_request_template.md-13-13: 1

13-13: Minor · Maintainability & Code Quality · Quick win

Unverified finding
Verification ran but could not confirm this finding. It is shown for review, not as a verified issue.

Correct the grammar in the guidance.

The phrase as the script's do is ungrammatical. Use as the script does:.

Proposed fix
-     yourself, each image's alt text names its state and side, as the script's do:
+     yourself, each image's alt text names its state and side, as the script does:

Review info
Run configuration
Commits

Reviewing files that changed from the base of the PR and between 5e45a79 and a0cd096.

Files selected for processing: 1
  • .github/pull_request_template.md

Included review availability: This review used your included allowance. 2 included reviews remain after this review. Your included PR review attempts over the past 7 days set your current allowance at 3 reviews per hour.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@Jacksondr5
Jacksondr5 merged commit 4657a56 into j5/main Oct 31, 2026
32 checks passed
@Jacksondr5
Jacksondr5 deleted the j5code/descriptive-pr-image-alt-text branch October 31, 2026 21:47

This branch was successfully deployed

1 active deployment
Preview — dd00d2e4 Deployed Oct 31, 2026 by vercel[bot]
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

size:XS 0-9 effective changed lines (test files excluded in mixed PRs). vouch:trusted PR author is trusted by repo permissions or the VOUCHED list.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant