Add comprehensive documentation set

2025-12-02 08:49:56 +10:00
parent 6917d944fe
commit 64b8a24920
4 changed files with 237 additions and 2 deletions
@@ -0,0 +1,56 @@
+# Contributing
+
+Thank you for helping improve StockFill! This guide explains how to set up a local environment, follow the coding conventions, and
+submit changes.
+
+## Ground rules
+
+- StockFill is an offline-first PWA. Avoid adding remote API calls or backend dependencies.
+- Dexie is the source of truth for persisted data. Schema updates must be applied via Dexie migrations to avoid data loss.
+- Use TypeScript with strict mode and prefer named exports for new modules.
+- Keep components and hooks small and focused; avoid files exceeding a few hundred lines where possible.
+- Follow the existing mobile-first UX patterns and preserve accessibility cues.
+
+## Prerequisites
+
+- Node.js 20+ and npm
+- Optional: Docker for containerized builds and previews
+- Optional: Playwright browsers for running `npm run test:e2e` (`npx playwright install`)
+
+## Setup
+
+1. Install dependencies:
+   ```bash
+   npm install
+   ```
+2. Start the dev server:
+   ```bash
+   npm run dev
+   ```
+3. Open the printed URL in your browser or mobile emulator.
+
+## Development workflow
+
+- Create small, focused branches for each feature or fix.
+- Keep PWA assets up to date when changing files in `src/pwa/`; the build step copies them into `public/`.
+- Ensure offline behavior remains intact by exercising flows without network connectivity when possible.
+
+## Testing and quality
+
+Run these commands before submitting a pull request:
+
+- Lint: `npm run lint`
+- Unit/component tests: `npm test`
+- Coverage (enforced at 80%+ for statements/branches/functions/lines): `npm run test:coverage`
+- End-to-end tests (optional, requires browsers): `npm run test:e2e`
+
+## Commit and PR guidelines
+
+- Write clear commit messages that describe the change.
+- Provide context in pull request descriptions: what changed, why, and how it was tested.
+- Avoid introducing breaking schema changes without a migration plan.
+
+## Reporting bugs
+
+- Include reproduction steps, expected vs. actual behavior, and environment details (browser, OS, device type).
+- Attach screenshots for UI regressions when possible.