From d01bff4161bd2fb4bf5e9605350cc788eaebbda7 Mon Sep 17 00:00:00 2001 From: omnom62 Date: Sat, 23 May 2026 07:42:08 +1000 Subject: Changelog --- .coderabbit.yaml | 142 ++++++++++----------- AGENTS.md | 7 + .../fragments/T8517_unit_tests_lldp_interfaces.yml | 3 + 3 files changed, 81 insertions(+), 71 deletions(-) create mode 100644 changelogs/fragments/T8517_unit_tests_lldp_interfaces.yml diff --git a/.coderabbit.yaml b/.coderabbit.yaml index 38eae56f..b23fb30b 100644 --- a/.coderabbit.yaml +++ b/.coderabbit.yaml @@ -12,8 +12,8 @@ reviews: profile: chill request_changes_workflow: false high_level_summary: true - high_level_summary_placeholder: '@coderabbitai summary' - auto_title_placeholder: '@coderabbitai' + high_level_summary_placeholder: "@coderabbitai summary" + auto_title_placeholder: "@coderabbitai" review_status: true poem: false collapse_walkthrough: true @@ -38,17 +38,17 @@ reviews: - Bump path_filters: - - '!**/__pycache__/**' - - '!**/*.pyc' - - '!**/*.egg-info/**' - - '!changelogs/changelog.yaml' - - '!.venv/**' - - '!.collections/**' - - '!.worktrees/**' + - "!**/__pycache__/**" + - "!**/*.pyc" + - "!**/*.egg-info/**" + - "!changelogs/changelog.yaml" + - "!.venv/**" + - "!.collections/**" + - "!.worktrees/**" path_instructions: # ── Global PR hygiene ────────────────────────────────────────────── - - path: '**' + - path: "**" instructions: | This is the vyos.vyos Ansible network collection (namespace=vyos, name=vyos, version=6.0.0). PR titles must follow the format `T{id}: description` referencing @@ -61,7 +61,7 @@ reviews: 88-char wrapping. # ── Module entry points ──────────────────────────────────────────── - - path: 'plugins/modules/vyos_*.py' + - path: "plugins/modules/vyos_*.py" instructions: | Module entry points. Each file must contain three YAML triple-string blocks: DOCUMENTATION, EXAMPLES, and RETURN — this is Ansible's documentation contract, @@ -78,7 +78,7 @@ reviews: are the canonical documentation. # ── Argspec (auto-generated) ─────────────────────────────────────── - - path: 'plugins/module_utils/network/vyos/argspec/**' + - path: "plugins/module_utils/network/vyos/argspec/**" instructions: | Auto-generated by the Ansible resource module builder. These files carry a "DO NOT EDIT" warning header. Do not suggest modifications to auto-generated @@ -88,7 +88,7 @@ reviews: that would cause runtime failures. # ── Config classes ───────────────────────────────────────────────── - - path: 'plugins/module_utils/network/vyos/config/**' + - path: "plugins/module_utils/network/vyos/config/**" instructions: | Config builders extending ansible.netcommon ConfigBase or ResourceModule. These generate VyOS CLI commands from desired state. Verify: @@ -102,7 +102,7 @@ reviews: Some older config files have auto-generated headers — do not restructure those. # ── Facts classes ────────────────────────────────────────────────── - - path: 'plugins/module_utils/network/vyos/facts/**' + - path: "plugins/module_utils/network/vyos/facts/**" instructions: | Facts classes parse raw VyOS CLI output into structured dicts. Verify: - Regex patterns handle edge cases (missing fields, empty values, quoted strings). @@ -114,7 +114,7 @@ reviews: get_resource_connection(). # ── RM Templates ─────────────────────────────────────────────────── - - path: 'plugins/module_utils/network/vyos/rm_templates/*.py' + - path: "plugins/module_utils/network/vyos/rm_templates/*.py" instructions: | Parser templates mapping structured data to VyOS CLI commands and vice versa. Files with a `_14` suffix target VyOS 1.4+ behavior — do not suggest merging @@ -126,7 +126,7 @@ reviews: - compval/getval paths match the argspec structure. # ── Cliconf plugin ───────────────────────────────────────────────── - - path: 'plugins/cliconf/vyos.py' + - path: "plugins/cliconf/vyos.py" instructions: | Low-level CLI abstraction for VyOS. Handles configure mode, commit, diff, command execution. Changes here affect all modules. Verify: @@ -137,7 +137,7 @@ reviews: - __rpc__ list matches actually implemented methods. # ── Terminal plugin ──────────────────────────────────────────────── - - path: 'plugins/terminal/vyos.py' + - path: "plugins/terminal/vyos.py" instructions: | Terminal prompt detection and initialization. Changes affect connection reliability. Verify regex patterns against actual VyOS prompt formats @@ -145,14 +145,14 @@ reviews: remove existing patterns without testing against all supported VyOS versions. # ── Action plugin ────────────────────────────────────────────────── - - path: 'plugins/action/vyos.py' + - path: "plugins/action/vyos.py" instructions: | Auto-proxies all modules to the device. Must validate network_cli connection type. Symlinks from each module name point here. Keep minimal — logic belongs in config classes, not the action plugin. # ── Changelog fragments ──────────────────────────────────────────── - - path: 'changelogs/fragments/*.{yaml,yml}' + - path: "changelogs/fragments/*.{yaml,yml}" instructions: | Changelog fragments for ansible-changelog. Valid top-level keys: major_changes, minor_changes, breaking_changes, deprecated_features, @@ -162,7 +162,7 @@ reviews: Use `trivial` for tooling/housekeeping. Entries should be complete sentences. # ── CI workflows ─────────────────────────────────────────────────── - - path: '.github/workflows/**' + - path: ".github/workflows/**" instructions: | CI pipeline: tests.yml (main CI with changelog, build, lint, sanity, unit jobs), codecoverage.yml, release.yml (Galaxy + Automation Hub publish), check_label.yaml, @@ -171,7 +171,7 @@ reviews: job from tests.yml. # ── Unit tests ───────────────────────────────────────────────────── - - path: 'tests/unit/**' + - path: "tests/unit/**" instructions: | Unit tests use pytest + unittest.TestCase via TestVyosModule base class. Key patterns: @@ -186,7 +186,7 @@ reviews: execute_module kwargs. pytest-xdist runs tests in parallel (-n 2). # ── Test fixtures ────────────────────────────────────────────────── - - path: 'tests/unit/modules/network/vyos/fixtures/**' + - path: "tests/unit/modules/network/vyos/fixtures/**" instructions: | Raw VyOS CLI output files (.cfg). These are loaded by load_fixture() and cached in memory. Format is VyOS `set ...` configuration syntax or show @@ -196,13 +196,13 @@ reviews: unless the test explicitly requires JSON parsing. # ── Collection metadata ──────────────────────────────────────────── - - path: 'galaxy.yml' + - path: "galaxy.yml" instructions: | Collection metadata. namespace=vyos, name=vyos. Version bumps must be coordinated with release process. Dependency on ansible.netcommon>=2.5.1 is required. Do not add unnecessary dependencies. - - path: 'meta/runtime.yml' + - path: "meta/runtime.yml" instructions: | Module redirects and tombstones. Adding a new module requires a redirect entry (short name → FQCN). Tombstoned modules (logging, vyos_logging) must @@ -273,7 +273,7 @@ code_generation: language: en-US path_instructions: # ── Module entry points: YAML blocks, not Python docstrings ────── - - path: 'plugins/modules/vyos_*.py' + - path: "plugins/modules/vyos_*.py" instructions: | Do NOT generate Python-style docstrings for these files. Ansible modules use YAML triple-string blocks: DOCUMENTATION, EXAMPLES, and RETURN. @@ -290,13 +290,13 @@ code_generation: Keep version_added accurate — do not backdate. # ── Argspec: skip auto-generated files ─────────────────────────── - - path: 'plugins/module_utils/network/vyos/argspec/**' + - path: "plugins/module_utils/network/vyos/argspec/**" instructions: | Skip — these files are auto-generated by the Ansible resource module builder and carry a "DO NOT EDIT" header. Do not generate or modify docstrings. # ── Config classes ─────────────────────────────────────────────── - - path: 'plugins/module_utils/network/vyos/config/**' + - path: "plugins/module_utils/network/vyos/config/**" instructions: | Config builder classes extending ConfigBase or ResourceModule. Use reStructuredText-style docstrings (Ansible/Sphinx convention): @@ -315,7 +315,7 @@ code_generation: keep docstrings minimal in those to avoid noise on regeneration. # ── Facts classes ──────────────────────────────────────────────── - - path: 'plugins/module_utils/network/vyos/facts/**' + - path: "plugins/module_utils/network/vyos/facts/**" instructions: | Facts parsers that convert VyOS CLI output to structured dicts. Use rST docstrings. Document: @@ -326,7 +326,7 @@ code_generation: Skip __init__.py files. # ── RM Templates ───────────────────────────────────────────────── - - path: 'plugins/module_utils/network/vyos/rm_templates/*.py' + - path: "plugins/module_utils/network/vyos/rm_templates/*.py" instructions: | Parser template files with _tmplt_* helper functions and PARSERS lists. Add a module-level docstring describing the resource and VyOS CLI hierarchy @@ -337,7 +337,7 @@ code_generation: note this in the module docstring. # ── Cliconf plugin ────────────────────────────────────────────── - - path: 'plugins/cliconf/vyos.py' + - path: "plugins/cliconf/vyos.py" instructions: | Uses Ansible DOCUMENTATION block for plugin-level docs. For Python methods use rST docstrings. Document: get_device_info(), edit_config(), get_config(), @@ -345,25 +345,25 @@ code_generation: configure mode. # ── Terminal and action plugins ────────────────────────────────── - - path: 'plugins/terminal/vyos.py' + - path: "plugins/terminal/vyos.py" instructions: | Minimal docstrings only. Document on_open_shell() and on_close_shell() explaining what terminal parameters they set. Regex patterns are self-documenting — do not add inline comments to each pattern. - - path: 'plugins/action/vyos.py' + - path: "plugins/action/vyos.py" instructions: | Skip — thin proxy inheriting ActionNetworkModule. No docstrings needed. # ── Utilities ──────────────────────────────────────────────────── - - path: 'plugins/module_utils/network/vyos/utils/*.py' + - path: "plugins/module_utils/network/vyos/utils/*.py" instructions: | Utility functions shared across modules. Use rST docstrings for any function with non-obvious behavior. Document parameters, return types, and side effects. Skip trivial one-liners. # ── Test files ────────────────────────────────────────────────── - - path: 'tests/**' + - path: "tests/**" instructions: | Skip — test files do not need docstrings. Test method names should be self-describing (test_vyos___). @@ -371,7 +371,7 @@ code_generation: unit_tests: path_instructions: # ── Resource module tests ──────────────────────────────────────── - - path: 'plugins/modules/vyos_interfaces.py' + - path: "plugins/modules/vyos_interfaces.py" instructions: &resource_module_tests | Generate tests in tests/unit/modules/network/vyos/test_vyos_.py. Inherit from TestVyosModule (import from vyos_module.py in same directory). @@ -428,68 +428,68 @@ code_generation: vyos__config.cfg with valid VyOS set-syntax configuration. Use load_fixture() to read fixtures — never inline raw config. - - path: 'plugins/modules/vyos_l3_interfaces.py' + - path: "plugins/modules/vyos_l3_interfaces.py" instructions: *resource_module_tests - - path: 'plugins/modules/vyos_lag_interfaces.py' + - path: "plugins/modules/vyos_lag_interfaces.py" instructions: *resource_module_tests - - path: 'plugins/modules/vyos_lldp_global.py' + - path: "plugins/modules/vyos_lldp_global.py" instructions: *resource_module_tests - - path: 'plugins/modules/vyos_lldp_interfaces.py' + - path: "plugins/modules/vyos_lldp_interfaces.py" instructions: *resource_module_tests - - path: 'plugins/modules/vyos_static_routes.py' + - path: "plugins/modules/vyos_static_routes.py" instructions: *resource_module_tests - - path: 'plugins/modules/vyos_firewall_rules.py' + - path: "plugins/modules/vyos_firewall_rules.py" instructions: *resource_module_tests - - path: 'plugins/modules/vyos_firewall_global.py' + - path: "plugins/modules/vyos_firewall_global.py" instructions: *resource_module_tests - - path: 'plugins/modules/vyos_firewall_interfaces.py' + - path: "plugins/modules/vyos_firewall_interfaces.py" instructions: *resource_module_tests - - path: 'plugins/modules/vyos_ospfv2.py' + - path: "plugins/modules/vyos_ospfv2.py" instructions: *resource_module_tests - - path: 'plugins/modules/vyos_ospfv3.py' + - path: "plugins/modules/vyos_ospfv3.py" instructions: *resource_module_tests - - path: 'plugins/modules/vyos_ospf_interfaces.py' + - path: "plugins/modules/vyos_ospf_interfaces.py" instructions: *resource_module_tests - - path: 'plugins/modules/vyos_bgp_global.py' + - path: "plugins/modules/vyos_bgp_global.py" instructions: *resource_module_tests - - path: 'plugins/modules/vyos_bgp_address_family.py' + - path: "plugins/modules/vyos_bgp_address_family.py" instructions: *resource_module_tests - - path: 'plugins/modules/vyos_prefix_lists.py' + - path: "plugins/modules/vyos_prefix_lists.py" instructions: *resource_module_tests - - path: 'plugins/modules/vyos_route_maps.py' + - path: "plugins/modules/vyos_route_maps.py" instructions: *resource_module_tests - - path: 'plugins/modules/vyos_snmp_server.py' + - path: "plugins/modules/vyos_snmp_server.py" instructions: *resource_module_tests - - path: 'plugins/modules/vyos_logging_global.py' + - path: "plugins/modules/vyos_logging_global.py" instructions: *resource_module_tests - - path: 'plugins/modules/vyos_ntp_global.py' + - path: "plugins/modules/vyos_ntp_global.py" instructions: *resource_module_tests - - path: 'plugins/modules/vyos_hostname.py' + - path: "plugins/modules/vyos_hostname.py" instructions: *resource_module_tests - - path: 'plugins/modules/vyos_vrf.py' + - path: "plugins/modules/vyos_vrf.py" instructions: *resource_module_tests # ── Legacy module tests ────────────────────────────────────────── - - path: 'plugins/modules/vyos_command.py' + - path: "plugins/modules/vyos_command.py" instructions: &legacy_module_tests | Generate tests in tests/unit/modules/network/vyos/test_vyos_.py. Inherit from TestVyosModule. @@ -525,48 +525,48 @@ code_generation: vyos_command wait_for/retries, vyos_config src/lines/match). Use execute_module(changed=, commands=) for assertions. - - path: 'plugins/modules/vyos_config.py' + - path: "plugins/modules/vyos_config.py" instructions: *legacy_module_tests - - path: 'plugins/modules/vyos_facts.py' + - path: "plugins/modules/vyos_facts.py" instructions: *legacy_module_tests - - path: 'plugins/modules/vyos_banner.py' + - path: "plugins/modules/vyos_banner.py" instructions: *legacy_module_tests - - path: 'plugins/modules/vyos_ping.py' + - path: "plugins/modules/vyos_ping.py" instructions: *legacy_module_tests - - path: 'plugins/modules/vyos_system.py' + - path: "plugins/modules/vyos_system.py" instructions: *legacy_module_tests - - path: 'plugins/modules/vyos_user.py' + - path: "plugins/modules/vyos_user.py" instructions: *legacy_module_tests - - path: 'plugins/modules/vyos_vlan.py' + - path: "plugins/modules/vyos_vlan.py" instructions: *legacy_module_tests # ── Test infrastructure — do not generate tests for these ──────── - - path: 'tests/unit/modules/utils.py' + - path: "tests/unit/modules/utils.py" instructions: | Skip — test infrastructure (ModuleTestCase base, set_module_args, exception classes). Do not generate tests for test utilities. - - path: 'tests/unit/modules/conftest.py' + - path: "tests/unit/modules/conftest.py" instructions: | Skip — pytest fixtures (patch_ansible_module). Do not generate tests. - - path: 'tests/unit/modules/network/vyos/vyos_module.py' + - path: "tests/unit/modules/network/vyos/vyos_module.py" instructions: | Skip — TestVyosModule base class with execute_module(), load_fixture(), and mock setup. Do not generate tests for the test base class. - - path: 'tests/unit/modules/network/vyos/fixtures/**' + - path: "tests/unit/modules/network/vyos/fixtures/**" instructions: | Skip — raw VyOS CLI output fixtures. Not code, not testable. # ── Non-module plugin code ─────────────────────────────────────── - - path: 'plugins/module_utils/**' + - path: "plugins/module_utils/**" instructions: | Module utility code (argspec, config, facts, rm_templates, utils). These are tested indirectly through module-level tests — the config @@ -575,17 +575,17 @@ code_generation: a utility function in plugins/module_utils/network/vyos/utils/ has complex standalone logic worth testing in isolation. - - path: 'plugins/cliconf/vyos.py' + - path: "plugins/cliconf/vyos.py" instructions: | Skip — cliconf plugin is tested via integration tests and indirectly through module tests. Unit testing requires complex CliconfBase mocking that provides little value over integration coverage. - - path: 'plugins/terminal/vyos.py' + - path: "plugins/terminal/vyos.py" instructions: | Skip — terminal plugin regex patterns are validated through integration tests against actual VyOS devices. - - path: 'plugins/action/vyos.py' + - path: "plugins/action/vyos.py" instructions: | Skip — thin action proxy. Tested indirectly via module tests. diff --git a/AGENTS.md b/AGENTS.md index 436b6785..6a749230 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,20 +1,24 @@ # AGENTS.md ## Project purpose + The official Ansible Collection for managing VyOS network appliances (`vyos.vyos` namespace). Provides modules, plugins, action handlers, terminal plugins, and resource modules for BGP, OSPF, firewall, interfaces, NTP, etc. ## Tech stack + - Ansible Collection (Galaxy). Python control-plane code under `plugins/`. - `galaxy.yml` declares `namespace: vyos`, `name: vyos`, `version: 6.0.0`, dep `ansible.netcommon >= 2.5.1`, license_file `LICENSE` (GPL-3.0). - Test stack: `pytest` + `tox-ansible.ini`; lint via flake8, isort, black (line-length 100), pre-commit, ansible-lint. - Runtime deps: `paramiko`, `scp` (`requirements.txt`); `bindep.txt` for system deps. ## Build / test / run + - Build: `ansible-galaxy collection build` produces a `vyos-vyos-.tar.gz`. - Install local dev: `ansible-galaxy collection install . --force`. - Test (unit): `ansible-test units` (matches `unit-galaxy` CI job; requires collection installed under `~/.ansible/collections/`). Fast local alternative: `source .venv/bin/activate && PYTHONPATH=".collections" python -m pytest tests/unit` (matches `unit-source` CI path; config in `pyproject.toml`). CI (`.github/workflows/tests.yml`) runs the changelog / build-import / ansible-lint / sanity / unit-galaxy / unit-source jobs; integration tests live under `tests/integration/` but are not yet wired into CI. Per `README.md`, the collection targets VyOS 1.3.8 / 1.4.1 / 1.5-rolling (no version matrix in the workflow itself). ## Repository layout + - `plugins/{action,cliconf,doc_fragments,filter,inventory,module_utils,modules,terminal}/` — collection content. - `tests/` — sanity, unit, integration directories. CI (`.github/workflows/tests.yml`) runs sanity + unit-galaxy + unit-source (plus changelog / build-import / ansible-lint); integration is not yet wired into CI. - `docs/` — generated module docs. @@ -23,10 +27,12 @@ The official Ansible Collection for managing VyOS network appliances (`vyos.vyos - `.github/workflows/` — `tests.yml`, `release.yml`, `codecoverage.yml`, `cla-check.yml`, `ah_token_refresh.yml`, `check_label.yaml`. ## Cross-repo context + - Consumed by Ansible users running playbooks against VyOS routers built by `vyos/vyos-build`. - The `vyos.vyos` collection talks to VyOS via `network_cli` connections; supports the same train branches (`current`, `circinus`, `sagitta`, `equuleus`). ## Conventions + - Commit headline: `T12345: description` (Phorge ID at https://vyos.dev mandatory). No workflow enforces PR title format in this repo. - Every PR must include exactly one changelog fragment under `changelogs/fragments/`; use `doc_changes` for documentation-only updates, or `trivial` for tooling / housekeeping changes. - Default branch `main` (not `current` — this repo predates the rename convention). @@ -34,6 +40,7 @@ The official Ansible Collection for managing VyOS network appliances (`vyos.vyos - Codecov + CodeRabbit configured (`codecov.yml`, `.coderabbit.yaml`). ## Notes for future contributors + - Galaxy versioning is independent of VyOS train versioning — bump in `galaxy.yml` per release. - Tested matrix is in README; expand only after smoketesting against real images. - `PR408_README.md` plus `pr408-diagram.png` document a non-trivial historical refactor; read before touching resource-module structure. diff --git a/changelogs/fragments/T8517_unit_tests_lldp_interfaces.yml b/changelogs/fragments/T8517_unit_tests_lldp_interfaces.yml new file mode 100644 index 00000000..65da6dad --- /dev/null +++ b/changelogs/fragments/T8517_unit_tests_lldp_interfaces.yml @@ -0,0 +1,3 @@ +--- +minor_changes: + - Add unit tests for vyos_lldp_interfaces moduule. -- cgit v1.2.3