From df0f65a151ceb0996c027a7fc1386019b2aa6b22 Mon Sep 17 00:00:00 2001
From: camilleislasse <camille.islasse@acseo-conseil.fr>
Date: Sun, 18 Oct 2026 20:32:31 +0200
Subject: [PATCH] feat: build the contributors list on /about from GitHub

---
 KNOWLEDGE_BASE.md                             |   4 +-
 app/Http/Controllers/AboutController.php      |   7 +-
 app/Queries/ContributorsQuery.php             | 119 ++++++++++++++++++
 resources/js/lib/about.ts                     |  50 --------
 resources/js/pages/about/show.tsx             |  20 ++-
 .../Controllers/AboutControllerTest.php       |  26 ++++
 tests/Pest.php                                |  24 ++++
 tests/Unit/Queries/ContributorsQueryTest.php  | 111 ++++++++++++++++
 8 files changed, 302 insertions(+), 59 deletions(-)
 create mode 100644 app/Queries/ContributorsQuery.php
 create mode 100644 tests/Unit/Queries/ContributorsQueryTest.php

diff --git a/KNOWLEDGE_BASE.md b/KNOWLEDGE_BASE.md
index 3a3dfd790..8a03ef82b 100644
--- a/KNOWLEDGE_BASE.md
+++ b/KNOWLEDGE_BASE.md
@@ -499,9 +499,9 @@ Sources: [metrics controller](app/Http/Controllers/ProductMetricsController.php)
 
 ### About, changelog, and policies
 
-The public **About** page describes the livestream project and its contributors. The **Changelog**, opened from the navigation or the side column, lists the pull requests merged into `production` on GitHub, a few days at a time. The **Brand** page at `/brand` offers the logo, wordmark, colors, typography, and wallpapers; right-clicking the logo in the navigation also copies it or links there. **Terms** and **Privacy** explain acceptable use and data handling. Public posts may be indexed or copied outside /dev/null; content and search queries can be processed by automated or AI services. Read those policies before posting sensitive information or relying on deletion to remove every external copy.
+The public **About** page describes the livestream project and lists everyone with a commit on production, read from GitHub once an hour, most commits first; when GitHub cannot be reached the page says so instead of showing the list. The **Changelog**, opened from the navigation or the side column, lists the pull requests merged into `production` on GitHub, a few days at a time. The **Brand** page at `/brand` offers the logo, wordmark, colors, typography, and wallpapers; right-clicking the logo in the navigation also copies it or links there. **Terms** and **Privacy** explain acceptable use and data handling. Public posts may be indexed or copied outside /dev/null; content and search queries can be processed by automated or AI services. Read those policies before posting sensitive information or relying on deletion to remove every external copy.
 
-Sources: [public page routes](routes/web.php), [About](resources/js/pages/about/show.tsx), [privacy policy](resources/js/pages/privacy/show.tsx), [terms](resources/js/pages/terms/show.tsx).
+Sources: [public page routes](routes/web.php), [About](resources/js/pages/about/show.tsx), [contributors](app/Queries/ContributorsQuery.php), [privacy policy](resources/js/pages/privacy/show.tsx), [terms](resources/js/pages/terms/show.tsx).
 
 ### Tom's repository insights and community statistics
 
diff --git a/app/Http/Controllers/AboutController.php b/app/Http/Controllers/AboutController.php
index 98b461175..19239dd92 100644
--- a/app/Http/Controllers/AboutController.php
+++ b/app/Http/Controllers/AboutController.php
@@ -4,15 +4,18 @@
 
 namespace App\Http\Controllers;
 
+use App\Queries\ContributorsQuery;
 use App\Services\PageMetadata;
 use Inertia\Inertia;
 use Inertia\Response;
 
 final readonly class AboutController
 {
-    public function show(PageMetadata $metadata): Response
+    public function show(ContributorsQuery $contributors, PageMetadata $metadata): Response
     {
-        return Inertia::render('about/show')->withViewData(['preview' => $metadata->page(
+        return Inertia::render('about/show', [
+            'contributors' => $contributors->get(...),
+        ])->withViewData(['preview' => $metadata->page(
             'About - /dev/null',
             'How /dev/null was built in the open: from the first commit on stream to the developers who joined and the people who shipped it.',
             route('about.show'),
diff --git a/app/Queries/ContributorsQuery.php b/app/Queries/ContributorsQuery.php
new file mode 100644
index 000000000..62389e60c
--- /dev/null
+++ b/app/Queries/ContributorsQuery.php
@@ -0,0 +1,119 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Queries;
+
+use App\Services\GitHub;
+use Illuminate\Http\Client\HttpClientException;
+use Illuminate\Support\Collection;
+use Illuminate\Support\Facades\Cache;
+use Illuminate\Support\Fluent;
+
+/**
+ * @phpstan-type Contributor array{login: string, commits: int}
+ */
+final readonly class ContributorsQuery
+{
+    private const int PerPage = 100;
+
+    private const int MaxPages = 10;
+
+    private const int Ttl = 3600;
+
+    private const int FailedTtl = 60;
+
+    /**
+     * GitHub reports them as ordinary accounts, so they are named rather than detected.
+     */
+    private const array Agents = ['ampagent', 'claude'];
+
+    public function __construct(private GitHub $github)
+    {
+        //
+    }
+
+    /**
+     * Everyone with a commit on production, most commits first, as GitHub counts them. A failed read is kept for a
+     * minute, so an outage doesn't send every visitor to GitHub.
+     *
+     * @return list<Contributor>|null
+     */
+    public function get(): ?array
+    {
+        $repository = config()->string('services.github.repository');
+        $key = "about:contributors:{$repository}";
+
+        /** @var list<Contributor>|false|null $contributors */
+        $contributors = Cache::get($key);
+
+        if ($contributors === null) {
+            $contributors = $this->fetch($repository) ?? false;
+
+            Cache::put($key, $contributors, $contributors === false ? self::FailedTtl : self::Ttl);
+        }
+
+        return $contributors === false ? null : $contributors;
+    }
+
+    /**
+     * @return list<Contributor>|null
+     */
+    private function fetch(string $repository): ?array
+    {
+        $people = [];
+
+        for ($page = 1; $page <= self::MaxPages; $page++) {
+            try {
+                $accounts = $this->github->request()->get("repos/{$repository}/contributors", [
+                    'per_page' => self::PerPage,
+                    'page' => $page,
+                ])->throw()->collect();
+            } catch (HttpClientException) {
+                return null;
+            }
+
+            if ($accounts->isNotEmpty() && ! array_is_list($accounts->all())) {
+                return null;
+            }
+
+            $people = [...$people, ...$this->people($accounts)];
+
+            if ($accounts->count() < self::PerPage) {
+                break;
+            }
+        }
+
+        return $people;
+    }
+
+    /**
+     * @param  Collection<int|string, mixed>  $accounts
+     * @return list<Contributor>
+     */
+    private function people(Collection $accounts): array
+    {
+        return array_values($accounts->where('type', 'User')
+            ->mapInto(Fluent::class)
+            ->filter($this->isPerson(...))
+            ->map(fn (Fluent $account): array => [
+                'login' => $account->string('login')->value(),
+                'commits' => $account->integer('contributions'),
+            ])
+            ->all());
+    }
+
+    /**
+     * An account with a name and a count behind it, and not one of the agents.
+     *
+     * @param  Fluent<string, mixed>  $account
+     */
+    private function isPerson(Fluent $account): bool
+    {
+        $login = $account->string('login')->value();
+
+        return $login !== ''
+            && is_int($account->get('contributions'))
+            && ! in_array(mb_strtolower($login), self::Agents, true);
+    }
+}
diff --git a/resources/js/lib/about.ts b/resources/js/lib/about.ts
index c6bbc3621..faaeb6e56 100644
--- a/resources/js/lib/about.ts
+++ b/resources/js/lib/about.ts
@@ -181,53 +181,3 @@ export const storyAfter: StoryEvent[] = [
         },
     },
 ];
-
-/**
- * Everyone with a commit on production, most commits first. Bots and agents are left out.
- */
-export const storyContributors: StoryContributor[] = [
-    { login: 'xHeaven', commits: 199 },
-    { login: 'nunomaduro', commits: 176 },
-    { login: 'mnapoli', commits: 61 },
-    { login: 'brendt', commits: 42 },
-    { login: 'simonhamp', commits: 18 },
-    { login: 'paulinevos', commits: 16 },
-    { login: 'jubianchi', commits: 16 },
-    { login: 'MrPunyapal', commits: 15 },
-    { login: 'sadiqk2', commits: 8 },
-    { login: 'camilleislasse', commits: 6 },
-    { login: 'hbenabdallah', commits: 5 },
-    { login: 'vtlxx', commits: 5 },
-    { login: 'robelsust', commits: 4 },
-    { login: 'HelgeSverre', commits: 4 },
-    { login: 'SanderMuller', commits: 3 },
-    { login: 'MaximeGoncalves', commits: 3 },
-    { login: 'mathiasonea', commits: 3 },
-    { login: 'fernandofreamunde', commits: 3 },
-    { login: 'mon4ssi', commits: 2 },
-    { login: 'hbenjacquet', commits: 2 },
-    { login: 'Akiyo974', commits: 2 },
-    { login: 'Chemaclass', commits: 2 },
-    { login: 'eznix86', commits: 2 },
-    { login: 'BENNIEV-ZA', commits: 2 },
-    { login: 'ahosker', commits: 2 },
-    { login: 'eramitgupta', commits: 1 },
-    { login: 'utsavsomaiya', commits: 1 },
-    { login: 'tooinfinity', commits: 1 },
-    { login: 'murrant', commits: 1 },
-    { login: 'RobinMalfait', commits: 1 },
-    { login: 'prateekbhujel', commits: 1 },
-    { login: 'ondrejmirtes', commits: 1 },
-    { login: 'lazarospsa', commits: 1 },
-    { login: 'kachelle', commits: 1 },
-    { login: 'kadirtikil', commits: 1 },
-    { login: 'jjaybrown', commits: 1 },
-    { login: 'GTS-MEGHNI', commits: 1 },
-    { login: 'faissaloux', commits: 1 },
-    { login: 'fabpl', commits: 1 },
-    { login: 'danielh-official', commits: 1 },
-    { login: 'chrisgocode', commits: 1 },
-    { login: 'AmanuelLegese', commits: 1 },
-    { login: 'alaminfirdows', commits: 1 },
-    { login: 'aaqidmasoodi', commits: 1 },
-];
diff --git a/resources/js/pages/about/show.tsx b/resources/js/pages/about/show.tsx
index 409804079..8adba11ec 100644
--- a/resources/js/pages/about/show.tsx
+++ b/resources/js/pages/about/show.tsx
@@ -16,6 +16,7 @@ import {
 import AppLayout from '@/layouts/app-layout';
 import type {
     StoryCommit,
+    StoryContributor,
     StoryEvent,
     StoryEventKind,
     StoryStream,
@@ -24,7 +25,6 @@ import {
     storyAfter,
     storyAfterLane,
     storyBefore,
-    storyContributors,
     storyFounders,
     storyStreams,
 } from '@/lib/about';
@@ -264,10 +264,10 @@ function Stream({ stream }: { stream: StoryStream }) {
     );
 }
 
-function Contributors() {
+function Contributors({ contributors }: { contributors: StoryContributor[] }) {
     return (
         <ul className="grid grid-cols-[repeat(auto-fill,minmax(11rem,1fr))] gap-2">
-            {storyContributors.map((contributor) => (
+            {contributors.map((contributor) => (
                 <li key={contributor.login}>
                     <a
                         href={`https://github.com/${contributor.login}`}
@@ -301,7 +301,11 @@ function Contributors() {
     );
 }
 
-export default function Show() {
+export default function Show({
+    contributors,
+}: {
+    contributors: StoryContributor[] | null;
+}) {
     const { repository } = usePage().props;
     return (
         <>
@@ -392,7 +396,13 @@ export default function Show() {
 
                 <DocumentSection id="contributors" title="Contributors">
                     <p>Everyone who has a commit on production. Thank you.</p>
-                    <Contributors />
+                    {contributors ? (
+                        <Contributors contributors={contributors} />
+                    ) : (
+                        <p className="text-muted-foreground">
+                            GitHub couldn't be reached. Try again in a minute.
+                        </p>
+                    )}
                     <p className="text-muted-foreground">
                         Want to be on this list?{' '}
                         <a
diff --git a/tests/Feature/Controllers/AboutControllerTest.php b/tests/Feature/Controllers/AboutControllerTest.php
index f507a7170..d6b342b53 100644
--- a/tests/Feature/Controllers/AboutControllerTest.php
+++ b/tests/Feature/Controllers/AboutControllerTest.php
@@ -3,14 +3,20 @@
 declare(strict_types=1);
 
 use App\Models\User;
+use Illuminate\Http\Client\ConnectionException;
+use Illuminate\Support\Facades\Http;
 
 it('renders the about page for guests', function (): void {
+    fakeGitHubContributors([gitHubContributor('xHeaven', 187)]);
+
     $this->get(route('about.show'))
         ->assertOk()
         ->assertInertia(fn ($page) => $page->component('about/show'));
 });
 
 it('renders the about page for signed in users', function (): void {
+    fakeGitHubContributors([gitHubContributor('xHeaven', 187)]);
+
     $this->actingAs(User::factory()->create())
         ->get(route('about.show'))
         ->assertOk()
@@ -18,9 +24,29 @@
 });
 
 it('describes the about page to search engines and link previews', function (): void {
+    fakeGitHubContributors([gitHubContributor('xHeaven', 187)]);
+
     $this->get(route('about.show'))
         ->assertOk()
         ->assertSee('<title>About - /dev/null</title>', false)
         ->assertSee('<link rel="canonical" href="'.route('about.show').'">', false)
         ->assertSee('"@type":"WebPage"', false);
 });
+
+it('hands the contributors to the page', function (): void {
+    fakeGitHubContributors([gitHubContributor('xHeaven', 187)]);
+
+    $this->get(route('about.show'))
+        ->assertOk()
+        ->assertInertia(fn ($page) => $page
+            ->has('contributors', 1)
+            ->where('contributors.0', ['login' => 'xHeaven', 'commits' => 187]));
+});
+
+it('leaves the contributors out while GitHub is unreachable', function (): void {
+    Http::fake(fn () => throw new ConnectionException('timeout'));
+
+    $this->get(route('about.show'))
+        ->assertOk()
+        ->assertInertia(fn ($page) => $page->where('contributors', null));
+});
diff --git a/tests/Pest.php b/tests/Pest.php
index 6e10bd963..6fd9d4ad3 100644
--- a/tests/Pest.php
+++ b/tests/Pest.php
@@ -10,7 +10,9 @@
 use App\Services\OpenAI;
 use App\Services\SignedCommits;
 use Carbon\CarbonInterface;
+use GuzzleHttp\Promise\PromiseInterface;
 use Illuminate\Foundation\Testing\RefreshDatabase;
+use Illuminate\Http\Client\Request;
 use Illuminate\Support\Facades\DB;
 use Illuminate\Support\Facades\Http;
 use Illuminate\Support\Facades\Process;
@@ -131,6 +133,28 @@ function fakeGitHubAccount(User $user, array $account = []): void
     fakeGitHubSshKeys(User::factory()->make(['github_id' => $user->github_id, 'username' => $account['login']]));
 }
 
+/**
+ * @return array<string, mixed>
+ */
+function gitHubContributor(string $login, int $commits, string $type = 'User'): array
+{
+    return ['login' => $login, 'contributions' => $commits, 'type' => $type];
+}
+
+/**
+ * Serves the contributors of the repository like GitHub does: most commits first, a page at a time.
+ *
+ * @param  list<array<string, mixed>>  $contributors
+ */
+function fakeGitHubContributors(array $contributors): void
+{
+    Http::fake(['api.github.com/repos/'.config()->string('services.github.repository').'/contributors*' => function (Request $request) use ($contributors): PromiseInterface {
+        $perPage = (int) $request['per_page'];
+
+        return Http::response(array_slice($contributors, ((int) $request['page'] - 1) * $perPage, $perPage));
+    }]);
+}
+
 /**
  * @param  list<SshPublicKey>  $keys
  * @param  list<SshPublicKey>  $signingKeys
diff --git a/tests/Unit/Queries/ContributorsQueryTest.php b/tests/Unit/Queries/ContributorsQueryTest.php
new file mode 100644
index 000000000..0b323ffd7
--- /dev/null
+++ b/tests/Unit/Queries/ContributorsQueryTest.php
@@ -0,0 +1,111 @@
+<?php
+
+declare(strict_types=1);
+
+use App\Queries\ContributorsQuery;
+use Illuminate\Http\Client\ConnectionException;
+use Illuminate\Support\Facades\Cache;
+use Illuminate\Support\Facades\Http;
+
+it('lists everyone with a commit, as GitHub counts them', function (): void {
+    fakeGitHubContributors([gitHubContributor('xHeaven', 187), gitHubContributor('jubianchi', 1)]);
+
+    expect(resolve(ContributorsQuery::class)->get())->toBe([
+        ['login' => 'xHeaven', 'commits' => 187],
+        ['login' => 'jubianchi', 'commits' => 1],
+    ]);
+});
+
+it('leaves out the bots and the agents, whatever case they are written in', function (): void {
+    fakeGitHubContributors([
+        gitHubContributor('xHeaven', 187),
+        gitHubContributor('ampagent', 8),
+        gitHubContributor('Claude', 2),
+        gitHubContributor('dependabot', 4, 'Bot'),
+    ]);
+
+    expect(resolve(ContributorsQuery::class)->get())->toBe([['login' => 'xHeaven', 'commits' => 187]]);
+});
+
+it('reads every page GitHub has, up to a thousand people', function (int $contributors, int $expected, int $requests): void {
+    fakeGitHubContributors(array_map(fn (int $number): array => gitHubContributor("dev{$number}", 2000 - $number), range(1, $contributors)));
+
+    expect(resolve(ContributorsQuery::class)->get())->toHaveCount($expected);
+
+    Http::assertSentCount($requests);
+})->with([
+    'one page' => [100, 100, 2],
+    'two pages' => [150, 150, 2],
+    'more than ten pages' => [1200, 1000, 10],
+]);
+
+it('keeps reading when a page is full but some of it is left out', function (): void {
+    $page = array_map(fn (int $number): array => gitHubContributor("dev{$number}", 200 - $number), range(1, 99));
+
+    fakeGitHubContributors([...$page, gitHubContributor('dependabot', 4, 'Bot'), gitHubContributor('xHeaven', 1)]);
+
+    expect(resolve(ContributorsQuery::class)->get())->toHaveCount(100);
+
+    Http::assertSentCount(2);
+});
+
+it('skips what GitHub sends without a login or a count', function (): void {
+    fakeGitHubContributors([['login' => 'ghost', 'type' => 'User'], ['contributions' => 3, 'type' => 'User'], gitHubContributor('xHeaven', 187)]);
+
+    expect(resolve(ContributorsQuery::class)->get())->toBe([['login' => 'xHeaven', 'commits' => 187]]);
+});
+
+it('asks GitHub again an hour later, not before', function (): void {
+    fakeGitHubContributors([gitHubContributor('xHeaven', 187)]);
+
+    resolve(ContributorsQuery::class)->get();
+    $this->travel(59)->minutes();
+    resolve(ContributorsQuery::class)->get();
+
+    Http::assertSentCount(1);
+
+    $this->travel(2)->minutes();
+    resolve(ContributorsQuery::class)->get();
+
+    Http::assertSentCount(2);
+});
+
+it('keeps an answer with nobody in it for the hour, since GitHub did answer', function (): void {
+    fakeGitHubContributors([gitHubContributor('claude', 2)]);
+
+    expect(resolve(ContributorsQuery::class)->get())->toBe([])
+        ->and(Cache::get('about:contributors:'.config()->string('services.github.repository')))->toBe([]);
+
+    $this->travel(2)->minutes();
+    resolve(ContributorsQuery::class)->get();
+
+    Http::assertSentCount(1);
+});
+
+it('has nobody to show while GitHub is unreachable, and tries again a minute later', function (): void {
+    $attempts = 0;
+    Http::fake(function () use (&$attempts): never {
+        $attempts++;
+
+        throw new ConnectionException('timeout');
+    });
+
+    expect(resolve(ContributorsQuery::class)->get())->toBeNull();
+
+    resolve(ContributorsQuery::class)->get();
+    expect($attempts)->toBe(1);
+
+    $this->travel(61)->seconds();
+    resolve(ContributorsQuery::class)->get();
+
+    expect($attempts)->toBe(2);
+});
+
+it('has nobody to show when GitHub answers with an error or with something that is not a list', function (array $body, int $status): void {
+    Http::fake(['api.github.com/*' => Http::response($body, $status)]);
+
+    expect(resolve(ContributorsQuery::class)->get())->toBeNull();
+})->with([
+    'an error' => [['message' => 'Not Found'], 404],
+    'an object' => [['message' => 'Moved'], 200],
+]);