CONTRIBUTING.md

Contributing to Docling Studio

Thank you for your interest in contributing to Docling Studio! This guide will help you get started.

Getting Started

1. Fork the repository on GitHub
2. Clone your fork locally:

   git clone https://github.com/<your-username>/Docling-Studio.git
   cd Docling-Studio
   

3. Create a branch for your work:

   git checkout -b feature/my-feature
   

Development Setup

Backend (Python 3.12+)

cd document-parser
python -m venv .venv && source .venv/bin/activate

# Remote mode (lightweight — delegates to Docling Serve)
pip install -r requirements.txt

# Local mode (full — runs Docling in-process)
pip install -r requirements-local.txt

pip install ruff pytest pytest-asyncio httpx  # dev tools
uvicorn main:app --reload --port 8000

Frontend (Node 20+)

cd frontend
npm install
npm run dev

Code Quality

Backend — Ruff

We use Ruff for linting and formatting Python code.

cd document-parser
ruff check .          # lint
ruff check . --fix    # lint with auto-fix
ruff format .         # format

Frontend — TypeScript + ESLint + Prettier

cd frontend
npm run type-check          # type check (vue-tsc)
npx eslint src/             # lint
npx prettier --check src/   # check formatting
npx prettier --write src/   # auto-format

Running Tests

# Backend (199 tests)
cd document-parser
pytest tests/ -v

# Frontend (129 tests)
cd frontend
npm run test:run

All tests must pass before submitting a PR.

Submitting Changes

1. Commit with clear, descriptive messages
2. Push your branch to your fork
3. Open a Pull Request against main
4. Describe what changed and why in the PR description
5. Ensure CI passes (tests + build)

Branching Strategy

We follow a simplified Git Flow:

Branch	Purpose
main	Always stable — latest release merged back
release/X.Y.Z	Release preparation (freeze, bugfixes, changelog)
feature/*	New features — PR to main
fix/*	Bug fixes — PR to main (or release/* for pre-release fixes)
hotfix/X.Y.Z	Urgent fix on a released version — PR to main

Rules:

• All PRs target main (never stack branches on other feature branches)
• release/* branches are created from main when preparing a release
• hotfix/* branches are created from the release tag

Versioning

We use Semantic Versioning: MAJOR.MINOR.PATCH.

• Source of truth: the git tag (vX.Y.Z)
• package.json version should match the current release branch
• The build injects the version automatically (Vite __APP_VERSION__ for frontend, APP_VERSION env var for backend)

Release Process

1. Create the release branch from main:

   git checkout main && git pull
   git checkout -b release/X.Y.Z
   

2. On the release branch, only:

   • Bug fixes
   • Move [Unreleased] to [X.Y.Z] - YYYY-MM-DD in CHANGELOG.md
   • Update version in frontend/package.json

3. Merge into main via PR, then tag on main:

   git checkout main && git pull
   git tag vX.Y.Z
   git push origin vX.Y.Z
   

4. The tag triggers the release workflow which builds and pushes the Docker image to ghcr.io.

Docker Image Tags

Each release produces two image variants:

Tag	Description
X.Y.Z-remote	Exact version — lightweight (Docling Serve)
X.Y.Z-local	Exact version — full (in-process Docling)
X.Y-remote	Latest patch of this minor — lightweight
X.Y-local	Latest patch of this minor — full
latest-remote	Latest stable — lightweight
latest-local	Latest stable — full

Hotfix

git checkout vX.Y.Z           # from the release tag
git checkout -b hotfix/X.Y.Z+1
# fix, commit, PR to main
git tag vX.Y.Z+1              # tag on main after merge

Changelog

We follow Keep a Changelog. Every PR should add a line under [Unreleased] in CHANGELOG.md. The release branch moves [Unreleased] to the versioned section.

Pull Request Guidelines

• Keep PRs focused — one feature or fix per PR
• Add tests for new functionality
• Update documentation if behavior changes
• Follow existing code style and conventions

Reporting Issues

• Use GitHub Issues to report bugs or request features
• Include steps to reproduce for bugs
• Mention your OS, Python/Node version, and Docker version if relevant

License

By contributing, you agree that your contributions will be licensed under the MIT License.