Development notes

Even tough Rust comes with its own cargo build tool, this project uses some build-time created caches, so always run make after changing the code and before using it.

Coding style

  • Build HTML strings using yattag, return a yattag::Doc if the result is an escaped string.

  • Path handling: make relative paths absolute using context::Context::get_abspath().

This has the benefit that real and test config/data (under / and tests/) can be separated via a single parameter to the context::Context constructor.

  • Try to keep module size under 1000 lines to avoid monster modules:
for i in $(git ls-files|grep rs$|grep -v tests.rs); do lines=$(wc -l < $i); if [ $lines -gt 1000 ]; then echo "$i is too large: $lines lines"; fi; done
  • Try to make JS optional. If a link can be handled with and without JS, then generate HTML which goes to the no-JS version, then JS can tweak the DOM to invoke JS instead.

TS debugging

Bundled JS can be minified (for production) and also source maps can be added (for debugging). The default output is for production, but touching a TS source file and invoking:

make TSDEBUG=1

produces output that is for debugging.

Rust debugging

make defaults to release builds. To switch to a debug build:

rm -rf target/
echo RSDEBUG=1 > config.mak
make

To run a single test:

RUST_BACKTRACE=1 cargo test --lib -- --exact --nocapture wsgi_json::tests::test_missing_streets_update_result_json

Tests follow the Favor real dependencies for unit testing pattern, i.e. apart from filesystem, network or time (see src/context.rs for the exact list), no mocking is used.

Debugging workdir/stats/stats.json generation:

cargo run -- cron --mode stats --no-overpass

Rust performance profiling

The symbols profile enables debug symbols while keeping optimizations on:

cargo build --profile symbols
valgrind --tool=callgrind target/symbols/osm-gimmisn missing_housenumbers budapest_11

YAML schema

The YAML schema is meant to provide reference documentation in the long run, so guide/src/usage.md can focus on tutorial documentation.

ajv validate -s data/relations.schema.yaml -d data/relations.yaml
for i in data/relation-*.yaml; do ajv validate -s data/relation.schema.yaml -d $i || break; done

Checklist

Ideally CI checks everything before a commit hits master, but here are a few things which are not part of CI: