Skip to content

Contributing#

If you'd like to add checks to flag new areas, please update this documentation and add an integration test.

Adding a check#

  1. Add a SQL file named after the check (fct_<what_is_checked>.sql) in the folder of its category under checks/ (modeling, testing, documentation, structure, performance or governance). The query returns one row per violation, with the resource to fix in the column unique_id, and no row when the check passes. Build it on the shared relations evaluator_models(), evaluator_sources() and evaluator_edges() from macros/checks/, so that the exclusions (exclude_packages, exclude_paths_from_project) and the disabled resources are handled, and wrap the query in {% set violations %}…{% endset %} followed by {{ evaluator_exceptions('<check name>', violations) }} so that exceptions apply (see any existing check, and add its name to evaluator_check_names()).
  2. Describe it in the YAML file of the folder (_<category>__checks.yml). Add selection_filter_on: none to its config if it measures the whole project rather than individual resources.
  3. Add the case it should flag to the project integration_tests_checks/violations/ and the number of violations expected in its expected_violations.csv.
  4. Document the rule in the page of its category under docs/rules/ and in the list of rules.

Running the integration tests#

The checks run locally and don't need a warehouse. You need dbt >=2.0.0 and then run

./integration_tests_checks/run_checks.sh

The script installs the package in each project of integration_tests_checks/ (violations and the parity_1x* projects ported from the 1.x integration tests), runs dbt check and compares the number of violations of each check with the expected_violations.csv of the project. test_exceptions.sh then tests the exceptions.

Running docs locally#

Docs are generated using Zensical, configured in zensical.toml. To test them locally, run the following command:

uvx zensical serve

To check that the site builds without warnings, run uvx zensical build --strict.

Docs are then automatically pushed to the website as part of our CI/CD process. We use Zensical's fork of mike as part of the process to publish different versions of the docs.

Diagrams can be written as Mermaid charts in code blocks with the language mermaid, and are rendered by the site.

  • markdownlint

    • Highlight issues with the Markdown code

    • The config used in .vscode/settings.json is the following:

      "markdownlint.config": {
    "ul-indent": {"indent": 4},
    "MD036": false,
    "MD046": false,
}

  • Mardown All in One

    • Makes it easy to paste links on top of text to create markdown links