Principle:Mlflow Mlflow API Compatibility Checking
| Knowledge Sources | |
|---|---|
| Domains | API Stability, Backward Compatibility |
| Last Updated | 2026-02-13 20:00 GMT |
Overview
Automated detection of backward-incompatible changes in public function signatures by comparing AST-parsed signatures between a base branch and the current working tree.
Description
Public APIs must evolve without breaking existing callers. This principle defines a systematic approach to detecting signature-level breaking changes before they reach production. The system works by extracting function signatures from the base branch (typically the main development branch) and the current branch, then comparing them according to a formal set of compatibility rules.
The signature extraction phase uses AST parsing to build a map from qualified function names to their parameter lists, including positional parameters, positional-only parameters, keyword-only parameters, and the presence of variadic (*args, **kwargs) collectors. Nested class methods are represented with dotted names. Private functions (those with a leading underscore that are not dunder methods) and functions within private classes are excluded, since they are not part of the public API contract.
The comparison phase applies a set of compatibility rules independently to positional and keyword-only parameter groups. Positional parameters are order-sensitive: renaming, reordering, or removing any existing positional parameter is flagged as breaking. Adding new required positional parameters is also breaking, while adding optional ones at the end is permitted. Making a previously optional parameter required is breaking. Keyword-only parameters are compared in an order-agnostic manner: removing or renaming one is breaking, promoting an optional keyword-only parameter to required is breaking, and adding a new required keyword-only parameter is breaking. Adding optional keyword-only parameters is always safe.
Only files within the public module namespace are checked. Files in private modules (those with leading-underscore directory or file names, excluding __init__.py) are skipped. The system is designed for CI integration, producing structured error messages that include file path, line number, column, and a description of the breaking change with the affected function name.
Usage
This principle applies as a pull request check in continuous integration. It warns contributors when their changes alter the signatures of public functions in ways that would break existing callers. The warnings are non-blocking but clearly indicate which function calls would fail, allowing maintainers to decide whether the change is intentional (a deliberate breaking change) or accidental.
Theoretical Basis
The compatibility checking algorithm operates in three phases:
Phase 1: File Discovery
- Use git diff to find Python files changed between the base branch and HEAD
- Filter to files under the public module namespace
- Exclude private modules and non-Python files
Phase 2: Signature Extraction (per file)
- Parse the file content into an AST
- Walk the tree, collecting FunctionDef and AsyncFunctionDef nodes
- Build qualified names using the class nesting stack
- Skip private functions and functions in private classes
- Extract parameter info: name, position, required/optional, positional-only, keyword-only
Phase 3: Compatibility Comparison (per function pair)
For positional parameters (order matters):
For each old parameter at index i:
- If no new parameter exists at index i: REMOVED (breaking)
- If new parameter name differs: RENAMED/REORDERED (breaking, stop checking further)
- If old was optional and new is required: BECAME REQUIRED (breaking)
For each new parameter beyond old count:
- If required: NEW REQUIRED PARAMETER (breaking)
For keyword-only parameters (order does not matter):
old_names = set of old keyword-only parameter names
new_names = set of new keyword-only parameter names
- For names in (old_names - new_names): REMOVED (breaking)
- For names in intersection where optional became required: BECAME REQUIRED (breaking)
- For names in (new_names - old_names) where required: NEW REQUIRED (breaking)
This formalization ensures that all safe evolution paths (adding optional parameters, adding keyword-only optional parameters) are permitted while all unsafe paths are flagged.