Contributing to Provenance

Thanks for your interest in helping build Provenance. This document covers how to contribute and the one legal step we ask of every contributor.

A note on the license

Provenance is source-available under the Business Source License 1.1, not (yet) open source. It is free for personal, family, and non-commercial use, and each release converts to AGPL-3.0 four years after it ships. Contributing does not change those terms. Please make sure you're comfortable with the license before sending a change.

Developer Certificate of Origin (DCO)

We use the Developer Certificate of Origin instead of a heavier contributor agreement. It's a lightweight, well-understood mechanism (the same one the Linux kernel uses) that lets you certify you have the right to submit your contribution.

In practice: sign off every commit. Add a Signed-off-by line by committing with -s:

git commit -s -m "Your message"

That appends a line like:

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

By signing off, you certify the statement at https://developercertificate.org/ — in short, that the contribution is yours to give (or you have the right to submit it) and that you understand it will be distributed under the project's license. Commits without a sign-off can't be merged.

Why DCO and not just a handshake: it keeps the project's licensing chain clean, so the maintainer can relicense or dual-license in the future (for example, the planned conversion to AGPL-3.0, or a possible first-party hosted offering) without having to track down every past contributor.

Before you start

Open an issue first for anything beyond a small fix. Describe the use case, not just the proposed change — Provenance is opinionated about UX for casual users, and context helps.
Check docs/PRD.md to see where a feature fits in the roadmap and whether it's currently in or out of scope.
For anything touching privacy, the AI assistant's write path, or the hint-matching engine, expect extra scrutiny. These are the areas where mistakes do real harm, so changes there need a clear design discussion before code.

Development setup

The stack is still standing up; this section will firm up as Phase 0 lands. The shape:

Frontend: Next.js + React + TypeScript + Tailwind + shadcn/ui
Backend: Python + FastAPI
Database: PostgreSQL
Object storage: S3-compatible (MinIO locally)
Everything is container-native and configured via environment variables.

Local development runs via the project's compose stack. See the README and docs/ for current instructions as they're published.

Pull request guidelines

Keep PRs focused — one logical change per PR.
Reference the issue the PR addresses.
Every commit signed off (-s); see DCO above.
Include tests for new behavior where a test surface exists.
Update docs (including the PRD if scope changes) in the same PR.
Write clear commit messages: a concise summary line, then a body explaining why if it isn't obvious.

Reporting security and privacy issues

Please do not open a public issue for a security vulnerability or a privacy-leak concern (especially anything that could expose living people's data or break the hint-matching anonymity guarantees). Report it privately to the maintainer so it can be fixed before disclosure.

Code of conduct

Participation in this project is governed by the Code of Conduct. By taking part, you agree to uphold it.

Provenance is built in the open, commit by commit. Thanks for being part of it.

3.6 KiB Raw Permalink Blame History