Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
260 lines (190 loc) · 11.2 KB

CONTRIBUTING.md

File metadata and controls

260 lines (190 loc) · 11.2 KB
Raw

Contributing to InvenTree

Hi there, thank you for your interest in contributing! Please read our contribution guidelines, before submitting your first pull request to the InvenTree codebase.

About InvenTree

InvenTree is an open-source inventory management system designed for makers, engineers, and small manufacturers.

The codebase is split into two independently deployable layers:

Backend — Django (Python) A REST API built with Django and Django REST Framework. It owns all business logic, the database schema, background task processing (Django-Q2), plugin execution, and report generation. The backend can be used standalone via the API without the frontend.

Frontend — React (TypeScript) A single-page application built with React 19, Mantine 9, and Vite. It communicates exclusively through the backend REST API. It has its own build pipeline, test suite (Playwright), and i18n system (Lingui). The frontend lives entirely in src/frontend/ and has no Django awareness.

When making changes, be clear about which layer you are working in — they have separate toolchains, test runners, and linting rules.

Project File Structure

The InvenTree project is split into two main components: frontend and backend. This source is located in the src directory. All other files are used for project management, documentation, and testing.

InvenTree/
├─ .github/                            # Files for GitHub
│  ├─ actions/                         # Reused actions
│  ├─ ISSUE_TEMPLATE/                  # Templates for issues and pull requests
│  ├─ workflows/                       # CI/CD flows
│  ├─ scripts/                         # CI scripts
├─ .vscode/                            # Settings for Visual Code IDE
├─ assets/                             # General project assets
├─ contrib/                            # Files needed for deployments
│  ├─ container/                       # Files related to building container images
│  ├─ installer/                       # Files needed to build single-file installer
│  ├─ packager.io/                     # Files needed for Debian/Ubuntu packages
├─ docs/                               # Directory for documentation / General helper files
│  ├─ ci/                              # CI for documentation
│  ├─ docs/                            # Source for documentation
├─ src/                                # Source for application
│  ├─ backend/                         # Directory for backend parts
│  │  ├─ InvenTree/                    # Source for backend
│  │  ├─ requirements.txt              # Dependencies for backend
│  │  ├─ package.json                  # Dependencies for backend HTML linting
│  ├─ frontend/                        # Directory for frontend parts
│  │  ├─ src/                          # Source for frontend
│  │  │  ├─ main.tsx                   # Entry point for frontend
│  │  ├─ tests/                        # Tests for frontend
│  │  ├─ netlify.toml                  # Settings for frontend previews (Netlify)
│  │  ├─ package.json                  # Dependencies for frontend
│  │  ├─ playwright.config.ts          # Settings for frontend tests
│  │  ├─ tsconfig.json                 # Settings for frontend compilation
├─ .pkgr.yml                           # Build definition for Debian/Ubuntu packages
├─ .pre-commit-config.yaml             # Code formatter/linter configuration
├─ biome.json                          # JS/TS linting and formatting config
├─ CONTRIBUTING.md                     # Contribution guidelines and overview
├─ Procfile                            # Process definition for Debian/Ubuntu packages
├─ pyproject.toml                      # Python tooling config (Ruff, pytest, coverage, djLint, ty)
├─ README.md                           # General project information and overview
├─ SECURITY.md                         # Project security policy
├─ tasks.py                            # Action definitions for development, testing and deployment

Backend app domains

The following Django apps are defined in src/backend/InvenTree/:

Directory Domain
build/ Build (manufacturing/assembly) orders
common/ Shared models, settings, utilities
company/ Suppliers, customers, manufacturers
data_exporter/ Data export functionality
generic/ Shared enums, events, and state machine utilities
importer/ Data import functionality
InvenTree/ Core configuration (settings, URLs, middleware)
machine/ Support for external machines and devices
order/ Purchase orders and sales orders
part/ Parts catalogue and categories
stock/ Stock items and locations
report/ Report templates and generation
plugin/ Plugin system
users/ User accounts and permissions
web/ Serves the React frontend static build to Django

Frontend layout

src/frontend/src/
  components/   # Reusable React components
  pages/        # Page-level route components
  tables/       # Data table components
  forms/        # Form components
  hooks/        # Custom React hooks
  states/       # Zustand global state
  locales/      # i18n translation catalogues (Lingui)

Development Setup

The project uses Invoke (tasks.py) as the task runner.

# One-time setup: creates venv at dev/venv/, installs deps, sets up pre-commit hooks
invoke dev.setup-dev

# Apply database migrations (and detect/create new migration files if required)
invoke migrate --detect

# Create an admin account (required to log in)
invoke superuser

# Terminal 1 — Django dev server (port 8000)
invoke dev.server

# Terminal 2 — Vite dev server with HMR (port 5173)
invoke dev.frontend-server

# Terminal 3 (optional) — Background task worker
invoke worker

A VS Code Dev Container configuration is available at .devcontainer/ and includes PostgreSQL 15 and Redis 7 sidecar services.

To see all available tasks, run invoke --list.

Running Backend Tests

Always pass --keepdb to backend test commands. It reuses the existing test database instead of rebuilding it from scratch on every run, which is significantly faster.

# All backend tests
invoke dev.test --keepdb

# Specific test module
invoke dev.test --keepdb --runtest=company.test_api

# With coverage
invoke dev.test --keepdb --coverage

# Migration tests only (skip --keepdb here — migrations must run against a fresh DB)
invoke dev.test --migrations

Running Frontend Tests

Frontend tests use Playwright and target Chromium and Firefox. The test runner automatically starts the Vite dev server (port 5173), the Django backend (port 8000), and the background worker — no manual server startup is needed.

# Open Playwright's interactive UI (recommended for local development)
invoke dev.frontend-test

# Run tests in headless mode from the frontend directory
cd src/frontend && npx playwright test

# Run a specific test file
cd src/frontend && npx playwright test tests/pui_login.spec.ts

# Run tests in a specific browser only
cd src/frontend && npx playwright test --project=chromium

Test files live in src/frontend/tests/ and follow the pui_*.spec.ts naming convention.

Locally, tests run with a single worker (required for Vite HMR compatibility). In CI they run with multiple workers against a production build for speed.

Code Style and Linting

All formatting and linting runs automatically on commit via pre-commit hooks. Never skip them.

Python (Backend)

Tool: Ruff (replaces Black, isort, flake8, and others).

ruff check src/backend/         # Lint
ruff format src/backend/        # Format
  • Google-style docstrings enforced
  • Enabled rule sets: A, B, C, D, F, I, N, SIM, PIE, PLE, PLW, RUF, UP, W
  • Type checking: ty (configured in pyproject.toml)

Django Templates

Tool: djLint

djlint src/backend/ --check

JavaScript / TypeScript (Frontend)

Tool: Biome (replaces ESLint + Prettier).

cd src/frontend
yarn biome check .      # Lint + format check
yarn biome format .     # Format only
  • Single quotes, space indentation
  • noUnusedImports is an error

Making Changes

Backend

  • Each Django app has its own models.py, serializers.py, views.py, urls.py, and filters.py.
  • API endpoints use Django REST Framework; document them with drf-spectacular decorators.
  • After changing models, create a migration: invoke dev.makemigrations.
  • Tests live in test_*.py files within each app directory.
  • Background tasks go through Django-Q2; define them in the app's tasks.py.

Frontend

  • Pages register themselves in src/frontend/src/router.tsx.
  • Server state fetching uses TanStack Query (React Query); avoid raw useEffect for data fetching.
  • Global UI state uses Zustand stores in states/.
  • UI components come from Mantine 9.x; use the Mantine component library before writing custom CSS.
  • Add i18n strings with Lingui (t macro / Trans component); run invoke int.frontend-trans to extract from source and compile. (invoke dev.translate is for the full translation pipeline and is not intended for local use.)
  • Playwright tests live in src/frontend/tests/.

Dependencies

Python: Add packages to src/backend/requirements.in (or requirements-dev.in for dev-only tools). The pre-commit hook runs pip-compile automatically on commit to regenerate requirements.txt. Never edit requirements.txt directly.

Frontend: Add packages with yarn add <package> from src/frontend/.

Migrations

  • Never edit existing migration files; always generate new ones.
  • Keep migrations reversible where possible.
  • Migration tests run in CI under the tag migration_test.

CI / CD

GitHub Actions workflows live in .github/workflows/. Key workflows:

Workflow Purpose
qc_checks.yaml Lint, type-check, backend tests, API schema
frontend.yaml Playwright E2E tests, frontend build
docker.yaml Docker image builds
translations.yaml Crowdin i18n sync

CI uses path-based filtering — only affected jobs run per PR. Coverage tracked via Codecov; quality analysis via SonarCloud.

Key Conventions

  • REST API versioning: Endpoint changes must not break the published API schema. Run invoke dev.schema and check the diff before opening a PR.
  • Plugin safety: The plugin system (plugin/) is a public extension point; avoid breaking its interfaces.
  • No hardcoded secrets: gitleaks runs in pre-commit and CI — any credential-shaped string will block merges.
  • Database portability: Code must work on PostgreSQL, MySQL/MariaDB, and SQLite. Avoid database-specific SQL or ORM features.
  • Frontend translations: Every user-visible string must be wrapped in a Lingui t macro or <Trans> component.
  • Test tagging: Tag slow or special tests (@tag('migration_test'), @tag('performance_test')) so CI can filter them selectively.

Refer to our contribution guidelines for more information!