|
| 1 | +# Repository Guidelines |
| 2 | + |
| 3 | +## Dos and Don'ts |
| 4 | +- Do install dependencies with `yarn` (classic Yarn v1) after checkout so postinstall scripts set up Electron and Husky hooks correctly. |
| 5 | +- Do run targeted Jest suites first, e.g. `yarn test app/lib/__tests__/loadThemes.spec.js`, before running the full suite. |
| 6 | +- Do follow the existing two-space indentation and no-semicolon style when editing JavaScript/TypeScript files. |
| 7 | +- Do reference existing Webpack aliases (e.g. `main/...`, `lib/...`, `plugins/...`) instead of rewriting import paths. |
| 8 | +- Don't switch package managers or bump Node/Electron versions without coordinating updates to `package.json`, `electron-builder.json`, and CI workflows. |
| 9 | +- Don't mass-reformat files or reorganize modules; keep diffs minimal and scoped to the task at hand. |
| 10 | + |
| 11 | +## Project Structure and Module Organization |
| 12 | +- Electron app with React renderer lives under `app/`; `app/main` is the primary renderer UI, `app/background` handles background tasks, and `app/lib` hosts shared utilities. |
| 13 | +- Core and external plugin logic resides in `app/plugins`; `app/plugins/core` contains built-in plugins and supporting helpers. |
| 14 | +- Webpack, Babel, Jest, and TypeScript configs are defined at the repo root (`webpack.config.*.js`, `babel.config.js`, `jest.config.js`, `tsconfig.json`). |
| 15 | +- Release assets, icons, and installer scripts live in `build/`; Electron Builder configuration is in `electron-builder.json`. |
| 16 | +- Continuous Integration workflows that run tests and releases are under `.github/workflows/` (`pr.yml`, `build.yml`). |
| 17 | +- Top-level entry points include `server.js` (hot-reload dev server) and `app/main.development.js` (Electron main process during development). |
| 18 | + |
| 19 | +## Build, Test, and Development Commands |
| 20 | +- Install dependencies with `yarn`; this also runs `electron-builder install-app-deps` and enables Husky commit hooks. |
| 21 | +- Launch the hot-reload development loop with `yarn dev` (spawns the Webpack hot server and a development Electron window). |
| 22 | +- For production smoke tests run `yarn build` first (emits `app/main.js` and `app/dist` bundles), then launch Electron with `yarn start`. |
| 23 | +- Build artifacts with `yarn build` (renders both main and renderer bundles) or package distributables with `yarn package` / `yarn release` as defined in `package.json`. |
| 24 | +- Run focused Jest suites via `yarn test <path-or-pattern>`; for example `yarn test app/main/actions/__tests__/search.spec.js` exercises action creators. The default `yarn test` executes all suites with coverage (`collectCoverage: true`). |
| 25 | +- Linting uses ESLint with the Airbnb base: `yarn lint` runs against `app/background app/lib app/main app/plugins *.js`. Keep new code compliant and retain the inline suppressions where we forward plugin props (ResultsList rows, FormItem form controls). |
| 26 | + |
| 27 | +## Coding Style and Naming Conventions |
| 28 | +- `.editorconfig` enforces spaces (size 2) for JavaScript/TypeScript and tabs elsewhere; trim trailing whitespace except in Markdown. |
| 29 | +- ESLint (Airbnb rules) is the baseline; notable overrides include `semi: ['error', 'never']`, disabled dangling commas, and relaxed import extension checks. Maintain single quotes. Do not add new trailing commas; you may leave existing trailing commas in legacy code unchanged. |
| 30 | +- Shared modules rely on Webpack/TypeScript path resolution (`app` treated as the module root). Preserve aliases like `import config from 'lib/config'` and directory `index.(js|ts)` entrypoints. |
| 31 | +- React components primarily live in `app/main/components`, with styles handled via CSS modules (`*.module.css`). Follow existing patterns for component structure and CSS naming. |
| 32 | +- Comments are short English line comments (`//`) or block comments where clarification is required; prefer matching the current files' commenting style. |
| 33 | + |
| 34 | +## Testing Guidelines |
| 35 | +- Jest is configured via `jest.config.js` with coverage enabled and a custom module mapper for static assets and CSS; tests live alongside source in `__tests__` directories and `*.spec.js` files. |
| 36 | +- Use `yarn test <file>` for scoped runs while iterating, then run `yarn test` before submitting to ensure coverage numbers stay intact. |
| 37 | +- When adding UI logic, favor lightweight Jest tests around reducers, actions, or utilities; UI components typically rely on snapshot-free, behavior-focused tests. |
| 38 | +- Tests rely on the Electron renderer environment; include `@jest-environment jsdom` when DOM APIs are needed, mirroring existing suites. |
| 39 | + |
| 40 | +## Commit and Pull Request Guidelines |
| 41 | +- Conventional Commits are enforced by Husky + Commitlint (`.commitlintrc.json` extends `@commitlint/config-conventional`). Keep subjects imperative and under 50 characters when possible. |
| 42 | +- Use `yarn commit` (Commitizen) if you need help crafting compliant messages; otherwise ensure manual commits follow the same format (`feat:`, `fix:`, `chore:` etc.). |
| 43 | +- Keep pull requests focused and ensure `yarn test <scope>` passes locally before pushing; CI (`.github/workflows/pr.yml`) re-runs `yarn` and `yarn test --detectOpenHandles --forceExit` on Ubuntu. |
| 44 | +- Link related issues in PR descriptions and include screenshots/gifs when UI behavior changes, matching past contributions in the history. |
| 45 | + |
| 46 | +## Safety and Permissions |
| 47 | +- Ask before adding dependencies, modifying build/CI configuration, or deleting/renaming files that affect Electron packaging or plugin contracts. |
| 48 | +- Reading files, inspecting configs, and running scoped tests (`yarn test <file>`) or targeted builds (`yarn build-main`) are safe by default. |
| 49 | +- Avoid destructive git operations, manual cleanups in `release/`, or editing generated bundles under `app/dist`; regenerate via the provided scripts instead. |
| 50 | +- Do not store secrets or environment credentials in the repo; follow `.env.example` when local overrides are required. |
0 commit comments