c6bdcfadb3Forgejo's download_count is cumulative with no history, so sample it daily into an append-only JSONL (git as the time-series DB) and render per-release, feat-vs-fix, and over-time charts client-side. - hack/snapshot-downloads.sh: paginated API pull, idempotent per-day append - .forgejo/workflows/track-downloads.yml: daily cron (only Forgejo Action; CI is otherwise Tekton) — needs DOWNLOAD_TRACKER_TOKEN secret - docs/downloads/: self-contained Chart.js dashboard + README Refs forgejo-mcp-5zy
44 lines
1.9 KiB
Markdown
44 lines
1.9 KiB
Markdown
# Release download analytics
|
||
|
||
Tracks how often each release asset is downloaded from Codeberg, over time.
|
||
|
||
## Why snapshots
|
||
|
||
The Forgejo API exposes a **cumulative** `download_count` per release asset
|
||
(`GET /api/v1/repos/{owner}/{repo}/releases`) but keeps **no history**. To see
|
||
trends you must sample the counter periodically and store it yourself. We sample
|
||
daily and append to `downloads.jsonl` — git is the time-series database.
|
||
|
||
## Pieces
|
||
|
||
| File | Role |
|
||
|------|------|
|
||
| `hack/snapshot-downloads.sh` | Pulls the API, flattens assets, appends one JSONL row per `(date, tag, asset)`. Idempotent per day. |
|
||
| `.forgejo/workflows/track-downloads.yml` | Daily cron (06:17 UTC) that runs the script and commits the new rows. |
|
||
| `docs/downloads/downloads.jsonl` | The append-only time series. |
|
||
| `docs/downloads/index.html` | Self-contained Chart.js dashboard. Fetches the JSONL, classifies assets + releases client-side. |
|
||
|
||
## Run it locally
|
||
|
||
```bash
|
||
hack/snapshot-downloads.sh # append today's snapshot
|
||
python3 -m http.server -d docs/downloads # then open http://localhost:8000
|
||
```
|
||
|
||
## CI requirements
|
||
|
||
This is the **only** Forgejo Actions workflow in the repo (CI/CD is otherwise
|
||
Tekton on the op1st cluster). It needs:
|
||
|
||
1. **Forgejo Actions enabled** for the repo (Settings → Actions → Enable).
|
||
2. A repo/org secret **`DOWNLOAD_TRACKER_TOKEN`** — a token with `write:repository`
|
||
used to push the daily commit back to the default branch.
|
||
|
||
## Charts
|
||
|
||
- **Per release × platform** — stacked bar of the latest snapshot. The binary
|
||
`tar.gz` assets are the real usage signal; `.mcpb` bundles and metadata
|
||
(checksums/sig/SBOM) are mostly automated tooling.
|
||
- **By release type** — each tag classified by its semver bump vs the previous
|
||
version (major = breaking, minor = feat, patch = fix), summing binary downloads.
|
||
- **Binary downloads over time** — grows as daily snapshots accumulate.
|