mirror of
https://github.com/bookorbit/bookorbit.git
synced 2026-11-03 00:11:37 -06:00
neon
e8ca5fceb2
Keep README growth data self-hosted and resilient when detailed GitHub stargazer history is unavailable.
58 lines
2.0 KiB
Markdown
58 lines
2.0 KiB
Markdown
# 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:
|
|
|
|
```bash
|
|
pnpm run test:star-history
|
|
```
|
|
|
|
Generate from a stored series and the current count:
|
|
|
|
```bash
|
|
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.
|