# Contributing to Open SafetyLog EHS

Thanks for helping make workplace safety software free for everyone. Contributions of all kinds are welcome: bug reports, feature ideas, documentation, design, translations and code.

Everyone taking part is expected to follow our [Code of Conduct](CODE_OF_CONDUCT.md).

## Ways to contribute

- **Report a bug.** Open an issue with steps to reproduce, what you expected, what happened, and your browser and device.
- **Suggest a feature.** Open an issue describing the safety problem you're trying to solve, not only the solution. Real-world context from plants and safety teams is especially valuable.
- **Pick up work.** Check the [roadmap](docs/ROADMAP.md) and [to-do list](docs/TODO.md). Comment on an issue before starting anything large so we can agree on the approach.

## Development setup

Requires Node.js 22.18 or later (see `.nvmrc`). No database install needed: development uses embedded PostgreSQL in `./data/`.

```sh
npm install
npx playwright install chromium   # once, for end-to-end tests
npm run db:seed                   # optional demo data
npm run dev                       # web app :5173, API :3000
```

Before opening a pull request, run:

```sh
npm run check      # lint, typecheck, unit tests, build
npm run test:e2e   # end-to-end tests on desktop and mobile
```

CI runs the same checks on every pull request.

## Code guidelines

- **TypeScript** everywhere; avoid `any`.
- **Structure:** routes go in `src/pages/`, reusable UI in `src/components/`, and types and domain logic in `src/lib/` (no React components there). API routes go in `server/routes/`, one file per resource. Enums and request schemas used by both sides live in `shared/`.
- **Server code runs without a build step** (Node strips the types), so use only erasable TypeScript: no `enum`, `namespace` or constructor parameter properties, and include the `.ts` extension in relative imports. `npm run typecheck` enforces this.
- **Database changes:** edit `server/db/schema.ts`, then run `npm run db:generate` and commit the generated migration. Migrations run automatically when the server starts.
- **Permissions:** every API route must check the signed-in user's role and organization. Add a test showing a lower role is refused.
- **Styling:** Tailwind CSS. Use the theme tokens in `src/index.css` (`text-ink`, `bg-coral`, `border-line`, …) rather than new hex values; add a token if a color is reused.
- **Tests:** put domain logic in `src/lib/` with a unit test next to it (`*.test.ts`). Cover user-facing flows with a component test or a Playwright test in `e2e/`.
- **Translations:** user-facing text on worker screens lives in `src/i18n/en.ts` with the Spanish in `src/i18n/es.ts`. TypeScript and a test fail if a Spanish entry is missing, so add both together. If you can't translate, open the pull request anyway and ask for help.
- **Accessibility:** every form control needs a label, and every icon-only button needs an `aria-label`. Shop-floor users may be on gloves-on touchscreens, so keep touch targets generous.
- **Safety data:** incident and injury records can contain medical and personal information. Never log them, and never add third-party scripts, fonts or analytics that would send data off the server.

## Commits and pull requests

- Branch from `main` and keep each pull request focused on one change.
- Use [Conventional Commits](https://www.conventionalcommits.org/) messages, e.g. `feat: add QR code location labels` or `fix: keep filter when returning to list`.
- Describe what changed and why, link related issues, and add screenshots for UI changes (desktop and mobile).
- Update `docs/ROADMAP.md` or `docs/TODO.md` if your change completes or adds an item.

## License

Open SafetyLog EHS is licensed under the [GNU Affero General Public License v3.0](LICENSE). By submitting a contribution, you agree that it is licensed under the same terms.