Skip to content

One canonical <=100-char description across README, About, and Docker Hub - #423

Merged
ptr727 merged 5 commits into
developfrom
readme-description-consistency
Jul 24, 2026
Merged

One canonical <=100-char description across README, About, and Docker Hub#423
ptr727 merged 5 commits into
developfrom
readme-description-consistency

Conversation

@ptr727

@ptr727 ptr727 commented Jul 24, 2026

Copy link
Copy Markdown
Owner

A new Docker Hub repo caps its short description near 100 characters, so the README's intro line could not be reused as-is. Make the README opening the one canonical short description and audit it across every surface it feeds.

  • H1 is the repository name - a hyphenated name may render its hyphens as spaces (Financial-Modeling -> Financial Modeling). New audit check.
  • Intro line: single sentence, link-free, <=100 characters - Docker Hub's short-description cap, the tightest surface. New length check.
  • One line, four surfaces - it mirrors to the GitHub About description (already checked), the HISTORY.md opening (already checked), and now the Docker Hub short description (new best-effort check: image name = owner/repo lowercased, unauthenticated read, skipped on 404).

spec/readme-structure.md (item 1 + the Docker Hub section) and the verbatim Repository Details section state the rule.

Already earning its keep: the audit flags PhotoCleaner's 150-char intro and its Docker Hub tagline that does not match the README. Verified: selftest + validate + markdownlint green; the Docker Hub fetch resolves ptr727/photocleaner live.

@ptr727 @claude
One canonical <=100-char description across README, About, and Docker…
1ca0e0c 
… Hub

A new Docker Hub repo caps its short description near 100 characters, so the
README's intro line could not carry as-is. Make the README opening the one
canonical short description and audit it across every surface it feeds:

- The README H1 is the repository name (a hyphenated name may render its hyphens
  as spaces, Financial-Modeling -> Financial Modeling); the audit checks it.
- The intro line is a single sentence, link-free, at most 100 characters - Docker
  Hub's cap, the tightest surface. The audit flags an over-length intro.
- That one line mirrors to the GitHub About description (already checked) and,
  for a docker repo, the Docker Hub short description (new best-effort check via
  the Docker Hub API; the image name is owner/repo lowercased, skipped on 404).

Repository Details (verbatim) and spec/readme-structure.md state the rule.
Already surfacing drift: PhotoCleaner's 150-char intro and its unsynced Docker
Hub tagline.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Copilot AI review requested due to automatic review settings July 24, 2026 17:32
Copilot AI reviewed Jul 24, 2026
View reviewed changes

Copilot AI 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.

Pull request overview

This PR formalizes a single canonical short description sentence (README intro line) and extends the fleet audit to validate that this same line cleanly mirrors to other metadata surfaces, including Docker Hub.

Changes:

  • Update the README-structure spec to require a link-free, single-sentence intro line capped at 100 characters and to define Docker Hub short description mirroring.
  • Extend spec/audit.py to validate README H1 naming, intro-line length/link-freedom, and (for Docker-publishing repos) best-effort Docker Hub short-description mirroring.
  • Update AGENTS "Repository Details" to state the <=100-character constraint and Docker Hub mirroring rule.

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 2 comments.

File Description
spec/readme-structure.md Tightens the README title/intro contract and documents Docker Hub short-description vs overview expectations.
spec/audit.py Implements new audit checks for H1 name, intro-line constraints, and Docker Hub short-description mirroring.
AGENTS.md Documents the <=100-character canonical description rule and Docker Hub short-description mirroring in the repo details contract.

Comment thread spec/audit.py Outdated
Comment thread spec/audit.py Outdated
@ptr727 @claude
Address Copilot: canonical repo name for the H1 check, shorter DH tim…
8cfcc26 
…eout

- H1-title check uses live['name'] (the GitHub API canonical name), not the
  registry-URL slug which can carry a different case; falls back to the slug.
- Docker Hub best-effort fetch timeout 15s -> 5s so it can't feel-hang the audit.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Copilot AI review requested due to automatic review settings July 24, 2026 17:37
Copilot AI reviewed Jul 24, 2026
View reviewed changes

Copilot AI 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.

Pull request overview

Copilot reviewed 3 out of 3 changed files in this pull request and generated 2 comments.

Comment thread spec/audit.py Outdated
Comment thread spec/audit.py
@ptr727 @claude
Address Copilot: distinguish Docker Hub 404 from a transient failure
b950c47 
docker_hub_description() returned None on any error, so a transient failure
silently skipped the check. Now a 404 (image not at the derived name) returns
None and is skipped, while a transient error is raised and the caller catches it
into a DRIFT 'could not verify' advisory - surfaced, never silently passed, and
never aborting audit_repo for that repo's other findings.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Copilot AI review requested due to automatic review settings July 24, 2026 17:44
Copilot AI reviewed Jul 24, 2026
View reviewed changes

Copilot AI 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.

Pull request overview

Copilot reviewed 3 out of 3 changed files in this pull request and generated 1 comment.

Comment thread spec/audit.py
@ptr727 @claude
Address Copilot: guard a missing H1 (title None) in the readme check
355ece2 
title_and_intro returns title=None when README.md has no '# ' H1; the H1-name
check called title.replace unconditionally and would raise. Emit a 'no H1'
LETTER instead.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Copilot AI review requested due to automatic review settings July 24, 2026 17:50
Copilot AI reviewed Jul 24, 2026
View reviewed changes

Copilot AI 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.

Pull request overview

Copilot reviewed 3 out of 3 changed files in this pull request and generated 1 comment.

Comments suppressed due to low confidence (1)

spec/audit.py:743

  • This comment wraps a sentence across multiple lines and uses a semicolon splice. AGENTS.md comment guidance prefers one sentence per line and no semicolon splices in agent-authored prose.
            # Docker Hub short description mirrors the same intro, for a repo that publishes a docker image. A
            # transient lookup failure surfaces as a DRIFT ("could not verify") rather than aborting the audit or
            # silently passing; a 404 (image not at the derived name) returns None and is skipped.

Comment thread spec/audit.py Outdated
@ptr727 @claude
Address Copilot: recast comment semicolon splices, one sentence per line
eb53d6e 
The new readme/description comments used clause-joining semicolons and wrapped a
sentence across lines, the exact pattern the Documentation Style Conventions ban.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Copilot AI review requested due to automatic review settings July 24, 2026 17:56
Copilot AI reviewed Jul 24, 2026
View reviewed changes

Copilot AI 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.

Pull request overview

Copilot reviewed 3 out of 3 changed files in this pull request and generated no new comments.

@ptr727
ptr727 merged commit 9d20aa6 into develop Jul 24, 2026
7 checks passed
@ptr727
ptr727 deleted the readme-description-consistency branch July 24, 2026 18:10
@ptr727 ptr727 mentioned this pull request Jul 24, 2026
Merged
ptr727 added a commit that referenced this pull request Jul 24, 2026
@ptr727
Promote develop to main: genericize verbatim sections + canonical des…
e83288e 
…cription rule (#422, #423) (#424)

Two governance PRs refining the section-fidelity model from downstream
feedback:

- **#422** - genericize the verbatim AGENTS sections for clean carry
(de-link 24 hub-only 404 links), mask a job's owned `needs:` list in
normalize(), Operational Repositories appliesTo:*, reclassify Repository
Onboarding as hub-only, and add the content-duplication reconciliation
rule + an undeclared-section audit advisory (hub exempted). Resolves the
hub-side issues the PlexCleaner convergence surfaced.
- **#423** - one canonical <=100-char description across README / GitHub
About / Docker Hub, with H1-name and length audit checks.

**Fleet impact:** re-vendors the (now clean) verbatim AGENTS sections
and the Repository Details section; the audit gains the section advisory
+ the description checks. Burned down via the AGENTS refreshes already
in motion.

Merge commit, no release fires.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

Copilot code review Copilot
Copilot review effort
Applies to this pull request for everyone.Learn more about Copilot code review.
Copilot left review comments

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

2 participants

@ptr727