Contributing

pygarble is a deterministic Python package for English gibberish detection. Keep runtime dependencies at zero, document heuristic limitations, and include regression cases for behavior changes.

Set up a checkout

Clone your fork, or use the upstream repository if you have write access:

git clone https://github.com/brightertiger/pygarble.git
cd pygarble
python -m venv .venv
source .venv/bin/activate
python -m pip install -e ".[dev]"
python -m pip install -r requirements-dev.txt
git switch -c docs/my-change

On Windows, activate with .venv\Scripts\activate instead.

Validation

Run the checks relevant to your change. The CI test matrix covers Python 3.8–3.12.

python -m pytest -q
black --check pygarble tests scripts regression
isort --check-only pygarble tests scripts regression
flake8 pygarble tests scripts regression
mypy pygarble
pre-commit run --all-files
python scripts/update_strategy_docs.py --check
python -m sphinx -W --keep-going -b html docs /tmp/pygarble-docs

The strategy reference is generated from pygarble/registry.py and pygarble/options.py. Update those sources when supported settings change, then run python scripts/update_strategy_docs.py. Keep practical usage guidance in docs/strategy-guide.rst and runnable examples in the quick start and README.

Data and evaluation

python scripts/generate_data.py --check
python regression/evaluate.py --split development

Data generation downloads a pinned source and verifies its checksum. For offline verification, supply --source /path/to/count_1w.txt. Curated exclusions live in scripts/data_curation.json; artifact hashes live in pygarble/data/manifest.json. Do not edit generated tables directly.

Keep development and holdout families separate; do not tune thresholds on holdout errors. Report confusion counts and limitations rather than treating a small benchmark as a production precision estimate. Hindi being flagged by English checks is expected; corruption-only checks have a separate contract.

Package validation

python -m pip install build twine
python -m build
python -m twine check dist/*

Also verify the wheel in a fresh environment with pip install --no-deps. Building artifacts does not publish them. Publishing is a separate maintainer action; do not create release tags or dispatch publishing workflows as part of routine documentation or implementation changes.

Pull requests and issue reports

Use a feature or fix branch and open a pull request with the problem, resulting behavior, and relevant validation. Update user documentation when the API or classification policy changes. Include tests for new behavior or fixes; avoid claiming unexecuted checks passed.

For an issue, include a minimal input, expected and actual results, Python and package versions, profile or strategy, and configuration. See existing tests for examples of batch contracts, explanations, and English-specific behavior.