Skip to content

fix(website): surface when community metrics were last refreshed - #330

Merged
danbaruka merged 1 commit into
IntersectMBO:mainfrom
IanoNjuguna:fix/community-metrics-freshness
Oct 16, 2026
Merged

danbaruka merged 1 commit into
IntersectMBO:mainfrom
IanoNjuguna:fix/community-metrics-freshness

Conversation

@IanoNjuguna

Copy link
Copy Markdown
Contributor

Description

Makes the freshness of the community metrics visible, which is what #327 asks for. Two changes:

  1. MonthlyPulse.tsx renders "Data as of 1 Aug 2026" style caption under the stats grid, taken from updatedAt. Formatted by hand in UTC rather than with toLocaleDateString, so the server-rendered and client-rendered strings are identical and the date can never mismatch on hydration. When the payload is flagged stale it appends "— GitHub API unavailable at build time".

  2. scripts/fetch-github-data.js no longer stamps a failed fetch as fresh. Previously updatedAt was unconditionally new Date(), so a failed API call produced a payload whose timestamp claimed "now" while the numbers were months old — rendering that timestamp as-is would have been worse than showing nothing. Now:

    • updatedAt advances only when every request in the run succeeded; otherwise the previous timestamp is preserved.
    • the payload gains stale: true when the run did not fully refresh.
    • the build log warns with the snapshot's age, plus a second warning past a 7-day threshold:
[github-data] Refresh failed — the site will render the snapshot from 2026-08-01T13:01:14.892Z (73 day(s) old).
[github-data] That snapshot is past the 7-day threshold. The community section shows its date, so the staleness is visible on the site.

Deliberately not failing the build: a transient API or rate-limit failure should not block a deploy of a documentation site. Visibility is the fix — the rendered date plus a loud warning. A hard gate is easy to add as a follow-up if that is preferred.

Semantics, stated plainly: updatedAt is when a complete refresh last succeeded. A partial refresh (say the contributors call fails while the stats calls succeed) keeps the older date and sets stale: true, so the site understates freshness rather than overstating it.

Fixes #327

Type of Change

  • Bug fix (non-breaking change which fixes an issue)
  • New feature (non-breaking change which adds functionality)
  • Breaking change (fix or feature that would cause existing functionality to not work as expected)
  • Documentation update

Testing

  • I have tested these changes locally
  • I have checked for broken links — build runs with onBrokenLinks: "throw" and onBrokenAnchors: "throw" and passes
  • Code examples have been tested — n/a

Script, both paths:

# success (all four calls ok)
updatedAt: 2026-10-14T10:03:32.185Z | stale: False

# failure — a copy of the script pointed at a non-existent repo, seeded with the committed snapshot
Contributors API returned 403
[github-data] Refresh failed — the site will render the snapshot from 2026-08-01T13:01:14.892Z (73 day(s) old).
updatedAt: 2026-08-01T13:01:14.892Z (unchanged) | stale: True
stats kept: {'mergedPRs': '136', 'openIssues': '12', 'closedIssues': '56'}

tsc --noEmit passes both with and without the new stale key in the snapshot, since the committed file predates the field and the component reads it defensively.

Production build passes and the caption renders under the stats grid.

Notes for review

  • The committed website/src/data/githubData.json is untouched by this PR — it is regenerated by the prebuild hook on every build, and the working-tree copy a build produces is not part of the diff.
  • Only MonthlyPulse is changed. Contributors.tsx renders the same payload and could get the same treatment; that overlaps Contributor list can include bot and AI-agent accounts (cursoragent is one today) #326 and was kept out.
  • Threshold (7 days) and copy are trivially adjustable — say the word if you'd prefer different wording, or a failing build instead of a warning.

Checklist

  • My code follows the style guidelines of this project
  • I have performed a self-review of my changes
  • I have made corresponding changes to the documentation — n/a
  • My changes generate no new warnings

@IanoNjuguna IanoNjuguna added the bug Something isn't working label Oct 14, 2026
MonthlyPulse rendered the numbers with no date, and the build-time fetch
stamped every payload with the current time even when the API call failed, so
a months-old snapshot could render as fresh with nothing on the page or in the
build log saying otherwise.

- MonthlyPulse renders "Data as of <date>" from updatedAt, formatted in UTC by
  hand (not toLocaleDateString) so the server and client render identical
  strings and the date cannot mismatch on hydration. A payload flagged stale
  appends "— GitHub API unavailable at build time".
- fetch-github-data.js advances updatedAt only when every request in the run
  succeeded, preserves the previous timestamp otherwise, marks the payload
  stale, and warns in the build log with the snapshot's age plus a second
  warning past a 7-day threshold. The build does not fail on purpose: a
  transient API or rate-limit failure should not block a deploy.

Verified both paths — a full refresh yields updatedAt today with stale false;
a run whose requests fail keeps the previous timestamp and stats and prints
both warnings.

Fixes IntersectMBO#327
@danbaruka
danbaruka merged commit cf046d1 into IntersectMBO:main Oct 16, 2026
1 check passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

bug Something isn't working

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Community metrics can silently go stale: updatedAt is never rendered and a failed fetch keeps old numbers

2 participants