Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
107 lines (78 loc) · 4.16 KB

CONTRIBUTING.md

File metadata and controls

107 lines (78 loc) · 4.16 KB
Raw

Contributing to open·kritt

Thanks for helping improve open·kritt. Please follow our Code of Conduct when participating.

Before you start

  • Search existing issues before reporting a bug or requesting a feature.
  • Use Discussions for questions, ideas, and larger proposals. Starting there can prevent duplicated work.
  • Never report a vulnerability publicly. Follow SECURITY.md to submit it privately.

Set up the project

You need Git, Docker with Docker Compose, and Node.js 20 or newer. Fork the repository, then:

#    External contributors: fork on GitHub, then clone your fork:
git clone https://github.com/<you>/open-kritt && cd open-kritt

# 2. Configure model access and bring the whole stack up
./kritt setup
./kritt start

# 3. Make changes on a branch and use Conventional Commits
git checkout -b feat/my-change
git commit -m "feat(frontend): add X"

# 4. Push and open a PR against main. CI must pass before it can merge.

These commands configure the environment and start the full stack. See the installation guide for more detail.

Make and validate your change

Keep each change focused. Add or update tests and documentation when behavior changes, then run the checks for every area you touched:

Area Checks
Frontend cd frontend && npm install && npm run lint && npm run format:check && npm test && npm run build
Backend cd backend && npm install && npx prisma generate && npx prisma validate && npm run lint && npm run format:check && npm test
Engine cd engine && pip install -r requirements.txt && ruff check . && ruff format --check . && pytest
CLI node --test scripts/kritt.test.mjs scripts/kritt-ui.test.mjs scripts/kritt-headless.test.mjs
Documentation cd docs-site && npm run check-links

Engine tests currently run locally but are not enabled in CI. A full-stack smoke test is recommended for changes that cross component boundaries:

docker compose up --build

Project rules

  • Never commit credentials, tokens, .env, or local scan data.
  • Database changes must use a new numbered SQL file in database/init/. Migrations must be additive, forward-only, and safe to run repeatedly; update backend/prisma/schema.prisma to match and run npm run migrate twice.
  • VERSION is the product version's source of truth. Normal contributions should not bump it. If a version change is required, edit VERSION and run node scripts/sync-version.mjs.
  • Keep Docker image tags pinned.
  • Read the repository-specific agent and contributor gotchas before changing dependency lockfiles, Prisma setup, result keys, or Markdown rendering.

Commit your change

Every commit must use Conventional Commits:

git commit -m "fix(frontend): describe the change"

Common types are feat, fix, docs, refactor, test, chore, and ci. A scope is optional; use feat: or feat(frontend):, never feat():.

Contribution terms

By intentionally submitting a pull request, commit, patch, or other contribution, you agree to the Contribution Terms, including assignment of your transferable rights in the contribution jointly to Harel Rom and Gabriel Balko. Do not submit work that an employer, client, university, or another party owns or restricts.

No separate signature, contributor agreement, form, checkbox, registry, or special commit syntax is required. The ordinary act of submitting the contribution is the only assent step.

Open a pull request

Push your branch and open a pull request against main. In the pull request:

  • Explain what changed and why, and link the related issue.
  • List the checks you ran.
  • Include screenshots for visible UI changes.
  • Keep unrelated changes out of the diff.
  • Complete the pull request template and make sure CI passes.

Contributions are distributed as part of the project under the repository's GNU AGPL v3.0 license.