Files
docling-core/CONTRIBUTING.md
Peter W. J. Staar 3b146930ba chore: add automatic AI triage and review (#959)
* 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>
2026-11-03 16:13:53 +01:00

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:

  • Ruff, to format and lint code
  • ty, as static type checker

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:

  1. Implement the model change in the relevant file under docling_core/types/doc/.

  2. Bump CURRENT_VERSION in docling_core/types/doc/common/constants.py (e.g. "1.10.0" → "1.11.0").

  3. Append a history entry to SCHEMA_VERSION_HISTORY in the same file, recording the library version and a short description.

  4. 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 data
    

    The function receives the raw dict produced by DoclingDocument.model_dump(mode="python") and must return a modified dict that is valid against schema 1.N.0.

  5. 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 that docs/schemas/DoclingDocument_1_(N+1).json is missing and renders it from the live models, so it describes exactly the version it is named for. It deliberately does not copy docs/DoclingDocument.json: that artefact is regenerated by the later docs hook and still holds the 1.N schema while this check runs. Add the generated snapshot file to your commit.

  6. Write a test class named exactly TestProjector_1_{N+1}_to_1_{N} in tests/test_compat.py. Add at least one non-trivial test that exercises the specific field(s) the projector handles.

  7. Run python scripts/check_compat_projectors.py locally 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_VERSION without a matching projector and test class will fail CI. A PR that introduces a structural breaking change without bumping CURRENT_VERSION will 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's extra="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()