Dev How-to

Coding Guidelines

LogML coding guide is based on Google Python Style Guide, adjusting it when needed.

Lint

LogML provides .pylintrc file in the base of its repository, which contains set of default rules and exceptions for LogML.

Pylint is installed into logml conda environment.

Command to run locally:

python -m pylint --output-format=parseable \
                        --fail-under=9.75 \
                        --msg-template="{path}:{line}: [{msg_id}({symbol}), {obj}] {msg}" \
                        ./src \
                        | tee pylint.log || echo "pylint exited with \$?"

Coding style

Test width is 100 (preferred), 120 (max) symbols.

Dependencies

Put all EligibleXXX items into one package, single level.

Use import_submodules in the package __init__.py file to import modules at a single level.

Everywhere: defer importing all EligibleXXX items, due to the fact that they perform blanket-style import and can import half of the application along.

Unit Testing

Always run ./scripts/run_tests.sh and make sure all the tests are green prior to pushing your changes to the repository.

External Dependency Management

Please update ./environment.yaml each time you install and import a new package.

Exact package version should always be specified (e.g. gensim=3.4.0).

Config schema updates

When working with config, it can be hard to detect exact changes in schema. To make this task easier, we store latest config schema in git, so we can track it.

Invoke the command to generate schema before creating PR:

python log_ml.py config print-schema -o schema/logml_config_schema.yaml

Build Sphinx documentation

Having logml conda environment active, open docs folder, and use the following command:

rm -r pages/dev/generated_refs/* && make clean && make html

to rebuild documentation from scratch. (or just make html to make incremental build).

Entry point is docs/_build/html/index.html.