Contributing¶
Thanks for your interest. gbfs-toolkit is a focused, research-grade library; contributions
that keep it that way are very welcome.
Setup¶
Scope¶
The library is deliberately bounded. In scope: ingesting/normalising GBFS, semantic & dynamic
quality audit, longitudinal panels, descriptive statistics, geospatial joins. Out of scope
(by design, see METHODOLOGY.md): routing/isochrones, OD/trip inference,
demand prediction or imputation, schedulers/daemons, and interactive visualisation. The library
returns tidy DataFrame/GeoDataFrame; you bring the model and the map.
Conventions¶
- Pure functions on canonical frames (mirrored as
.gbfsaccessor methods). No hidden global state. Validate inputs withrequire_columnsso a bad frame raises a clearSchemaError. - Tz-aware UTC timestamps and nullable dtypes everywhere; never silently impute.
- Optional dependencies stay behind extras and lazy imports, so the core is numpy/scipy/pandas only.
- New behaviour needs a test; keep coverage ≥ 85% (CI enforces it). Run
ruffbefore pushing. - Document any methodological assumption or threshold in
METHODOLOGY.md. - Performance benchmarks live in
benchmarks/(outside the test suite). Run them withpytest benchmarks/ --benchmark-only. CI runs them informationally and uploads the results; if you touch a hot path (spatial neighbour queries, panel groupbys, the per-snapshot loops invehicle_id_persistence/spatial_outage_redundancy), check the numbers before and after.
Docstring standard¶
Docstrings are the API reference: mkdocstrings renders them on the site, pytest
--doctest-modules runs their examples, and interrogate (fail-under 90) gates
coverage. Every public function uses NumPy style with this section order, and
only the sections it needs:
- Summary line — one imperative sentence, ≤ 90 characters, on the first line.
- Extended description — the why: the research question it answers, the pitfall it avoids, the scope boundary. This "why first" paragraph is the house style; it is what makes the reference read like documentation, not a signature dump.
- Parameters — every argument, with type and meaning.
- Returns — type and shape (name the columns / index of a returned frame).
- Raises — when the function validates and rejects input.
- Examples — required on any public function that takes a business frame
(info / status / panel / GeoDataFrame) and returns a frame, a Series, or changes
state. Make it self-contained and deterministic: build a 2–20 row frame
inline (never load a dataset), add
# doctest: +NORMALIZE_WHITESPACEfor any DataFrame output, and wrap numeric returns infloat(...)/round(...)or test a stable property — never assert a raw float (it prints asnp.float64(...)). - References — the canonical paper for any non-trivial algorithm.
Exempt from the Examples rule: internal helpers, trivial property accessors, pure
utilities, and network functions (fetch*, systems_catalog).
Worked examples that need more than one function, real data, or a figure are
not docstrings: a task-oriented pipeline is a runnable script under examples/,
included into a How-To page with the --8<-- snippet syntax (one source of truth,
linted and run), and an end-to-end narrative is a notebook executed by nbmake.
Reporting issues¶
Please separate two distinct kinds of report:
- Software defects (a crash, a wrong result, a packaging problem) belong in the
issue tracker. Include
show_versions()output and a minimal reproducer. - Methodological disputes (a station you believe the A1–A7 audit flags or misses incorrectly)
concern the taxonomy itself, which is defined by the companion dataset
gbfs-audit-catalogue. Raise those there, with the feed and station, so the operational definition and the implementation stay in step.
Pull requests¶
Keep PRs focused, describe the why, and update CHANGELOG.md. If a change is breaking, say so
and provide the migration.