Skip to content

Redesign the home page around Psalm with live leaderboards and share cards - #56

Merged
alies-dev merged 4 commits into
masterfrom
alies-dev/home-chosen
Nov 21, 2026
Merged

alies-dev merged 4 commits into
masterfrom
alies-dev/home-chosen

Conversation

@alies-dev

Copy link
Copy Markdown
Contributor

Context

The home page lists recently active repositories, but it doesn't say what Shepherd measures, how to set it up, or that it is part of Psalm. Links to shepherd.dev shared in Slack, X or Telegram show only "Shepherd", because the pages have no description or Open Graph tags.

Solution

Home page:

  • The hero reads "Watch your PHP get stricter." It has two buttons: "Add your project", which opens the Shepherd guide on psalm.dev, and "New to Psalm? Try it in 2 minutes", which opens the installation docs. Next to them are the three install commands with a Copy button.
  • "Projects reporting to Shepherd" has four tabs of 10 repositories each: Recently active, Level 1 club, Highest coverage and Largest codebases. Every row shows the coverage change since that repository's previous report. The three ranking tabs only include repositories with at least 1,000 expressions and a report in the last 90 days.
  • Recently active updates itself every 30 s from /recent, an HTML fragment rendered by the same PHP code as the page. Polling stops when the browser tab is hidden, when another tab is selected, or after 60 s without input.
  • "Shepherd is one part of Psalm" links to security analysis, plugins, automatic fixes and the language server.

Every page:

  • The header has a "by Psalm" link, "Install / Help" (the Shepherd guide) and an icon-only theme toggle. Links to the Psalm docs, Playground, Plugins, GitHub and Support are in a new footer.
  • Pages now have description, Open Graph and twitter:card tags, all pointing to one static 1200×630 image. On project pages the numbers go into the card text, for example "vimeo/psalm: 99.93% type coverage, Psalm level 1".

The project page gets an "Add to README" section with the badge Markdown and a Copy button.

Database load:

  • The ranking tabs share one snapshot cached for 5 minutes. The recent list keeps its 60 s cache.
  • With a warm cache the page runs no SQL, and /recent answers 304 without querying when nothing changed.
  • With a cold cache a render runs at most 6 queries, none of them per row. On MariaDB 10.5 they use repo_recent and the unique git_commit key, so psalm_reports is never scanned.
  • The sparkline query now uses FORCE INDEX (repo_recent): with USE INDEX, MariaDB scanned and sorted the whole table for vimeo/psalm.

The GitHub push webhook stores master commits even when CI never sends a report for them, so a repository's newest commit may have no report. The ranking tabs then use that repository's newest reported commit, so the repository stays on the boards.

The Shepherd guide at https://psalm.dev/docs/running_psalm/shepherd/ is not deployed yet. "Install / Help" and "Add your project" already point to it.

…hange

- Add Api::getBoards(): one snapshot (cached 300 s) with the level 1 club, highest coverage and largest codebases,
  ten repositories each, from repositories with at least 1,000 expressions and a report in the last 90 days.
- The snapshot starts from the newest commit per repository (MAX(id) group-by on repo_recent, LEFT JOIN
  psalm_reports). Every push to master is stored, also those CI never sent a report for, so for repositories whose
  newest commit has no report the newest reported commit comes from one batched UNION ALL query.
  Deltas and sparklines for the displayed rows come from the existing per-repository UNION ALL query.
- Recent repositories now carry the coverage change since the previous report; the list is limited to ten.
- Force repo_recent in the sparkline query: with USE INDEX the optimizer scanned and sorted the whole table
  for a repository with thousands of reports.
- Ask for the repo_recent index once per request.
- head.php takes an optional description and emits description, og:type, og:site_name, og:title,
  og:description, og:url (request path without the query string), og:image with alt text and
  twitter:card=summary_large_image. X falls back to the og tags for everything else.
- Add the 1200x630 card image assets/img/og.png.
- Header: wordmark with a "by Psalm" label, an Install / Help link and an icon-only theme toggle that cycles
  System, Light and Dark (aria-label and title carry the name). Footer: Psalm docs, Playground, Plugins, GitHub,
  Support, Shepherd source and Report a problem, on every page that renders the nav.
- Hero with the install terminal (dark in both themes) and a Copy button that copies only the three commands and
  hides itself without the Clipboard API. The old hero and the Add your project block are gone.
- Projects reporting to Shepherd: Recently active, Level 1 club, Highest coverage and Largest codebases as
  accessible tabs over server-rendered panels with identical fixed columns and ten rows each. The panels share one
  grid cell with JS, so switching tabs never changes the height. Without JS every panel stays visible.
- Recently active refreshes itself: GET /recent returns only the tbody (same renderer as the page, ETag and 304),
  polled every 30 s while the tab is selected, the page visible and the user active; changed rows are highlighted.
- Shepherd is one part of Psalm: four feature cards before the footer.
- Title and description from the newest report, e.g. "vimeo/psalm: 99.93% type coverage, Psalm level 1" and
  "238.7K expressions analysed across 2,258 reports.". Later pages ask for the newest report once more.
- A closed <details> "Add to README" next to the badges holds the Markdown of both badges with the shared Copy button.
@alies-dev alies-dev self-assigned this Nov 21, 2026
@alies-dev
alies-dev merged commit 98937d2 into master Nov 21, 2026
3 of 5 checks passed
@alies-dev
alies-dev deleted the alies-dev/home-chosen branch November 21, 2026 16:02
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.

1 participant