mirror of
https://github.com/tiennm99/ghstats.git
synced 2026-09-02 00:19:35 +00:00
tiennm99andGitHub
059c8b11ad
project-roadmap.md went from a 146-line phase-by-phase history to a 48-line focused view: what's planned, what's out of scope. Completed work is already in git log + GitHub Releases — the doc re-telling it was the thing most likely to rot and least likely to be read. project-overview-pdr.md: "Open questions" section dropped its stale bullet list and now just points at project-roadmap.md (single source of truth for planned work). code-standards.md: drop the ".claude/ directory" commit rule — that's a per-user workflow detail, not a project-level standard. Docs are for users of the CLI/Action and coworkers of this repo, nothing else.
66 lines
3.2 KiB
Markdown
66 lines
3.2 KiB
Markdown
# ghstats — Product Development Requirements
|
|
|
|
## One-liner
|
|
|
|
Single-binary Go CLI + GitHub Action that renders 15 themed SVG cards summarising a GitHub user's public (and optionally private) profile, for embedding in a profile README.
|
|
|
|
## Users
|
|
|
|
- **Primary**: GitHub users maintaining a profile README who want auto-updating stat cards without a self-hosted service.
|
|
- **Secondary**: Tools integrating profile summaries (dashboards, portfolio sites).
|
|
|
|
## Non-goals
|
|
|
|
- WakaTime-style editor telemetry.
|
|
- Cloning repos or running linguist locally (lowlighter/metrics territory). A future `-accurate-languages` mode may add per-commit REST classification; clone-mode is out of scope for v1.
|
|
- Real-time / per-request API server. ghstats is a scheduled batch renderer.
|
|
|
|
## Value proposition vs alternatives
|
|
|
|
| Tool | Language | Runs as | Solves per-commit attribution? |
|
|
| --- | --- | --- | --- |
|
|
| anuraghazra/github-readme-stats | JS | hosted service | No (byte-size only) |
|
|
| vn7n24fzkq/github-profile-summary-cards | TS | Action + hosted | No (primary-language-per-repo) |
|
|
| lowlighter/metrics (indepth) | JS | Action | Yes (clones + linguist-js) |
|
|
| **ghstats** | Go | Action + CLI | Partial (byte-weighted today; REST-per-commit planned) |
|
|
|
|
Distinguishing traits:
|
|
- **Single binary**: no Node, no Ruby, no Docker needed for CLI usage.
|
|
- **Seed-list sampling**: commit-history probes land on repos the user actually committed in (via `contributionsCollection.commitContributionsByRepository`), not top-starred or owned-only.
|
|
- **All-time variants**: for every time-bounded card (most-commit-language, productive-time, contributions), there's a lifetime counterpart.
|
|
- **Accurate defaults**: forks and private repos are **on** by default so cards reflect real activity; `-include-private` silently no-ops if the token lacks `repo` scope, so the default is safe for public runs too.
|
|
|
|
## Functional requirements
|
|
|
|
| # | Requirement |
|
|
| --- | --- |
|
|
| F1 | Render 15 cards per selected theme (see `docs/system-architecture.md`) |
|
|
| F2 | Support 65 themes ported from github-profile-summary-cards |
|
|
| F3 | Handle the full username→profile→cards flow in a single invocation |
|
|
| F4 | Package as GitHub Action with `commit_changes` auto-commit of output |
|
|
| F5 | Expose `-include-forks` / `-include-private` toggles |
|
|
| F6 | Apply byte-weighted commit-to-language attribution |
|
|
| F7 | Render smooth area charts for time-series (Catmull-Rom) |
|
|
| F8 | Support IANA timezones for productive-time (display `UTC±N.NN`) |
|
|
|
|
## Non-functional requirements
|
|
|
|
| Axis | Target |
|
|
| --- | --- |
|
|
| Runtime (scheduled Action) | < 60 s for typical user |
|
|
| GraphQL calls per run | < 100 |
|
|
| REST calls per run | 0 (may grow with future modes) |
|
|
| Dependencies | stdlib only (no Go module deps required) |
|
|
| Binary size | < 15 MB stripped |
|
|
| SVG output correctness | XML-escaped, no script injection from user data |
|
|
|
|
## Success metrics
|
|
|
|
- Cards render identically across `dracula`, `github`, `github_dark`, `nord_bright`, `tokyonight`.
|
|
- Test suite covers rendering, XML escaping, number formatting, language sort.
|
|
- `go vet ./...` and `go test ./...` clean on every commit.
|
|
|
|
## Open questions
|
|
|
|
Planned follow-on work lives in [`project-roadmap.md`](./project-roadmap.md).
|