Files
poli0981andClaude Opus 5.5 2b4b988cc7 docs: sync the community docs with the repository
A read-through against the code found about forty claims that had drifted.

README:
- Dynamic game-count and version badges. The count is index.json's total.
  The version is the newest v* release by semver, since an app release
  published last would otherwise count as "latest".
- SvelteKit 3, every desktop package, and the shard layout without a last
  shard number.
- The media host, which commits deploy, and the nine workflows the table
  left out.
- The accessibility statement and form in the link lists.

SECURITY.md:
- Fix the broken bullet list.
- Describe the real stack, and pushes with the built-in GITHUB_TOKEN.
- Add to scope: the media host, /api/ingest/*, /api/updates/desktop and the
  avatar origin.

AUTHORS.md and username.txt:
- Donations are in FUNDING.yml.
- The Add-games template is gone.
- Test devices come from pc_spec.

The issue forms lose the hash URLs, the GitHub Pages permalink, and the
editing and GPG options.

web/README.md, dev_env (EN + VI), the acknowledgements and the contact page
are updated to match. The last two are not consent documents, so nobody is
asked to accept the terms again.

CHANGELOG [Unreleased] lists all three commits.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-09 08:43:39 +07:00

93 lines
5.1 KiB
Markdown

# Developer environment
IDE, language toolchains, and the day-to-day workflow used to develop this repo. Mirrored in Vietnamese at [`i18n/vi/dev_env.md`](i18n/vi/dev_env.md).
## IDEs
| Tool | Used for |
| ---------- | ------------------------------------------------------------------ |
| PyCharm | `scripts/` Python pipeline (data fetcher, scraper, generator) |
| WebStorm | `web/` SvelteKit + Svelte 5 + TypeScript, the Worker, `admin/` |
| RustRover | `web/src-tauri/` Tauri 2 desktop wrapper (Rust) |
JetBrains lineup, paid version, channel **2026.x**. Any equivalent editor (VS Code, Neovim, etc.) works — the repo is editor-agnostic.
## Toolchains
| Tool | Version | Notes |
| ----------- | ------------------- | --------------------------------------------- |
| Python | 3.15 | `scripts/` pipeline + Steam client |
| Node.js | 26 (`web/.node-version`) | web build, tests (`node:sqlite`), Tauri build |
| TypeScript | 7 + 6 | 7 (`@typescript/native`) type-checks; 6 stays for svelte-check and `svelte-kit sync` |
| Rust | stable (via rustup) | Tauri runtime |
| npm | bundled with Node | `web/package-lock.json` is the source of truth |
| Git | recent | GPG signing on (`commit.gpgsign=true`) |
| Tauri CLI | 2.x | invoked via `npm run tauri ...` |
The CI workflows in [`.github/workflows/`](../.github/workflows) pin these versions explicitly, and `web/shared/toolchain.test.ts` fails when one of them drifts from the others (CodeQL's Python is the one named exception). See [`release-desktop.yml`](../.github/workflows/release-desktop.yml) for the desktop build matrix and [`web-ci.yml`](../.github/workflows/web-ci.yml) for the web checks. The site itself is deployed by Cloudflare Workers Builds on a push to `main` — see [`DEPLOYMENT.md`](DEPLOYMENT.md). Why TypeScript is two packages, and how to move each runtime next time: [`plan/16-toolchain-2026.md`](plan/16-toolchain-2026.md); the switch to TypeScript 7 alone, planned for 7.1: [`plan/17-typescript-7.1.md`](plan/17-typescript-7.1.md).
## Dev workflow
### Web app
```bash
cd web
npm ci # one-time install
npm run dev # http://localhost:5173 (Vite)
npm run dev:admin # http://localhost:5174/admin, the admin app on a local mock backend
npm run typecheck # strict TS: app, admin, Worker, tests
npm test # vitest
npm run build # site into web/dist, admin into the Worker bundle
node scripts/verify-dist.mjs --web
```
`typecheck`, `test` and `build` must all pass before opening a PR; `web-ci.yml` runs the same, plus a Tauri-flavour build.
### Tauri desktop
```bash
cd web
npm run tauri dev # dev build with hot reload, Rust + WebKit
npm run tauri build # release binary into web/src-tauri/target/release/bundle
```
Platform prerequisites + signing notes live in [`../web/src-tauri/TAURI.md`](../web/src-tauri/TAURI.md).
### Python pipeline
From the repo root: the scripts read and write `data/` by a relative path.
```bash
python -m pip install --require-hashes --only-binary :all: -r requirements.txt
python -m pip install --require-hashes --only-binary :all: -r requirements-test.txt # pytest
python scripts/ingest_new.py # process scripts/temp_info.jsonl
python scripts/update_data.py # daily full refresh
python scripts/top_online.py # rebuild games/top-online.md
```
`requirements.txt` pins every package with its hashes, so pip refuses anything else; install the unhashed `requirements-dev.txt` (vulture, pip-audit) in a separate call. `python -m pytest scripts/tests` covers the pipeline's contracts; `python-tests.yml` runs it on every change under `scripts/` or to the requirements files. Lint with `ruff` if you have it; otherwise rely on review.
### Git + GPG
- **Always** sign commits: `git config --local commit.gpgsign true`.
- Each commit lands as **Verified ✓** on GitHub when the GPG key is unlocked.
- The web app no longer commits anything. Commits made from `/admin` are created by a GitHub App through `createCommitOnBranch`, which GitHub signs itself — see [`ADMIN.md`](ADMIN.md).
## Branch + PR flow
Per the maintainer's working style:
1. Cut a feature branch from `main`.
2. Implement + run `npm run typecheck && npm run build` (web) or `python scripts/<task>.py` (pipeline).
3. Squash-commit with a short, scoped message.
4. Push, open PR, squash-merge to `main` once green.
Larger features (multi-task batches like the v3.x release cycle) are landed in phase-PRs that group related work to keep history scannable.
## Related
- [`pc_spec.md`](pc_spec.md) — hardware spec
- [`../web/src-tauri/TAURI.md`](../web/src-tauri/TAURI.md) — Tauri 2 desktop build prerequisites
- [`../CONTRIBUTING.md`](../CONTRIBUTING.md) — contribution paths (issue / discussion / fork)
- [`../web/README.md`](../web/README.md) — web stack, data paths, CSP, PWA, i18n, build + checks