jayjennings
c69eccb5c1
- Add incident reporting routes and logic to handle creation, updating, and retrieval of incidents. - Implement visibility rules for users based on roles (reporters, supervisors). - Create tests for incident reporting functionality to ensure correctness and reliability. - Introduce site and area management routes, including validation for area hierarchy. - Establish user management routes with role-based access control for creating and updating users. - Add setup routes for initializing the application with an organization and admin user. - Implement shared enums and schemas for consistent validation and data handling across the application. - Create a test helper for setting up an in-memory database and API client for testing. - Add TypeScript configuration for server-side code with strict type checking and module resolution.
55 lines
3.6 KiB
Markdown
55 lines
3.6 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/`.
|
|
- **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.
|