Contribution guide

Welcome

Whether you are fixing a typo, reporting a bug, or implementing a new module feature, thank you. Contributions are accepted under the project’s MIT License.

Contribution pathways

Code of conduct

We expect every interaction—issues, PRs, discussions, and reviews—to follow these norms:

• Be respectful. Critique ideas and code, never people.
• Be inclusive. Welcome contributors of all backgrounds and experience levels.
• Be collaborative. Assume good intent, ask clarifying questions, and document decisions.
• Be responsible. Do not share secrets, customer data, or exploit details that could harm users.
• No harassment or discrimination of any kind. Maintainers may moderate or block abusive behavior.

Report conduct concerns privately to the repository maintainers via GitHub when possible. Serious violations may result in contribution privileges being revoked.

Local development environment

1. Fork the repository on GitHub, then clone your fork:

   git clone https://github.com/<your-username>/nats.git
   cd nats
   git remote add upstream https://github.com/maziyank/nats.git

2. Install toolchain — Node.js 20+, PostgreSQL 15+, Git.
3. Install packages & env

   npm install
   cp .env.example .env
   # edit DATABASE_URL and SESSION_SECRET

4. Prepare database

   npx prisma generate
   npx prisma migrate dev
   npm run prisma:seed:minimal

5. Start dev server

   npm run dev

Full operational details live in the setup & usage guide.

Fork, branch, and pull request workflow

Branching

• Create a topic branch from an up-to-date main (or the repository default branch).
• Use descriptive names: fix/pos-session-department, docs/pages-performance, feat/inventory-export.

git fetch upstream
git checkout main
git merge upstream/main
git checkout -b fix/short-description

Commits

• Keep commits focused and reviewable.
• Write clear messages that explain why, not only what.
• Do not commit secrets, local env files, or large unrelated binaries.

Open a pull request

1. Push your branch to your fork.
2. Open a PR against the upstream default branch.
3. Fill in a summary, linked issues, test plan, and screenshots for UI changes.
4. Ensure CI (lint/tests) is green when available.
5. Respond to review feedback promptly; force-push rebased topic branches only when needed for cleanliness.

Coding standards

• Language: TypeScript for application code; keep types honest and avoid any unless justified.
• Style: Follow existing ESLint configuration (npm run lint). Prefer project patterns over personal style.
• Architecture: Keep domain logic in services/modules; keep server actions thin; reuse validation schemas.
• UI: Use existing components under components/ui and layout primitives before inventing new ones.
• i18n: User-facing strings should go through message catalogs (messages/en.json, messages/id.json). Run npm run i18n:validate when adding keys.
• Permissions: New privileged operations must use the permission registry / protected action helpers.
• Database: Schema changes require Prisma migrations; never edit production data ad hoc in PRs.
• Security: Validate inputs, avoid leaking secrets in logs, and consider multi-tenant/company boundaries.

Testing expectations

• Add or update unit/integration tests for non-trivial logic (Vitest is the project runner).
• Run targeted tests while developing, and a broader suite before requesting review:

npm run lint
npm test
npm run i18n:validate

For UI-heavy changes, include manual steps in the PR (roles used, pages visited, expected results).

Reporting bugs, requesting features, and filing tickets

Bug reports

Include enough detail for a stranger to reproduce:

• NATS version / commit SHA and deployment method (local, Docker)
• OS, Node.js version, browser (if UI)
• Exact steps to reproduce
• Expected vs actual behavior
• Logs, stack traces, and screenshots
• Whether the issue is a regression

Feature requests

• Problem statement and who it helps
• Proposed solution and alternatives considered
• Impact on existing modules, permissions, and migrations
• Willingness to implement or pair on the work

Issue hygiene

• Search existing issues before opening a new one.
• Use clear titles and keep one problem per ticket.
• Update the issue when you learn more; close duplicates with a pointer.

Start here: Open a new issue.

Documentation, design, and community support

Documentation

• Marketing/docs site lives in docs/ and deploys via GitHub Pages workflow.
• Prefer accurate, concise steps over marketing fluff in guides.
• Keep screenshots optimized and stored under docs/assets/images/.

Design

• Match existing spacing, typography, and component patterns.
• Target WCAG 2.1 AA: contrast, focus states, labels, and keyboard access.
• Document visual changes with before/after captures in the PR.

Community support

• Answer questions with reproducible steps and links to docs.
• Label and triage issues if you have write access; otherwise leave structured comments.
• Be patient with first-time contributors.

Credits & contributors

NATS is built by volunteers and the broader open-source community. Core project attribution:

For a live list of code contributors, see the GitHub contributors graph: github.com/maziyank/nats/graphs/contributors.

Significant contributors may be recognized in release notes (CHANGELOG.md) when maintainers cut versions.

Return to the product home or the setup guide.