Skip to content

docs: refresh the README banner - #522

Merged
LivXue merged 1 commit into
mainfrom
docs/refresh_readme_hero_banner
Sep 20, 2026
Merged

LivXue merged 1 commit into
mainfrom
docs/refresh_readme_hero_banner

Conversation

@LivXue

@LivXue LivXue commented Sep 19, 2026

Copy link
Copy Markdown
Member

Summary

Both READMEs point at a re-rendered hero banner on line 3. The composition and the
1536x656 geometry are unchanged; the tagline rule now sets its ampersands in italic so
they match the italic words on either side.

The image is not committed. scripts/check_large_files.py rejects an added .png by
extension at any size, so the asset is hosted as a GitHub attachment and the README
references it by absolute URL. It was uploaded as a new comment on the existing banner
issue rather than by editing the old one, whose URL is still live in the published
README and in every fork and cache of it.

The banner UUID is shared between the English and the Chinese README, so one replaced
image is two edits carrying the same new URL. The workflow figure further down is the
language-specific one, and it is untouched.

Checked and deliberately not changed: line 3 uses plain Markdown image syntax rather
than the anchor-wrapped <img width="100%"> shape the benchmark figures use. That is
the shape the banner already had, and converting it is a separate decision from
swapping the asset.

Type

  • Fix
  • Feature
  • Docs
  • CI / tooling
  • Refactor
  • Other

Verification

  • git grep for the previous asset UUID across all tracked files returns 0 hits after
    the change; before it, exactly two, both README line 3. Nothing survives in
    docs-site/, which carries no copy of the README and no user-attachments URL at
    all.

  • Byte check of the published asset against the local render: a GET of the exact URL
    as written in the README returns HTTP 200 image/png with sha256
    c62a38ab3bf0c8fe82dc194bd8250ee99e324bfdd13242a271f18a8f5c69e107, identical to the
    file on disk.

  • A HEAD probe of that URL returns 403, but so does a HEAD probe of the previously
    published banner, which is live and rendering. The signed storage URL behind the
    redirect refuses HEAD, so GET is the only probe that carries information here. Noted
    because the 403 reads like a failed upload and is not one.

  • make check-large-files check-source-language -> exit 0.

  • scripts/check_commit_messages.py origin/main..HEAD -> exit 0.

  • No automated test covers this and none was added: no file under tests/ references
    user-attachments, and tests/test_living_docs.py globs raven/**/README.md and
    ui-tui/README.md, not the repository root README. The byte comparison above is the
    verification.

  • Relevant tests pass locally

  • Relevant lint / type checks pass locally

  • User-facing docs or screenshots are updated when needed

The two boxes above are left blank on purpose. No test suite exercises a README image
URL, and make lint covers Python that this diff does not touch. The checks that do
apply to a Markdown-only diff are the three gates listed above, and all three pass.

Risk

One rendered image at the top of the README landing view. No code path, no
configuration, no dependency, no behaviour change. The artwork carries only the product
tagline, so there is nothing disclosed by publishing it.

Rollback is a single revert of this commit, which restores the previous URL. The
previous asset is untouched and still served, so the rollback needs no re-upload.

  • Security impact considered
  • Backward compatibility considered
  • Rollback path is clear for risky changes

Related Issues

#126 hosts the asset. This PR does not close it.

Point both READMEs at a re-rendered hero banner. The composition and the
1536x656 geometry are unchanged; the tagline rule now sets its ampersands
in italic so they match the words on either side.

The asset is hosted as an attachment on the existing banner issue #126,
because the repository gate rejects image files by extension at any size.

Co-authored-by: Claude (claude-opus-5[1m]) <noreply@anthropic.com>
@LivXue
LivXue requested review from 0xKT and gloryfromca September 19, 2026 16:43

@gloryfromca gloryfromca left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

No blockers; this can merge as far as I am concerned.

The new hosted asset resolves as a valid 1536x656 PNG, preserves the prior composition and wording, and makes the stated italic ampersand correction. Both localized READMEs use the same URL, and no prohibited asset is added to the repository.

Coverage: I checked AGENTS.md constraints, the complete diff, surrounding README content, the prior banner-refresh history, backward compatibility and rollback, test scope and absence of test weakening, and the repository asset/architecture rules. There are no runtime callers for this documentation-only URL change.

Verification: the large-file, source-language, and commit-message scripts passed directly through uv; pre-commit passed for both READMEs; and git diff --check passed. No automated test targets root README image URLs. All completed GitHub checks were green when reviewed; one unit-test shard was still pending. (make itself is unavailable in this environment, so I invoked the exact underlying scripts.)

@ZuyiZhou ZuyiZhou left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Approving. Every claim here is checkable and all of them check out:

  • The new URL returns HTTP 200 image/png, sha256 c62a38ab3bf0c8fe82dc194bd8250ee99e324bfdd13242a271f18a8f5c69e107 -- the exact digest stated -- and the PNG header reads 1536x656, so the geometry really is unchanged.
  • The old UUID has zero hits across tracked files; the new one appears in exactly two, both README line 3, same URL in each.
  • The old asset still returns 200, so the rollback claim holds: reverting restores a URL that is still served and needs no re-upload.

Hosting it as an attachment rather than committing it is the right reading of section 7, which says to keep public-report assets outside git and link to them. At 1.55 MB a committed copy would have failed the extension block and the size limit both.

Leaving the two verification boxes blank and explaining why is the correct call, not a gap: no suite covers a README image URL, and test_living_docs.py globs raven/**/README.md and ui-tui/README.md, not the root. The byte comparison is the verification, and it is a better one than a test would have been.

The HEAD-returns-403 note was worth writing down. I would have read that as a failed upload too.

@LivXue
LivXue merged commit 04eb8a3 into main Sep 20, 2026
21 checks passed
@LivXue
LivXue deleted the docs/refresh_readme_hero_banner branch September 20, 2026 02:09
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants