jayjennings
3e964d1176
feat(kiosk): implement kiosk report submission functionality with offline support test(outbox): add tests for outbox functionality including report submission and error handling feat(outbox): create outbox management for queued reports with IndexedDB persistence feat(uuid): add UUID generation utility for client IDs feat(qr): implement QR code generation for reporting links by site and area feat(kiosk): create Kiosk page for reporting incidents without an account
56 lines
3.8 KiB
Markdown
56 lines
3.8 KiB
Markdown
# 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.
|