mirror of
https://github.com/tiennm99/ghglance.git
synced 2026-10-11 12:18:55 +00:00
tiennm99
3fc8a59de6
The Marketplace rejects ghstats as an action name, so the repo, Go module, binary, and action share the name ghglance instead. The demo workflow keeps reading the existing GHSTATS_TOKEN repo secret.
66 lines
3.2 KiB
Markdown
66 lines
3.2 KiB
Markdown
# ghglance — 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. ghglance 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) |
|
|
| **ghglance** | 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).
|