Add a new TRF rule to the mlinter. Checks for duplicates, creates the rule module and TOML entry, runs against all models, and handles violations (fix or allowlist).
<description>: Natural-language description of what the rule should detect.ast module). NEVER import runtime libraries like torch, tensorflow, etc.check(tree, file_path, source_lines) -> list[Violation] interface.RULE_ID module constant (set automatically by discovery) instead of hardcoding the rule ID string.Check for duplicate rules in utils/mlinter/rules.toml:
Determine the next rule number:
utils/mlinter/trf*.py files and find the highest number.TRF014).Add the TOML entry to utils/mlinter/rules.toml:
[rules.TRFXXX] section at the end of the file with:
description - one-line summarydefault_enabled = trueallowlist_models = [][rules.TRFXXX.explanation] with what_it_does, why_bad, bad_example, good_exampleCreate the rule module at utils/mlinter/trfXXX.py:
trf*.py)."""TRFXXX: <short description>."""ast, Path, and needed helpers from ._helpers.RULE_ID = "" # Set by discovery.def check(tree: ast.Module, file_path: Path, source_lines: list[str]) -> list[Violation]:.utils/mlinter/trf*.py for patterns and helpers.Run the rule against all models:
python -m utils.mlinter --enable-rules TRFXXX
Handle violations:
allowlist_models in rules.toml?"allowlist_models list in the TOML entry.Add tests in tests/repo_utils/test_mlinter.py:
mlinter.analyze_file(), and assert on violations.tempfile.TemporaryDirectory to create real file structures. The test file already imports tempfile.python -m pytest tests/repo_utils/test_mlinter.py -x -v -k "trfXXX"
Final validation:
make style
make check-repo
The mlinter processes files one at a time via analyze_file(file_path, text, enabled_rules). When a rule needs cross-file information, the rule module must read the other file from disk. Be aware of these patterns:
Some model directories contain multiple configuration files (e.g., data2vec/ has configuration_data2vec_audio.py, configuration_data2vec_text.py, configuration_data2vec_vision.py). When finding a config file for a modeling file, match by suffix first: modeling_foo_text.py -> configuration_foo_text.py. Only fall back to picking the first config file if there's a single one or no suffix match. See trf014.py:_find_config_file() for the pattern.
A single configuration_*.py file can define multiple config classes (e.g., a main config plus text/vision sub-configs). If the rule is checking a property that should belong to one specific config class, do not scan the file and accept the first matching class. First resolve the modeling class's target config class:
config_class from the model class, following local modeling inheritance if it is declared on a parent *PreTrainedModel.config_class, infer the best match from class names, typically by longest shared prefix (FooTextForCausalLM -> FooTextConfig, not FooConfig).Then validate only that config class. This avoids early-return bugs where an unrelated sub-config masks a missing field on the actual target config.
Some config classes inherit from another model's config rather than directly from PreTrainedConfig (e.g., VoxtralRealtimeTextConfig(MistralConfig)). These inherit fields like tie_word_embeddings from their parent. When checking for a field in a config class, if the base class is not PreTrainedConfig/PretrainedConfig and ends with Config, assume the field may be inherited and skip the violation.
Models like janus, perception_lm, pe_audio_video use composite configs with sub_configs = {"text_config": AutoConfig, "vision_config": ...}. Text-related fields (like tie_word_embeddings) live in the text sub-config (e.g., LlamaConfig), not in the composite config itself. When checking for a text-related field, if the config class has a sub_configs dict containing "text_config", the field is delegated to the sub-config and should not be flagged.
tie_word_embeddings is NOT in PreTrainedConfigThe base PreTrainedConfig in src/transformers/configuration_utils.py does not define tie_word_embeddings. Each model config must define it explicitly (as a class attribute like tie_word_embeddings: bool = True, or via self.tie_word_embeddings = ... in __init__/__post_init__).
utils/mlinter/trf*.pyutils/mlinter/rules.tomlutils/mlinter/_helpers.py (Violation, iter_pretrained_classes, _has_rule_suppression, _class_methods, _get_class_assignments, full_name, _simple_name, etc.)tests/repo_utils/test_mlinter.pyutils/mlinter/README.md