* I added two files:
- .github/scripts/ai_pr_event.py, copied from docling. Its logic is unchanged; I only reformatted it with ruff
format because docling-core allows longer lines.
- tests/test_ai_pr_event.py, copied from docling with the same reformatting and one small fix. Two helper
functions inside the test were annotated -> object, so ty couldn't see .run and .force_review. I changed both to
-> Any. The script is loaded by file path, so ty can't use the real Decision type.
Signed-off-by: Peter Staar <taa@zurich.ibm.com>
* adding the AI triaging
Signed-off-by: Peter Staar <taa@zurich.ibm.com>
---------
Signed-off-by: Peter Staar <taa@zurich.ibm.com>
9.6 KiB
Contributing In General
Our project welcomes external contributions. If you have an itch, please feel free to scratch it.
For more details on the contributing guidelines head to the Docling Project community repository.
Developing
Usage of uv
We use uv as package and project manager.
Installation
To install uv, check the documentation on Installing uv.
Create an environment and sync it
You can use the uv sync to create a project virtual environment (if it does not already exist) and sync
the project's dependencies with the environment.
uv sync --all-extras
Use a specific Python version (optional)
If you need to work with a specific version of Python, you can create a new virtual environment for that version and run the sync command:
uv venv --python 3.12
uv sync --all-extras
More detailed options are described on the Using Python environments documentation.
Add a new dependency
Simply use the uv add command. The pyproject.toml and uv.lock files will be updated.
uv add [OPTIONS] <PACKAGES|--requirements <REQUIREMENTS>>
Code style guidelines
We use the following tools to enforce code style:
A set of styling checks is defined and managed through prek, a fast drop-in replacement for the pre-commit framework. To ensure that those scripts run automatically before a commit is finalized, install the hooks on your local repository:
make hooks-install
To run the checks on-demand, type:
make validate # hooks on the changed files
make validate-all # hooks on all files
make check # read-only checks
make fix # apply the Ruff formatter and fixers
make test # run the test suites
Pull requests also run a fast lint and typing check on the changed files. This check does not need a maintainer approval to run.
An AI triage also runs on each pull request. It posts one comment, adds advisory ai:* and topic labels, and writes a first review with inline comments. It never approves or blocks a pull request, and a maintainer still reviews every change. See AI PR triage and first review.
Documentation
We use JSON Schema for Humans to generate Markdown pages documenting the JSON schema of the Docling objects.
The documentation pages are stored in docs folder and are updated at every commit, as part of the prek check hooks. To generate the documentation on-demand, run:
uv run python -m docling_core.utils.generate_docs docs
Breaking changes and schema bumps
DoclingDocument carries an embedded schema version (CURRENT_VERSION in
constants.py).
This version is independent of the library (pyproject.toml) version and must
only be bumped when the serialized JSON representation changes in a way that
could cause an older docling-core to fail parsing.
Change classification
| Change | Schema version bump | Required companion work |
|---|---|---|
| New enum value on a serialized field | Minor bump | Downgrade projector mapping the new value to the nearest old equivalent |
| New optional field on an existing model | Minor bump | Downgrade projector stripping the field |
| New required field | Minor bump | Downgrade projector supplying a safe default |
New DocItem subtype (new discriminator label) |
Minor bump | Projector converting to nearest existing type or dropping the item |
| Field removed or renamed | Major bump | Migration guide; old clients must upgrade |
| Semantic change (same name, different meaning) | Major bump | Migration guide |
| Internal-only change (no JSON impact) | No bump needed | — |
Tip
A minor bump signals backward-incompatible wire changes while staying within the same major "era". Clients on the same major version can request a server-side downgrade that uses uses
docling_core.compat.project_to()to satisfy the request.
Step-by-step checklist per schema minor bump
Suppose you are bumping CURRENT_VERSION from 1.N.0 to 1.(N+1).0:
-
Implement the model change in the relevant file under
docling_core/types/doc/. -
Bump
CURRENT_VERSIONindocling_core/types/doc/common/constants.py(e.g."1.10.0"→"1.11.0"). -
Append a history entry to
SCHEMA_VERSION_HISTORYin the same file, recording the library version and a short description. -
Add a downgrade projector to
docling_core/compat.py:@register_projector(from_minor=N+1, to_minor=N) def _project_1_{N+1}_to_1_{N}(data: dict) -> dict: """Describe what this projector does.""" data = dict(data) # … transform data … data["version"] = f"1.{N}.0" return dataThe function receives the raw
dictproduced byDoclingDocument.model_dump(mode="python")and must return a modifieddictthat is valid against schema1.N.0. -
The JSON Schema snapshot is captured automatically — you do not need to do anything manually.
scripts/check_compat_projectors.py(run by the pre-commit hook) detects thatdocs/schemas/DoclingDocument_1_(N+1).jsonis missing and renders it from the live models, so it describes exactly the version it is named for. It deliberately does not copydocs/DoclingDocument.json: that artefact is regenerated by the laterdocshook and still holds the1.Nschema while this check runs. Add the generated snapshot file to your commit. -
Write a test class named exactly
TestProjector_1_{N+1}_to_1_{N}intests/test_compat.py. Add at least one non-trivial test that exercises the specific field(s) the projector handles. -
Run
python scripts/check_compat_projectors.pylocally to confirm the coverage check passes.
Automated enforcement
The following checks run automatically as pre-commit hooks and in CI:
| Check | Mechanism | What it catches |
|---|---|---|
| Projector count | scripts/check_compat_projectors.py + test_projector_count_matches_expected |
Missing @register_projector function |
| All steps covered | Same | A step (N→N-1) with no registered function |
| History table | Same | Missing SCHEMA_VERSION_HISTORY entry |
| Unannounced structural break | scripts/check_compat_projectors.py check 9 |
New enum value, new field on strict model, new required field, or new union subtype added without bumping CURRENT_VERSION |
| Projector output shape | test_every_projector_produces_valid_output |
Projector that crashes, drops required keys, or sets wrong version |
| Test class present | test_every_projector_has_a_test_class |
Projector with no TestProjector_1_N_to_1_{N-1} class |
Warning
A PR that bumps
CURRENT_VERSIONwithout a matching projector and test class will fail CI. A PR that introduces a structural breaking change without bumpingCURRENT_VERSIONwill also fail CI.
Note
What the schema diff cannot detect — serialization-semantic changes (e.g. a changed
model_serializer, a different roundtrip encoding for an existing field, reordered keys) leave the JSON Schema structurally identical so the diff is empty. These changes are invisible to static analysis. They are the contributor's responsibility to identify and announce via a version bump. The classification table above lists them as "Semantic change (same name, different meaning) → Major bump". For a minor-bump serialization-semantic change (e.g. a new encoding that old clients can still parse) no automated check is needed — bump the version, provide the projector, write the test class; the existing checks will enforce those.
The test_every_projector_produces_valid_output test is parameterized
over every registered projector. It runs a minimal document dict through
the projector and checks: the function does not raise; the output is a
dict; the version key is set to the correct target version; schema_name
is preserved; all required top-level keys are present.
Note
Why not
DoclingDocument.model_validate()? The contract of a projector is "produce a dict valid for the target SDK" — an older SDK not available at test time. Validating with the current SDK would be incorrect: if a future schema change removes a field, the current model'sextra="forbid"would reject a projected dict that contains the old field, producing a false failure. Conversely, the current model accepts a superset of what old clients accept, so it would also produce false passes. Full semantic correctness — "does this parse under the old SDK?" — is the responsibility of the hand-written per-projector test class.
Using projectors on the server side
This is an implementation example for a server providing DoclingDocument
objects to a client application with version compatibility.
from docling_core.compat import project_to
from docling_core.types.doc.document import DoclingDocument
doc: DoclingDocument = converter.convert(pdf)
# The client advertises its schema version in a request header.
client_version = request.headers.get("Accept-Schema-Version")
if client_version:
doc = project_to(doc, target_version=client_version)
return doc.model_dump_json()