linting-and-formatting

SKILL.md preview

---
name: linting-and-formatting
description: Code style and quality rules for Megatron Bridge — ruff configuration, naming conventions, type hints, mypy rules, docstrings, copyright headers, logging, and the code review checklist.
when_to_use: Writing or reviewing code for style compliance, fixing ruff or mypy errors, pre-commit hook failures, copyright header questions, naming or docstring conventions.
---

# Linting and Formatting

Single source of truth for code style in Megatron Bridge. Read this before
writing new code or reviewing PRs.

## Style Guides

- Python: [Google Python Style Guide](https://google.github.io/styleguide/pyguide.html)
- Shell: [Google Shell Style Guide](https://google.github.io/styleguide/shellguide.html)

Target Python 3.10+.

## Formatting and Linting

Run before every commit:

```bash
uv run ruff check --fix .
uv run ruff format .
```

Pre-commit hooks run these automatically. If hooks auto-fix files, re-stage
and re-run until clean:

```bash
git add -u
pre-commit run
# if it auto-fixed files:
git add -u
pre-commit run
```

### Ruff Rules (from `ruff.toml`)

| Rule | ID | Description |
|---|---|---|
| Line length | — | 119 characters (formatter) |
| Quote style | — | Double quotes |
| f-string without placeholders | F541 | Error |
| Unused local variable | F841 | Auto-removed by `--fix` |
| Unused import | F401 | Auto-removed by `--fix` (ignored in `__init__.py`) |
| Ambiguous variable name | E741 | Error (e.g., `l`, `O`, `I`) |
| Undefined name | F821 | Error |
| Block comment format | E266 | Error (too many `#`) |
| Import sorting | I | isort-compatible, auto-fixed |
| Public class docstring | D101 | Warning (ignored in test files) |
| Public function docstring | D103 | Warning (ignored in test files) |

**Per-file overrides:**
- `__init__.py`: F401 and F403 ignored (re-exports expected).
- `test_*.py`, `*_test.py`, `tests/*.py`: D101 and D103 ignored.

## Naming Conventions

| Kind | Convention | Example |
|---|---|---|
| Files | snake_case | `model_bridge.py` |
| Classes | PascalCase | `MegatronModelBridge` |
| Functions/methods | snake_case | `load_weights_hf_to_megatron` |
| Local variables | snake_case | `megatron_weights` |
| Variables starting with digit | prefix `k` | `k_99th_percentile` |
| Global variables | UPPER_SNAKE + prefix `G` | `G_LOGGER` |
| Constants | UPPER_SNAKE | `DEFAULT_HIDDEN_SIZE` |

- Avoid shadowing variables from an outer scope.
- Initialize all externally visible class members in the constructor.

## Import Order

1. `__future__` imports
2. Standard library
3. Third-party (`megatron.core`, `torch`, `transformers`, etc.)
4. First-party (`megatron.bridge.*`)
5. Local folder imports

Separate groups with blank lines. ruff auto-fixes via the `I` rule.

## Type Hints

Required on all public API functions and methods.

- Use `T | None` instead of `Optional[T]`
- Use `X | Y` instead of `Union[X, Y]`
- Use built-in generics (`list`, `dict`, `tuple`) instead of `typing` equivalents

```python
def get_module_by_name(
    model: torch.nn.Module,
    name: str,
    default: torch.nn.Module | None = None,
) -> torch.nn.Module | None:
    ...
```

### Mypy

Run on changed files before submitting:

```bash
uv run mypy --strict path/to/file.py
```

Key rules:

- **No `Any` leaks** — use `object` for unknown types or a `TypeVar` for generics.
- **No untyped defs** — every function must have parameter and return annotations.
- **No implicit `Optional`** — write `x: int | None = None`, never `x: int = None`.
- **Explicit casts** — use `typing.cast()` only when inference fails; add a comment.
- **Typed dictionaries** — prefer `TypedDict` over `dict[str, Any]` for structured dicts.
- **Callable signatures** — use `Callable[[ArgType], ReturnType]` or `Protocol`.
- **Ignore sparingly** — `# type: ignore[code]` must include the error code and justification.

## Keyword-Only Arguments for Ambiguous Parameters

When a function has multiple parameters of the same type that could be swapped


…