57 lines
2.0 KiB
Markdown
57 lines
2.0 KiB
Markdown
# 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.
|