Contributing#

pagescan is an open-source product of 7R+ GmbH. Bug reports, fixes, and discussion are all welcome.

Quick orientation#

Directory

What’s there

src/pagescan/

The package — what gets shipped to PyPI.

tests/

Test suite. Run with pytest.

benchmark/

Real-data benchmarks. Production harness is benchmark/comparison/; benchmark/ceiling/ is a development reference with GT bboxes.

training/yolo/

YOLO11 detector training pipeline.

docs/

This documentation site (Sphinx + MyST + pydata-sphinx-theme).

data/model/

Local model-weight cache (gitignored).

_archive/

Failed-approach reference. Not part of the product — don’t import from it.

Dev setup#

git clone https://github.com/7RPlus-GmbH/pagescan.git
cd pagescan
pip install -e ".[dev,ml,docs]"

The [dev] extras pull in the test and lint toolchain; [ml] enables the cascade; [docs] builds this site.

Quality gates#

Before opening a PR, all three must be clean:

ruff check src tests             # lint
mypy src/pagescan                # type-check
pytest -q                        # tests

The same gates run in CI on every PR via .github/workflows/ci.yml — pytest matrix on Python 3.9–3.13.

Building the docs locally#

cd docs
make html
make serve     # opens http://localhost:8000

make linkcheck validates every external link in the docs. Run it before any PR that touches the documentation.

Before opening an issue#

  • Search existing issues.

  • For bug reports, include: pagescan version, Python version, OS, a minimal reproducer, and the input image if possible (or a description of the document type, lighting, and background).

Before opening a pull request#

  • Discuss large changes in an issue first. The 0.1.0 release plan is opinionated about scope.

  • Quality gates clean (ruff + mypy + pytest).

  • Update CHANGELOG.md under [Unreleased] for user-facing changes.

  • Keep PRs focused. One change per PR.

What we’re looking for help with#

The roadmap is opinionated, but the following are always welcome:

  • Labeled training data in our failure distributions — magazines, white-on-cream paper, hand-occluded scenes. Even 20–50 labeled photos help.

  • Bug reports with attached images pagescan scans poorly.

  • Documentation improvements — especially examples and tutorials.

  • Benchmark results from real workflows.

What we’re not doing in 0.1.0#

  • Mobile / on-device SDK.

  • Cloud-hosted scanning service.

  • Receipt / non-rectangular document support.

  • Languages beyond German / English.

These are out of scope for 0.1.0 and may be considered for later versions.

Contact#

For non-technical questions: contact@7rplus.com.