CONTRIBUTING.md

Contributing to MetricFlow

Welcome to the MetricFlow developer community, we're thrilled to have you aboard!

Before you get started, please...

1. Familiarize yourself with our Code of Conduct. In summary - be kind to each other. We're all here trying to make the data world a better place to work.
2. Make sure you can sign our Contributor License Agreement. Unfortunately, we cannot accept PRs unless you have signed. If you are not able to sign the agreement you may still participate in our Slack community or interact with Issues. To sign the agreement simply put up a PR, and you will receive instructions there.

Before you write any code

For interface changes, open an issue first.

If your contribution would add, remove, or modify any public interface — including query APIs, semantic manifest schemas, metric/dimension/entity definitions, CLI commands, or any other surface that downstream tools or users depend on — please open a GitHub issue for discussion before writing code.

Interface changes have broad impact across dbt Labs tools and the wider ecosystem, and the Semantic Layer engineering team needs to be part of that conversation early. PRs that introduce interface changes without prior discussion are very likely to be declined or sent back for significant rework, regardless of implementation quality. We want your time to be well-spent, and a brief issue thread upfront saves everyone effort.

If you're not sure whether your change qualifies, err on the side of opening an issue. We're happy to help you figure out the right approach.

Environment setup

1. Ensure you have a relevant version of Python.
2. You may need to install the following required system dependencies:
   • MySqlClient:
     • Follow the instructions from MySQL
     • Mac users might prefer to use Homebrew: brew install mysql
   • Postgres:
     • Postgres provides pre-built packages for download and installation
     • Mac users might prefer to use Homebrew: brew install postgresql
   • Docker:
     • This is only required if you are developing with Postgres.
     • Follow the instructions from Docker
3. Create a fork of the MetricFlow repo and clone it locally.
4. Install Hatch via make install-hatch - this is the tool we use to manage our build dependencies.

Start testing and development

You're ready to start! Note all make and hatch commands should be run from your repository root unless otherwise indicated.

pyproject.yaml includes a definition for a Hatch environment named dev-env that is similar to a virtual environment and allows packages to be installed in isolation. The Makefile includes a number of other useful commands as well, such as make test, which handle the environment switching. For engine-specific testing refer to the <engine>-env environments defined in pyproject.yaml and the test-<engine> commands in the Makefile - for example, postgres tests are most easily run through the postgres-env instead of dev-env, or via make test-postgresql.

When running any one of the hatch commands, the environment is automatically set up for you.

1. Run some tests to make sure things happen:

   • Run the full test suite: make test
   • Run a subset of tests based on path: hatch run dev-env:pytest tests/plan_conversion
   • Run a subset of tests based on test name substring: hatch run dev-env:pytest -k "query" tests

2. Now you may wish to break some tests. Make some local changes and run the relevant tests again and see if you broke them!

   • Working with integration tests
     • These tests are driven by a set of test configs in tests_metricflow/integration/test_cases. They compare the output of a MetricFlow query against the output of a similar SQL query.
     • These tests all run on consistent input data, which is created in the target warehouse via setup fixtures.
       • Modify the test inputs for one of the test models if you are looking to test boundary cases involving things like repeated rows of data.
     • Let's break a test!
       • Change a SQL query inside of tests_metricflow/integration/test_cases/itest_simple.yaml
       • Run the test case: hatch run dev-env:pytest -k "itest_simple" tests/integration. Did it fail?
   • Working with module and component tests
     • These are generally laid out in a similar hierarchy to the main package.
     • Let's try them out:
       • Run the dataflow plan to sql plan conversion tests: hatch run dev-env:pytest tests_metricflow/plan_conversion/test_dataflow_to_sql_plan.py.
       • Modify something in the dataflow to sql plan converter logic. I like to throw exceptions just to make sure things blow up.
       • Run the test again. Did anything break?
   • Remember to clean up when you're done playing with the tests!

3. Make changes to the codebase and verify them through further testing, including test runs against other warehouse engines.

   • To run tests against other engines you MUST have read and write access to an instance of the execution engine and database.
   • Run the following commands in your shell, replacing the tags with the appropriate values:
     • export MF_SQL_ENGINE_URL=<YOUR_WAREHOUSE_CONNECTION_URL>
     • export MF_SQL_ENGINE_PASSWORD=<YOUR_WAREHOUSE_PASSWORD>
   • Run make test-<engine> to execute the entire test suite against the target engine. This will pull in and configure the necessary dependencies for query execution. For example, to run tests against BigQuery, run make test-bigquery
   • By default, without MF_SQL_ENGINE_URL and MF_SQL_ENGINE_PASSWORD set, your tests will run against DuckDB.

4. Run the linters with make lint. We use:

   • Black for formatting
   • Ruff for general Python linting
   • MyPy for typechecking

   Linting must pass before you open a PR — CI will enforce this, and PRs with lint failures won't be reviewed until they're clean. Running it locally before pushing saves you a round trip.

5. To see how your changes work with more interactive queries, use your repo-local CLI.

   • Run hatch run dev-env:mf --help
   • Follow the CLI help from there, just remember your local CLI is always hatch run dev-env:run mf <COMMAND>!
   • Note this will only work if you invoke the command from within a properly configured dbt project, so it may be simpler to clone the jaffle-sl-template repo and do an editable install (via pip install -e /path/to/metricflow/repo) in a separate Python virtual environment.

6. Some tests generate snapshots in the test directory. Separate snapshots may be generated for each SQL engine. You can regenerate these snapshots by running make regenerate-test-snapshots.

Adding or modifying a CHANGELOG Entry!

We use changie to generate CHANGELOG entries. Note: Do not edit the CHANGELOG.md directly. Your modifications will be lost.

In order to use it, you can:

1. Follow the steps to install changie for your system.
2. Once changie is installed, run changie new before opening your PR and changie will walk you through the process of creating a changelog entry.
3. Commit the file that's created and your changelog entry is complete!
4. (Optional if contributing to a feature in progress) Modify the changie yaml file in metricflow/.changes/unreleased/ related to your change. If you need help finding this file, please ask within the discussion for the pull request!

You don't need to worry about which metricflow version your change will go into. Just create the changelog entry with changie, and open your PR against the main branch. All merged changes will be included in the next minor version of metricflow. The maintainers may choose to "backport" specific changes in order to patch older minor versions. In that case, a maintainer will take care of that backport after merging your PR, before releasing the new version of metricflow.

Submit your contribution!

1. Rebase your branch onto the latest main before opening your PR: git fetch upstream && git rebase upstream/main. Keep your branch up to date with main throughout the review process as well — we prefer rebase over merge commits to keep history clean.

2. Make a well-formed Pull Request (PR) from your fork into the main MetricFlow repository. If you're not clear on what a well-formed PR looks like, fear not! We will help you here and throughout the review process.

   A PR should do one thing. This is the single most important rule for getting a timely, high-quality review. A PR that mixes a bug fix, a refactor, and a new feature is much harder to review carefully — and mistakes are more likely to slip through. If you find yourself writing "also" or "while I was in here..." in your PR description, that's a signal to split.

   • Well-formed PRs are composed of one or more well-formed commits, and include clear indications of how they were tested and verified prior to submission. PRs that add new behavior or fix bugs must include tests. We will ask you to add them if they're missing, so save yourself the round trip.
   • Use commits to tell the story of your PR. When a PR involves multiple logical steps — for example, first refactoring an internal structure, then adding new behavior on top — break those into separate commits. A reviewer should be able to read through your commits in order and understand how you arrived at the final state. Squashing everything into a single commit is fine for trivial changes, but obscures the reasoning for anything non-trivial.
   • Well-formed commits are focused (loosely speaking they do one conceptual thing) and well-described.
   • A good commit message — like a good PR message — will have three components:
     1. A succinct title explaining what the commit does
     2. A separate body describing WHY the change is being made
     3. Additional detail on what the commit does, if needed
   • We want this because we believe the hardest part of a collaborative software project is not getting the computer to do what it's supposed to do. It's communicating to a human reader what you meant for the computer to do (and why!), and also getting the computer to do that thing.
   • This helps you too — well-formed PRs get reviewed a lot faster and a lot more productively. We want your contribution experience to be as smooth as possible and this helps immensely!

3. One of our core contributors will review your PR and either approve it or send it back with requests for updates

4. Once the PR has been approved, our core contributors will merge it into the main project.

5. You will get a shoutout in our changelog/release notes. Thank you for your contribution!