open-safetylog-ehs/CONTRIBUTING.md

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.

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 and to-do list. 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/.

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:

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 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. By submitting a contribution, you agree that it is licensed under the same terms.