bookorbit/docs/STAR_HISTORY.md

Star History Chart

BookOrbit renders its README star-history chart in the repository instead of depending on an external chart service.

Storage

The star-history branch contains two generated files:

• star-history.json: validated daily aggregate counts and source metadata
• star-history.svg: the self-contained README chart

The workflow creates normal commits on this branch. It does not force-push, so previous chart data remains recoverable without adding automated commits to main.

The bootstrap snapshot at scripts/star-history/bootstrap.json contains the initial exact aggregate history. It is used only when the publication branch does not exist. Raw stargazer records and GitHub usernames are never stored.

Refresh behavior

The Star History workflow runs daily and can also be dispatched manually. It restores the stored series, obtains the current repository star count, replaces any existing point for the current UTC date, renders the SVG, and publishes the JSON and SVG in one branch commit.

The built-in workflow token is sufficient for daily snapshots. An optional STAR_HISTORY_TOKEN repository secret belonging to a collaborator enables exact-history refreshes from GitHub's timestamped stargazer endpoint. Exact refreshes replace the aggregate curve and correct any drift from previous snapshots. If the endpoint is unavailable, the workflow retains the stored history and falls back to the current count.

The generator refuses malformed series, data for a different repository, future points, invalid API responses, and exact histories beyond GitHub's pagination limit. A failed run publishes nothing.

Local commands

Run the focused test suite:

pnpm run test:star-history

Generate from a stored series and the current count:

GITHUB_TOKEN=... node scripts/star-history/generate.mjs \
  --repo bookorbit/bookorbit \
  --series star-history.json \
  --bootstrap scripts/star-history/bootstrap.json \
  --out star-history.svg

Set STAR_HISTORY_TOKEN as well to attempt a complete exact-history refresh.