Contributing

qnop is developed in the open at github.com/qnophq/qnop. This page is the short version of the repository’s CONTRIBUTING.md, which stays the authoritative source.

The workflow

1. Open an issue first, describing the intent before changing code.
2. Branch off main. main is integration-only and protected — never commit or push to it directly.
3. Open a pull request that references its issue (Closes #12). Keep it focused.
4. Sign the CLA on your first PR; a bot prompts you.
5. CI must be green before merge.

Everything that lands in the repository, an issue or a PR is written in English — including commit messages, documentation and code comments.

Branches

Branch names follow Conventional Branch: <type>/<description>, with feat, fix, hotfix, release or chore as the type. Descriptions are lowercase a-z, digits and hyphens — no underscores, spaces or consecutive hyphens. Dots appear only in release versions (release/v1.2.0). Including the issue number is welcome: feat/issue-123-new-login.

Commits

Conventional Commits, with feat, fix, refactor, docs, test, chore, perf, ci or build as the type:

<type>: <subject>

<optional body>

Signed-off-by: Your Name <you@example.com>

Every commit needs a DCO sign-off (git commit -s), certifying you have the right to submit the work under the project licence.

Work produced with an AI coding agent must be attributed — a Co-Authored-By: trailer on commits, and an attribution line in the issue or PR body.

Code quality

Backend. Run ./gradlew spotlessApply before committing; ./gradlew build must pass, which runs the Spotless check and the ArchUnit rules. Every source file carries the copyright header and SPDX-License-Identifier: AGPL-3.0-only. Spotless inserts it for Java automatically — package-info.java and frontend files need it by hand.

Frontend. From qnop-ui/: pnpm format && pnpm lint && pnpm build.

Layering. The architecture boundaries are enforced by ArchUnit, not by convention: web → service → repository → entity. The published contracts (qnop-spi, qnop-api) stay Spring-free.

The CLA, and why there is one

qnop is open core — the AGPL-3.0 community edition plus commercial add-ons. To keep that dual path legally sound, every contributor signs a one-time CLA granting the project the right to sublicense contributions, including under commercial terms. A bot comments on your first PR with instructions.

The DCO sign-off and the CLA are complementary — both are required. If you use an AI coding agent, you as the human operator sign on behalf of the submission.

Architecture decisions

Significant decisions are recorded as ADRs and are public. If your change involves one, add the ADR in the same pull request. Reading the ADR index is also the fastest way to understand why qnop is built the way it is.

Dependencies

Dependencies are kept current by a self-hosted Renovate instance that opens grouped PRs. Review them like any other change; do not bump dependencies by hand unless you are fixing an urgent security issue.

Prefer permissive licences (Apache-2.0, MIT, BSD, MPL-2.0) for new dependencies. Copyleft tooling may only be used out-of-process.