From 01cef6756d0affd23e610f0e59269703d83e09b8 Mon Sep 17 00:00:00 2001 From: AUDO Date: Fri, 7 Aug 2026 00:14:23 +0800 Subject: [PATCH 1/3] ci: run lint, tests, and production build on PRs and main MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Closes #4. Label sync was the only workflow, so renderer and Electron regressions could land with no automated signal. - Node 22 (Vite 7 needs ^20.19.0 || >=22.12.0), npm cache keyed on avatar/package-lock.json. - Runs `npm test` as well as lint and build: the 26 Electron unit tests existed but nothing ever ran them. - Skips the Electron binary download — the tested modules deliberately avoid require('electron'), so ~100 MB is dead weight here. - No dist:win: Windows-specific and slow, deferred as the issue suggests. Co-Authored-By: Claude Opus 5 --- .github/workflows/ci.yml | 48 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 48 insertions(+) create mode 100644 .github/workflows/ci.yml diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml new file mode 100644 index 0000000..e9169f9 --- /dev/null +++ b/.github/workflows/ci.yml @@ -0,0 +1,48 @@ +name: CI + +on: + pull_request: + push: + branches: [main] + +permissions: + contents: read + +concurrency: + group: ci-${{ github.workflow }}-${{ github.ref }} + cancel-in-progress: true + +jobs: + check: + name: Lint, test, build + runs-on: ubuntu-latest + defaults: + run: + working-directory: avatar + env: + # Nothing here launches Electron: the unit-tested modules deliberately + # avoid require('electron'), so the ~100 MB binary is dead weight. + ELECTRON_SKIP_BINARY_DOWNLOAD: 1 + steps: + - name: Checkout + uses: actions/checkout@v4 + + - name: Set up Node + uses: actions/setup-node@v4 + with: + # Vite 7 needs ^20.19.0 || >=22.12.0. + node-version: 22 + cache: npm + cache-dependency-path: avatar/package-lock.json + + - name: Install + run: npm ci + + - name: Lint + run: npm run lint + + - name: Test + run: npm test + + - name: Build + run: npm run build From 997882c361582372055a7ba0194da3b08b70e507 Mon Sep 17 00:00:00 2001 From: AUDO Date: Fri, 7 Aug 2026 10:43:00 +0800 Subject: [PATCH 2/3] ci: bump checkout and setup-node to v5 v4 declares the node20 runtime, which GitHub now force-runs on Node 24 and warns about on every run. v5 declares node24 natively. No input changes: node-version, cache, and cache-dependency-path are unchanged between v4 and v5. Co-Authored-By: Claude Opus 5 --- .github/workflows/ci.yml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index e9169f9..5cec3d8 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -25,10 +25,10 @@ jobs: ELECTRON_SKIP_BINARY_DOWNLOAD: 1 steps: - name: Checkout - uses: actions/checkout@v4 + uses: actions/checkout@v5 - name: Set up Node - uses: actions/setup-node@v4 + uses: actions/setup-node@v5 with: # Vite 7 needs ^20.19.0 || >=22.12.0. node-version: 22 From 149f73ea1e558e94fb7679b96df7d73b5e848867 Mon Sep 17 00:00:00 2001 From: rosspeili Date: Fri, 7 Aug 2026 13:54:41 +0300 Subject: [PATCH 3/3] docs: changelog, CI badge, and CONTRIBUTING ripples for lint + CI (#34, #35) Record Unreleased notes for ESLint coverage and GitHub Actions CI, add the README CI badge, mark roadmap CI done, document the workflow in project layout, and expand CONTRIBUTING for changelog style, CI gates, and human/AI ripple-effect guidance. --- CHANGELOG.md | 12 +++++++++ CONTRIBUTING.md | 40 +++++++++++++++++++++++++----- README.md | 1 + docs/development/project-layout.md | 8 ++++-- docs/development/roadmap.md | 3 ++- 5 files changed, 55 insertions(+), 9 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index cd450c0..3b4b733 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,10 +6,22 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). ## [Unreleased] +### Added + +- GitHub Actions CI on pull requests and `main`: `npm ci` → `lint` → `test` → `build` in `avatar/` (Node 22; Electron binary download skipped). See [Contributing](CONTRIBUTING.md#continuous-integration) and [Project layout](docs/development/project-layout.md). (#4, #35) +- README CI status badge. + ### Changed - Rename the app package directory from `avatar-demo/` to `avatar/`. Contributor paths (`cd avatar`, docs, `.gitignore`) updated; the Windows installer is unchanged. - Docs and README: add desktop companion GIFs (`AVATAR_M5_*`) for overlay, Settings scroll, animations, custom environments, and Camera & Lighting. +- ESLint covers `src/`, `electron/**/*.cjs`, and build scripts (`scripts/`, config files); `npm run lint` enforces `--max-warnings=0`. (#34) +- Expand [Contributing](CONTRIBUTING.md) for ripple effects, changelog style with issue/PR numbers, CI expectations, and guidance for human and AI contributors. + +### Fixed + +- Capture the Three.js group once in `VrmAvatar` so effect cleanup detaches from the same container the model was attached to (avoids orphan scenes on avatar swap). (#34) +- Drop unused `audioFile` prop from `VoicePanel` (file input is uncontrolled). (#34) ## [0.5.0] — 2026-08-06 diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 8b432fe..a95f660 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -31,10 +31,13 @@ npm install | Production-like Electron on `dist/` | `npm run desktop` | | Browser only | `npm run dev` → http://localhost:5173 | | Lint | `npm run lint` | +| Unit tests (Electron modules) | `npm test` | | Vite production build | `npm run build` | | Windows installer (local output under `desktop-setup/`) | `npm run dist:win` | | Regenerate bundled avatar thumbnails | `npm run thumbs` | +Pull requests and pushes to `main` run the same **lint → test → build** sequence in GitHub Actions (see [Continuous integration](#continuous-integration)). Run those three locally before opening a PR. + End users can use [AVATAR-Setup-0.5.0.exe](https://github.com/ARPAHLS/avatar/releases/download/v0.5.0/AVATAR-Setup-0.5.0.exe) without Node. ### Bundled avatar thumbnails @@ -78,20 +81,33 @@ AVATAR is small but cross-cutting. When you change behavior, ask what else must | Installer / packaging | [Installation](docs/getting-started/installation.md), [releases](docs/releases/README.md) if user-facing, `avatar/build/` assets, `package.json` `build` field | | Public API of preload / IPC | Every `window.voxDesktop` (or equivalent) caller; keep `preload.cjs` and `main.cjs` in sync | | Labels or issue forms | [`.github/labels.yml`](.github/labels.yml) (CI syncs labels) — do not invent one-off label names in templates | +| Lint / ESLint scope | `avatar/eslint.config.js` (renderer `src/`, Electron `electron/**/*.cjs`, scripts) — keep Node vs browser globals correct | +| CI workflow | [`.github/workflows/ci.yml`](.github/workflows/ci.yml), [Project layout](docs/development/project-layout.md#continuous-integration), README CI badge if the workflow name/path changes | +| Package scripts / Node engines | `avatar/package.json`, install docs if contributors must change Node version | +| Roadmap item shipped | [Roadmap](docs/development/roadmap.md) checkboxes | ### Docs, changelog, and README -For **user-visible** changes: +For **user-visible** or **contributor-visible** changes (behavior, install, CI, lint gates): -1. **`CHANGELOG.md`** — add a bullet under `[Unreleased]` (`Added` / `Changed` / `Fixed` / `Removed`). Keep it short; say *why it matters*, not every file touched. +1. **`CHANGELOG.md`** — add a bullet under `[Unreleased]` (`Added` / `Changed` / `Fixed` / `Removed`). Keep it short; say *why it matters*, not every file touched. Prefer **issue and PR numbers** when known, matching the style under published releases (e.g. `(#4, #35)`). Do not use `Closes`/`Fixes` keywords inside changelog text. 2. **Feature docs** — update the guide that describes the behavior (see table above). Do not leave docs describing the old path. 3. **`docs/using-the-app.md`** — update if menus, defaults, or the main walkthrough change. 4. **`README.md`** — only if Quick start, install order, badges/links, or high-level “what this is” change. Keep README lite; deep detail stays in `docs/`. 5. **Screenshots** — replace or add under `docs/screenshots/` when the UI in docs would mislead; keep filenames stable when replacing in place. 6. **`CITATION.cff` / release notes** — only when versioning or release messaging changes (maintainers). +7. **`docs/development/roadmap.md`** — mark shipped items when a tracked milestone lands. Docs-only PRs still need a clear description; changelog entry optional unless the doc fix is user-facing correction of wrong instructions. +### Continuous integration + +- Workflow: [`.github/workflows/ci.yml`](.github/workflows/ci.yml) on every pull request and on pushes to `main`. +- Steps (in `avatar/`): `npm ci` → `npm run lint` → `npm test` → `npm run build`. +- Node **22** (Vite 7 compatible). Electron’s binary is **not** downloaded in CI (`ELECTRON_SKIP_BINARY_DOWNLOAD`); unit tests must not `require('electron')` at load time. +- Windows installer (`dist:win`) is **not** run in CI — too heavy and Windows-specific; verify locally when you touch packaging. +- A failing CI check blocks confidence for merge; fix lint/tests/build in the same PR when you introduce the breakage. + ### Desktop vs browser parity - If a feature is **Electron-only**, say so in UI copy and docs; do not silently no-op in a confusing way when possible. @@ -105,6 +121,18 @@ Docs-only PRs still need a clear description; changelog entry optional unless th - Desktop: `electron/settingsStore.cjs` → `config.yaml` in userData. - Changing keys or defaults can break existing user configs — prefer migrations or tolerant reads; document resets in [User settings](docs/user-settings.md). +### For AI coding agents (and humans using them) + +Treat the repo as a **product + docs** unit, not a single-folder code patch: + +1. **Read before editing** — [Using the app](docs/using-the-app.md), the feature doc for the area, and this ripple table. +2. **Electron vs browser** — do not claim desktop-only behavior works in `npm run dev` without checking. +3. **Complementary files in the same PR** — code + catalogs + preload/main + docs + `CHANGELOG.md` `[Unreleased]` + screenshots when the UI story changes. Avoid “follow-up later” for obvious ripples (changelog, user guide line, roadmap checkbox). +4. **Changelog** — Keep a Changelog sections; short *why*; include `#issue` / `#PR` when known (see [0.5.0](CHANGELOG.md) entries). +5. **Do not commit** secrets, `desktop-setup/*.exe`, or gitignored `custom/` media. +6. **Verify** — `npm run lint`, `npm test`, and `npm run build` in `avatar/` (same as CI). Use `dev:desktop` for overlay/audio smoke tests. +7. **PR description** — what / why / how tested / leftover follow-ups that are genuinely optional. + --- ## Assets and licensing @@ -120,14 +148,14 @@ Docs-only PRs still need a clear description; changelog entry optional unless th Before you open a PR: -- [ ] `npm run lint` and `npm run build` pass in `avatar/` +- [ ] `npm run lint`, `npm test`, and `npm run build` pass in `avatar/` - [ ] Smoke-tested the path you changed (`dev:desktop` and/or `dev` as appropriate) - [ ] Catalogs / config updated if you added assets or options - [ ] Electron preload ↔ main IPC still aligned (if you touched desktop APIs) -- [ ] `CHANGELOG.md` `[Unreleased]` updated for user-visible changes -- [ ] Relevant docs (and screenshots if needed) updated +- [ ] `CHANGELOG.md` `[Unreleased]` updated for user- or contributor-visible changes (with issue/PR numbers when known) +- [ ] Relevant docs (and screenshots if needed) updated; roadmap touched if a listed item shipped - [ ] No secrets, local `custom/` media, or `desktop-setup/` installer binaries committed -- [ ] PR description states **what** changed, **why**, and any **follow-ups** +- [ ] PR description states **what** changed, **why**, how you **tested**, and any **follow-ups** --- diff --git a/README.md b/README.md index 0d9691b..2c1534e 100644 --- a/README.md +++ b/README.md @@ -10,6 +10,7 @@
Version 0.5.0 + CI License MIT BOOTH VRM VRoid Hub diff --git a/docs/development/project-layout.md b/docs/development/project-layout.md index bdc9238..c3b9ddb 100644 --- a/docs/development/project-layout.md +++ b/docs/development/project-layout.md @@ -42,8 +42,12 @@ End users personalize via **Settings → Directories** and **VRoid Hub** (see [U | `npm run dev:desktop` | Contributors | Vite + Electron (hot reload) | | `npm run dist:win` | Contributors | Build Windows NSIS installer (local `desktop-setup/` output) | | `npm run build` | CI / web | Production Vite bundle | -| `npm run lint` | Contributors | ESLint | -| `npm test` | Contributors | Electron unit tests | +| `npm run lint` | Contributors / CI | ESLint (`src/`, `electron/**/*.cjs`, scripts; `--max-warnings=0`) | +| `npm test` | Contributors / CI | Electron unit tests (`electron/*.test.cjs`) | | `npm run thumbs` | Contributors | Re-render committed avatar portraits into `src/assets/avatars/thumbs/` | +### Continuous integration + +Pull requests and pushes to `main` run [`.github/workflows/ci.yml`](../../.github/workflows/ci.yml): install → lint → test → production build in `avatar/` on Ubuntu (Node 22). The workflow does **not** build the Windows installer (`dist:win`) and skips downloading the Electron binary (`ELECTRON_SKIP_BINARY_DOWNLOAD`) because unit tests do not launch Electron. Label sync remains a separate workflow (`.github/workflows/sync-labels.yml`). + Run `npm run thumbs` whenever a bundled `.vrm` or the `config/avatars.js` catalog changes, and commit the PNGs — the Appearance picker reads those files rather than rendering a live preview. Custom-folder avatars are cached at runtime under Electron `userData/thumbnails/` instead. See [Contributing](../../CONTRIBUTING.md#bundled-avatar-thumbnails). diff --git a/docs/development/roadmap.md b/docs/development/roadmap.md index 8268c89..cdc97ab 100644 --- a/docs/development/roadmap.md +++ b/docs/development/roadmap.md @@ -41,7 +41,8 @@ - [ ] Avatar thumbnail follow-ups (pre-warm, sidecars, cache prune) (#21) - [ ] Environments picker flicker / GIF size (#22) - [ ] Code-signed Windows installer -- [ ] Broader CI (lint / build) +- [x] Broader CI (lint / test / build) (#4, #34, #35) - [ ] Asset license audit and manifest - [ ] Security review for capture permissions copy - [ ] Harden VRoid Hub VRM download for restrictive networks / CDN paths +- [ ] Docs visual overhaul (reshoot screenshots / GIFs, layout rules)