Add bc decorator

tools/stronghold/src/api/compatibility.py

@@ -6,6 +6,7 @@
 import pathlib
 import tempfile
 from collections.abc import Iterable, Mapping, Sequence
+import ast
 
 import api
 import api.ast
@@ -71,10 +72,25 @@ def check(
     before_api = api.ast.extract(before)
     after_api = api.ast.extract(after)
 
+    before_raw = api.ast.extract_raw(before)
+    after_raw = api.ast.extract_raw(after)
+
+    disabled_funcs = {
+        name
+        for name, node in before_raw.items()
+        if _decorator_disables(node)
+    } | {
+        name
+        for name, node in after_raw.items()
+        if _decorator_disables(node)
+    }
+
     violations: list[api.violations.Violation] = []
     for name, before_def in before_api.items():
         if any(token.startswith("_") for token in name.split(".")):
             continue
+        if name in disabled_funcs:
+            continue
 
         after_def = after_api.get(name)
         if after_def is None:
@@ -320,3 +336,43 @@ def _check_type_compatibility(
                 return False
 
     return True
+
+
+def _decorator_disables(node: ast.FunctionDef) -> bool:
+    """Returns True if the bc_linter.check_compat decorator disables checks."""
+
+    for deco in node.decorator_list:
+        name = _decorator_name(deco)
+        if name != "bc_linter.check_compat":
+            continue
+
+        enable = True
+        if isinstance(deco, ast.Call):
+            # Look for keyword argument ``enable`` first
+            for kw in deco.keywords:
+                if kw.arg == "enable" and isinstance(kw.value, ast.Constant):
+                    enable = bool(kw.value.value)
+                    break
+            else:
+                if len(deco.args) == 1 and isinstance(deco.args[0], ast.Constant):
+                    enable = bool(deco.args[0].value)
+
+        return not enable
+
+    return False
+
+
+def _decorator_name(expr: ast.expr) -> str | None:
+    """Returns dotted name of decorator if easily determined."""
+
+    if isinstance(expr, ast.Call):
+        expr = expr.func
+
+    if isinstance(expr, ast.Name):
+        return expr.id
+    if isinstance(expr, ast.Attribute):
+        value = _decorator_name(expr.value)
+        if value is None:
+            return None
+        return value + "." + expr.attr
+    return None

tools/stronghold/src/bc_linter.py

@@ -0,0 +1,22 @@
+"""Utilities for marking API compatibility checks."""
+
+from __future__ import annotations
+
+from typing import Callable, TypeVar, Any
+
+F = TypeVar("F", bound=Callable[..., Any])
+
+
+def check_compat(*, enable: bool = True) -> Callable[[F], F]:
+    """Decorator used by stronghold to toggle API compatibility checks.
+
+    When ``enable`` is ``False`` the decorated function will be skipped by the
+    backward compatibility linter.
+    """
+
+    def decorator(func: F) -> F:
+        setattr(func, "_bc_linter_enable", enable)
+        return func
+
+    return decorator
+

tools/stronghold/tests/api/test_compatibility.py

@@ -6,6 +6,7 @@
 import api.violations
 import pytest
 from testing import git, source
+import bc_linter
 
 
 def test_deleted_function(tmp_path: pathlib.Path) -> None:
@@ -520,3 +521,36 @@ def will_be_deleted():
             api.violations.FunctionDeleted(func="will_be_deleted", line=1)
         ],
     }
+
+
+def test_check_disable_decorator(tmp_path: pathlib.Path) -> None:
+    @bc_linter.check_compat(enable=False)
+    def func(x: int) -> None:
+        pass  # pragma: no cover
+
+    before = source.make_file(tmp_path, func)
+
+    @bc_linter.check_compat(enable=False)
+    def func(x: int, y: int) -> None:  # type: ignore[no-redef]
+        pass  # pragma: no cover
+
+    after = source.make_file(tmp_path, func)
+
+    assert api.compatibility.check(before, after) == []
+
+def test_check_enable_decorator(tmp_path: pathlib.Path) -> None:
+    @bc_linter.check_compat(enable=True)
+    def func(x: int) -> None:
+        pass  # pragma: no cover
+
+    before = source.make_file(tmp_path, func)
+
+    @bc_linter.check_compat(enable=True)
+    def func(x: int, y: int) -> None:  # type: ignore[no-redef]
+        pass  # pragma: no cover
+
+    after = source.make_file(tmp_path, func)
+
+    assert api.compatibility.check(before, after) == [
+        api.violations.ParameterNowRequired(func=func.__name__, parameter="y", line=2)
+    ]

tools/stronghold/tests/bc_linter_vllm.md

@@ -0,0 +1,13 @@
+# BC Linter for vLLM
+PR: https://github.com/vllm-project/vllm/pull/21234
+
+## Code Path
+Cover the following code path:
+- vllm/v1/attetion/**
+- vllm/v1/core/**
+
+Additionally, we should have flexibility to cover other code path in the future.
+
+## Lint Rules
+- Check backward compatibility for dataclasses/functions defined python files in code path above
+- The default behavior for linter is to check all the dataclasses/public functions in the code path, but we provide an option to skip bc-linter for some experimental dataclasses/functions with `@bc_linter_skip` decorator