| description | Set up the City2Graph development environment, run tests and pre-commit checks, follow the code style, and submit a pull request. | |
|---|---|---|
| keywords | contributing, pull request, development environment, pre-commit, pytest, coverage, code style, ruff, mypy, numpydoc, documentation | |
| hide |
|
We welcome contributions to City2Graph. This guide is the canonical reference for setting up the repository, making and testing changes, and submitting a pull request.
-
Fork the repository on GitHub.
-
Clone your fork locally:
git clone https://github.com/<your-name>/city2graph.git cd city2graph git remote add upstream https://github.com/c2g-dev/city2graph.git
-
Install uv if it is not already available on your
PATH. -
Install the development dependencies with the CPU-only PyTorch extra:
uv sync --extra cpu --group dev
The CPU build keeps development installations fast and deterministic. The project supports Python 3.12 through 3.14, and CI tests every supported version.
There is no separate virtual-environment activation step. Run project commands
with uv run; uv automatically uses the managed environment.
Create a branch from an up-to-date main branch. Direct commits to main are
blocked by the no-commit-to-branch pre-commit hook.
git checkout -b your-change-nameKeep each pull request focused. Update tests and documentation with the code they describe, and use a concise, descriptive commit message.
Before committing, run both required checks:
uv run pytest -q
uv run pre-commit run --all-filesThese are the same commands used by the repository's local workflow and CI.
All code, comments, docstrings, and documentation must be written in English.
City2Graph uses:
- Ruff for linting, import ordering, and formatting. The formatter line length is 100 characters; the lint configuration allows lines up to 140 characters where Ruff cannot rewrite them cleanly.
- mypy with strict type checking. Public functions must have type hints.
- numpydoc validation. Public modules, functions, classes, and methods must use NumPy-style docstrings.
Use four spaces for indentation. Prefer the existing public API and established module patterns when extending functionality. If a change affects public behaviour, update the corresponding docstring and documentation.
The public GTFS entry points live in city2graph.transportation. Their implementation lives in the internal
city2graph.gtfs package:
| Module | Responsibility |
|---|---|
schema |
Input types, configuration, primitive conversions, schemas and the defaults registry |
validation |
Input validation, normalisation, selection and GTFS integrity |
metadata |
Source records, adopted conditions, validation and JSON serialisation |
report |
Summary tables derived from recorded conditions |
feed |
DuckDB setup and GTFS ZIP persistence |
service |
Calendars, operating conditions, identifiers and agency metadata |
generation |
Generation stages, geometry, travel times and table materialisation |
sources |
OSM interpretation, retrieval and supplemental inputs |
Dependencies point upwards in this table. Internal modules do not import the
public facades. The transportation facade supplies geographical and download operations from
city2graph.data to the source adapters and shares calendar and edge aggregation
between graph analysis and generated-feed summaries. The data module has no
dependency on the GTFS package.
Place new functionality with its existing owner. A new internal module needs an independent responsibility and a clear dependency justification. Keep preparation and reusable indexes local to one generation call so that later changes to caller DataFrames or database tables are respected. Resolve an adopted value and its metadata together, then carry that decision through generation and reporting.
The initial public generation model is simple-v1. Internal refactors preserve
its operating rules and identifiers. Benchmarks record the model and conditions used for each run.
Keep downloaded GTFS archives, OSM responses, regional extracts, boundaries,
walking graphs and intermediate analysis outputs outside Git. Use the ignored
docs/examples/data/ and benchmarks/data/ directories, or an external data
location. Benchmark results belong under the ignored benchmarks/results/.
Tests construct the smallest synthetic inputs that exercise the public API.
Share source fixtures through tests/conftest.py and create temporary archives
with pytest's tmp_path; avoid city-scale snapshots and fixed real-network counts.
The tutorial contains the maintained example code. Retain only figures used by
published pages, with source attribution. One-off acquisition, rendering and audit
scripts belong in a separate research workspace.
Tests live under tests/ and mirror the package layout. Add a new test class
only when the test does not belong to an existing class.
Test private helper functions indirectly through the public function that calls them. Do not create tests that call private helpers directly. This keeps tests focused on supported behaviour and allows internal implementations to evolve.
New behaviour and bug fixes must include tests that cover the changed paths. Behaviour-preserving refactors may rely on existing public-API tests when those tests already exercise the refactored paths.
Coverage is enabled automatically by the pytest configuration:
uv run pytest -qThe command prints a term-missing report. Check its missing-line output before
opening a pull request and keep new code covered; no additional coverage flags
are needed. @overload and if TYPE_CHECKING: blocks are excluded from
coverage, so do not add tests solely to execute those blocks.
Install the hooks once per clone:
uv run pre-commit installThey then run automatically on git commit. Always run the complete suite
before committing:
uv run pre-commit run --all-filesFor a focused local iteration, run one hook or a selected set of files:
uv run pre-commit run ruff-check --all-files
uv run pre-commit run --files city2graph/graph.py tests/test_graph.pyThe configured checks cover:
- Python AST, TOML, and YAML syntax;
- case conflicts, merge-conflict markers, and private keys;
- executable and shebang consistency;
- byte-order marks, mixed line endings, trailing whitespace, and final newlines;
- strict YAML linting;
- NumPy-style docstrings in
city2graph/; - Ruff linting with automatic fixes and Ruff formatting;
- strict mypy type checking; and
- protection against direct commits to protected branches.
Some hooks modify files automatically. Review those changes, stage them, and rerun the full suite until every hook passes. Do not bypass failed checks.
Update the relevant files under docs/ for new features or significant
behaviour changes. Add or update examples when they materially help users
understand a feature.
Install the documentation dependencies and build the site before submitting documentation changes:
uv sync --extra cpu --group dev --group docs
uv run --no-sync mkdocs build --strictSync both groups once. default-groups is empty, so a plain uv sync --group docs
removes the dev packages, and the next test run reinstalls them. Alternating
the two commands rebuilds the environment on every switch. --no-sync skips the
environment check on each documentation command.
For a local preview, run:
uv run --no-sync mkdocs serveThen open http://127.0.0.1:8000/.
The build checks internal links, anchors, and static assets, including notebook images and videos. It also extracts notebook plots and shared stylesheets into cacheable files without changing notebook calculations or saved outputs.
To run the Chromium smoke tests used by the documentation CI:
uv run --no-sync playwright install chromium
uv run --no-sync mkdocs build --strict
CITY2GRAPH_DOCS_SITE=site uv run --no-sync pytest -q tests/test_docs.py tests/test_docs_browser.pyThese checks cover instant navigation, search, copying code, maths, version
selection, and mobile and desktop layouts in both colour schemes. The browser
tests are skipped by the regular test suite unless CITY2GRAPH_DOCS_SITE is set.
Push your branch to your fork and open a pull request against
c2g-dev/city2graph:main:
git push -u origin your-change-nameFollow the repository's pull request template:
- Summary: explain what changed and why.
- Related issues: link issues with closing keywords when appropriate, or state that none apply.
- Testing: list the exact automated and manual checks run; explain any check that was not run.
- Documentation: identify documentation changes, or write "Not applicable".
- Reviewer notes: call out compatibility concerns, trade-offs, or areas deserving particular attention.
Both uv run pytest -q and uv run pre-commit run --all-files must pass before
the contribution is committed. Documentation changes must also pass
uv run mkdocs build.