Contributing Guide

Thank you for considering a contribution to DocuGardener. Here is everything you need to get started.

License

DocuGardener is licensed under the GNU Affero General Public License v3.0 (AGPL-3.0). By submitting a pull request, you agree that your contributions will be licensed under the same terms. If your employer has a CLA requirement, please check with them before contributing.

How to Contribute

Fork the repository on GitHub.
Create a branch from main with a descriptive name (e.g. fix/inbox-filter-bug or feat/slack-notifications).
Make your changes — keep commits focused and well-described.
Open a pull request against main. Describe what you changed and why.
Wait for review. A maintainer will review your PR, suggest changes if needed, and merge when ready.

Development Setup

The development setup is the same as the Docker Compose deployment, with the addition of test tooling.

1. Start infrastructure

git clone https://github.com/docugardener/docugardener.git
cd docugardener
cp .env.example .env
# Edit .env with your values
docker compose --env-file .env -f docker/docker-compose.yml up -d

2. Set up the Python backend

python3.13 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"

3. Set up the Next.js frontend

cd web
npm install
npx prisma migrate dev --name init
npm run dev

Running Tests

Python tests (pytest)

source .venv/bin/activate
pytest

To run a specific test file or test function:

pytest tests/unit/test_drift_analysis.py
pytest tests/unit/test_drift_analysis.py::test_score_calculation -v

Frontend tests (Vitest)

cd web
npx vitest run

For watch mode during development:

npx vitest

End-to-end tests (Playwright)

cd web
E2E_ENABLED=1 npx playwright test

Note: E2E tests require all services to be running (Docker Compose + web dev server). Set E2E_ENABLED=1 to enable them — they are skipped by default to avoid accidental runs against production.

Code Style

Language	Formatter / Linter	Command
Python	Ruff (format + lint)	`ruff check . && ruff format .`
TypeScript	ESLint + Prettier	`cd web && npx eslint . && npx prettier --check .`

Pull Request Checklist

Before requesting a review, make sure your PR meets the following criteria:

All existing tests pass (pytest + npx vitest run).
New features include tests.
No regressions — existing functionality still works as expected.
Documentation is updated if you added a new feature, changed behaviour, or modified environment variables.
Code style checks pass (Ruff for Python, ESLint + Prettier for TypeScript).
Commit messages are clear and describe the “why”, not just the “what.”

Community

We use GitHub for all project communication:

Bugs: GitHub Issues — search existing issues before opening a new one.
Feature requests & questions: GitHub Discussions — great for open-ended conversations and RFCs.

Good First Issues

New to the project? Look for issues tagged good first issue on GitHub. These are smaller, well-scoped tasks that are ideal for first-time contributors.