Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
95 lines (71 loc) · 3.73 KB

CONTRIBUTING.md

File metadata and controls

95 lines (71 loc) · 3.73 KB
Raw

Contributing to ReqSolve

Thanks for your interest in improving ReqSolve! These rules keep the project consistent and safe for everyone who runs it. PRs that don't follow them will be asked to change before merge.

License of contributions

ReqSolve is licensed under the Business Source License 1.1 (see LICENSE). By submitting a contribution (code, documentation, translations, or other material) you agree that it is provided under the project license and may be distributed as part of the Licensed Work under its terms, including the future change to the Apache License 2.0 on the Change Date.

Non-negotiables

1. Department isolation & security must be preserved

ReqSolve's core security promise is that departments are isolated: agents, tickets, knowledge, requesters, audit entries and AI context are scoped to the teams a user belongs to, and that boundary is enforced server-side (never only in the UI). Any change that touches data access must keep this intact:

  • New queries and API routes must apply the same department scoping as the code around them (see the existing scope helpers in lib/).
  • Anything sent to an AI provider must be pre-scoped to the ticket's department; never widen the candidate set.
  • Secrets (API keys, mail passwords, OAuth tokens) are stored encrypted at rest via ENCRYPTION_KEY and are never returned to the client. Keep it that way.
  • Treat ticket/requester text as untrusted data everywhere — in SQL (use the ORM), in HTML (no raw rendering), and in AI prompts (data, not instructions).

If your change could weaken any of the above, say so explicitly in the PR description so it gets a careful review.

2. Every user-facing string ships in English AND German

The UI is internationalized with next-intl. Never hardcode UI text in components:

  • Add new strings to both messages/en.json and messages/de.json, using the existing namespaces. Key sets must stay identical in both files.
  • German register: formal "Sie", professional helpdesk/IT terminology. Don't translate product/brand names or technical identifiers.

3. Documentation travels with the code

If you change what a user or admin sees or does, update the help center under docs/ in the same PR:

  • Configuration / admin changes → docs/admin/*
  • Agent and end-user behavior (tickets, knowledge base, email, AI assist, account, web form) → docs/using/*
  • New feature with no existing page → add a page and wire it into the sidebar in docs/.vitepress/config.mts
  • Removed/deprecated feature → remove or adjust the matching page
  • The docs are bilingual: keep the German counterpart under docs/de/ (and the German sidebar) in sync.

Purely internal changes with no user-visible effect (refactors, tests, CI, tooling) are exempt. When in doubt, update the docs.

4. All checks must pass

Run the same checks CI enforces (.github/workflows/ci.yml) before you push:

npm run lint
npx tsc --noEmit
npm run build
npm run docs:build
npm test

If you add or change logic that can be unit-tested, add a matching *.test.ts under lib/ — npm test picks it up automatically.

Preview the docs locally with npm run docs:dev → http://localhost:5173/documentation/

Branching & PRs

  • main is the single source of truth and the default branch; it must always build (app and docs) and stay green in CI.
  • Develop feature work on a dedicated branch and open a PR against main.
  • Keep PRs focused: one feature or fix per PR, with a description of what changed and why.

Reporting security issues

Please do not open a public issue for a vulnerability. Report it privately to the maintainer (see the repository's security/contact settings) so it can be fixed before disclosure.