diff --git a/AGENTS.md b/AGENTS.md index 9e14bba0e1c..0cae881a67f 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -8,7 +8,14 @@ - Follow the code patterns that already exist in the file you are editing, in similar layers when editing a layer (in both `layers/` or `contrib/`) or in the rest of the project. Some of those guidelines are detailed below. - Do not declare functions for very simple checks or operations. Prefer code readability over trying to reduce code duplication. - Never declare a function that is only used once, unless it is meant to be a public API. -- Avoid silent exception suppression (`try: ... except Exception: pass` or bare `except: pass`). Catch specific exception types (e.g., `(AttributeError, OSError)`). When the exception is unexpected, log the caught exception using `scapy.error.log_runtime.debug(...)` or the module's child logger (e.g., `log_j1939.debug(...)`), or document explicitly why suppression is necessary. Use WARNING or above only against bugs or unexpected behaviors. +- Avoid silent exception suppression (`try: ... except Exception: pass` or bare `except: pass`). Catch specific exception types (e.g., `(AttributeError, OSError)`). When the exception is unexpected, log the caught exception using `scapy.error.log_runtime.debug(...)` or the module's child logger (e.g., `j1939_log.debug(...)`), or document explicitly why suppression is necessary. Use WARNING or above only against bugs or unexpected behaviors. +- Do not introduce backward-compatibility alias redefinitions for new or modified symbols introduced within the current branch or PR. Rename symbols directly at their original definition site and update all references across the codebase. +- Adhere strictly to protocol prefix naming conventions: prefix lowercase functions and module-level variables with `_` (e.g., `j1939_scan`, `j1939_log`), uppercase constants and registries with `_` (e.g., `J1939_GLOBAL_ADDRESS`, `J1939_MANUFACTURERS`), and classes with `` (e.g., `J1939NativeSocket`). +- Never import internal methods or constants (those starting with a leading underscore) across modules. If a function or constant is shared across multiple modules, make it public by removing the leading underscore and prefixing it with the protocol prefix. +- Dataclasses must be used strictly as dataclasses. Do not implement dictionary emulation methods (`__getitem__`, `get`, `keys`, `values`, `items`, etc.) on dataclasses. Use `dataclasses.asdict()` or attribute access when dictionary operations are required. +- Place all imports at the top of the file. Do not use local/deferred imports inside functions or methods unless strictly required to prevent circular import dependencies. +- Keep all import blocks and `__all__` lists sorted alphabetically. +- Packet layer classes (`Packet` subclasses) bound to other protocols must declare explicit `bind_layers()` bindings. ## Put code in the right place