38 lines
2.8 KiB
Markdown
38 lines
2.8 KiB
Markdown
# Repository Guidelines
|
||
|
||
## Project Structure & Module Organization
|
||
- `lib/main.dart` is the single entry point; group new features in subfolders under `lib/` (e.g., `timer/`, `settings/`) with `widgets/`, `services/`, and `models/` as needed.
|
||
- Tests live in `test/` (default `widget_test.dart`); mirror `lib/` paths (`lib/timer/controller.dart` → `test/timer/controller_test.dart`).
|
||
- Assets such as backgrounds reside in `assets/` and are declared in `pubspec.yaml`; keep new images in the same folder and register them there.
|
||
- Platform folders (`android/`, `ios/`, `macos/`, `windows/`, `linux/`, `web/`) hold generated build config—modify only when working on platform-specific code or permissions.
|
||
|
||
## Build, Test, and Development Commands
|
||
- `flutter pub get` – install/update dependencies.
|
||
- `flutter analyze` – static analysis using `flutter_lints`; run before commits.
|
||
- `dart format .` – format codebase (uses 2-space indent).
|
||
- `flutter test` – run all unit/widget tests; add `--coverage` to check coverage.
|
||
- `flutter run -d <device>` – launch locally on a simulator/emulator or browser.
|
||
- `flutter build apk --release` or `flutter build web --release` – produce release artifacts for mobile or web.
|
||
|
||
## Coding Style & Naming Conventions
|
||
- Follow `analysis_options.yaml` (`flutter_lints`); prefer clean imports and avoid unused code.
|
||
- Use snake_case for files, PascalCase for types, camelCase for variables/methods, and ALL_CAPS for consts.
|
||
- Keep widgets small and composable; separate stateful logic from rendering.
|
||
- Document non-obvious logic with comments; avoid print debugging in committed code.
|
||
|
||
## Testing Guidelines
|
||
- Use `flutter_test` for units and widgets; name files `*_test.dart` and describe behavior in test names (`'starts countdown on tap'`).
|
||
- Cover new logic paths and UI states (loading/error/success); add visuals only when needed.
|
||
- Run `flutter test` locally before opening a PR; ensure assets or permissions used in tests are mocked (e.g., geolocator calls).
|
||
|
||
## Commit & Pull Request Guidelines
|
||
- If using Git, follow Conventional Commits (`feat: add timer presets`, `fix: handle geolocator errors`).
|
||
- Scope commits narrowly; keep diffs focused on one concern.
|
||
- PRs should include: summary of changes, linked issues/tasks, screenshots or screen recordings for UI updates, and a checklist of commands run (`flutter analyze`, `flutter test`).
|
||
- Flag platform-specific changes (Android/iOS/Web) and note any permission/config edits in `pubspec.yaml` or platform manifests.
|
||
|
||
## Security & Configuration Tips
|
||
- Do not commit API keys or secrets; prefer runtime configuration or platform-specific secure stores.
|
||
- Keep asset paths synced with `pubspec.yaml` to avoid runtime load failures.
|
||
- When adding location-dependent features (geolocator), document permission prompts and testing steps per platform.
|