Fix documentation, agent-instruction, and changelog gaps - #297
Merged
Conversation
AGENTS.md claimed model fields must be immutable collections, but HConfigDriverRules deliberately uses list fields so built-in rules and callbacks can be removed by identity (#286); an agent following the rule literally would break that API. Document the carve-out everywhere the rule is stated (AGENTS.md, copilot-instructions, code-style.md, review skill, new-driver skill). The review skill diffed against master, which on any next-based branch pulls in all of v4 and makes the report meaningless; switch to merge-base against the actual base branch. Add the branching strategy to AGENTS.md (previously only CLAUDE.md had it, so non-Claude agents and Copilot would target master for v4 work) and drop the now-duplicate section from CLAUDE.md. Also surface facts agents had no way to learn: the CI Python matrix (3.10-3.14), the unconditional docs --strict job and its separate docs/requirements.txt, the formats layer (JSON/XML/NETCONF/gNMI), future_with_report(), registry key canonicalization (#284/#295), and per-driver unit test expectations. Fix CONTRIBUTING.md stale content (nonexistent test file, missing yamllint/flynt, missing changelog requirement, no branch-base guidance).
Several documented examples did not run or showed wrong output: getting-started referenced a fixture that does not exist, tags.md filtered on an 'ntp' tag its fixture never defines (actual output was empty), remediation-workflows called a nonexistent delete_child() method, config-views mixed switchport and ip address config and claimed outputs the view never produces, and the hierarchical JunOS example was missing six trailing set lines. All replacement outputs were verified by running the snippets against the real fixtures. Remove the hardcoded prerelease pin from install.md (it had already drifted from pyproject) and add --pre to the README install so its Quick Start, which uses the v4-only API, can actually run. Propagate Aruba AOS-CX into the architecture driver table and config-views lists, correct the HConfigViewBase abstract-member lists (dot1q_mode_from_vlans is a concrete static helper), and align the interface-view example with the in-tree base-class pattern. Fill reference gaps: formats module, future_with_report/FutureReport, resolve_driver, view data models, and the full built-in post-load callback table in api-reference/rule-reference; glossary entries for the registry, future reports, list_keys, callbacks, and RemediationPlugin; rules-from-files loader constraints (one criterion per lineage entry, Platform-only). Point the legacy utilities.md redirects at admin/rules-from-files.md where that content actually lives.
The Unreleased block had accumulated duplicate Added/Changed/Fixed headings from successive merges, Added-type entries filed under Fixed, a non-standard 'v4 design decisions' heading, and a stale claim that JSON/XML ingestion was post-4.0 roadmap work when the same section documents it as shipped. Merge to one heading per category, re-file the misfiled entries, drop the contradictory sentence, and keep the design decisions as an intro note. All 59 entries and every (#NNN) reference are preserved. Point the migration guide at the Unreleased section instead of a 4.0.0 CHANGELOG section that does not exist yet. Correct the per-file ignore path for the benchmarks file, which moved to tests/benchmarks/ without the lint config following; with the ignore active again, the inline print suppressions it replaces became unused and were removed.
The WorkflowRemediation class docstring, which renders into the public API reference, still showed a v3-era example importing the removed get_hconfig from the nonexistent hier_config.model module, and claimed __init__ raises ValueError when it raises IncompatibleDriverError. Add attribute docs to the FutureReport fields (the user-facing contract of future_with_report) and docstrings to 33 previously undocumented public members on autodoc'd classes — driver extension points (idempotent_for, sectional_exit, prefixes, config_preprocessor), the HConfigViewBase contract, and the HConfigBase/HConfigChild/HConfig/ HConfigChildren members that doc examples tell users to call. Also add this PR's changelog entry (#297).
jtdub
changed the title
jtdub
marked this pull request as ready for review
August 5, 2026 13:55
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Closes the gaps found in a full audit of the documentation and agent-facing instruction files against the code on
next. Four commits, one per surface:Agent instruction files (
c222257) — AGENTS.md/copilot-instructions/skills contradicted or omitted repo reality:list[...]fields onHConfigDriverRules(Stable public identities for built-in post-load callbacks #286 removal-by-identity); an agent following it literally would break that public API. The carve-out is now documented in AGENTS.md, copilot-instructions, code-style.md, and both affected skills.hier-config-reviewskill diffed againstmaster, which on anynext-based branch pulls in all of v4 — it now uses the merge-base with the actual base branch.masterfor v4 work). Also added: the CI Python matrix (3.10–3.14), the unconditional docs--strictjob and its separatedocs/requirements.txt, the formats/plugins/constructors modules,future_with_report(), and the v4: Canonicalize registry platform keys before 4.0.0 final #284/Canonicalize registry keys to uppercase platform names #295 registry canonicalization (including thePlatform.X.namekey requirement in the new-driver skill).User docs + README (
ff7007b) — five documented examples were verifiably broken (nonexistent fixture in getting-started, tags.md filtering on a tag its fixture never defines, a nonexistentdelete_child()method, wrong config-view outputs, six missing JunOS output lines). All replacement outputs were produced by running the snippets against the real fixtures. Also:--prein the README install (its Quick Start uses the v4-only API), de-pinned the drifted4.0.0b1from install.md, propagated Aruba AOS-CX into architecture/config-view docs, corrected theHConfigViewBaseabstract-member lists, added the formats module / Future Config section /resolve_driver/ view data models / all nine built-in post-load callbacks to the API reference, five new glossary entries, and pointed the legacyutilities.mdredirects atadmin/rules-from-files.md.CHANGELOG (
480d04d) —[Unreleased]had duplicate Added/Changed/Fixed headings, Added entries misfiled under Fixed, a non-standard "v4 design decisions" heading, and a self-contradiction (JSON/XML ingestion described as both shipped and post-4.0 roadmap). Merged to one heading per category with all 59 entries and every(#NNN)reference preserved. Also fixed the stale benchmarks per-file-ignore path in pyproject.toml (tests/test_benchmarks.py→tests/benchmarks/test_benchmarks.py) and removed the ten inline suppressions that fix makes redundant.Docstrings (
be650e4) — theWorkflowRemediationclass docstring (rendered on the public API reference) showed a v3 example importing the removedget_hconfigfrom the nonexistenthier_config.modelmodule and claimedRaises: ValueErrorwhere the code raisesIncompatibleDriverError. Documented theFutureReportfields and 33 previously undocumented public members on autodoc'd classes. No code behavior changed.Self-Review Checklist
poetry run ./scripts/build.py lint-and-testpasses locally (lint + 95% test coverage).CHANGELOG.mdhas an entry under## [Unreleased]referencing this issue/PR ((#297)).mkdocs build --strictpasses if docs were touched).AI-Assisted Contributions
Written with Claude Code; the
hier-config-reviewskill was run against the final diff (using the correctednextmerge-base this PR introduces) — gates green, no blockers or should-fix findings.Noted but out of scope
mkdocs build --strictwithout installing the package (fragile if griffe ever falls back to dynamic import); theinclude-markdownplugin is loaded but unused.poetry.lockcurrently resolvesmkdocs-redirects→properdocsandmkdocstrings-python→griffelib(forks that arrived transitively via Add AI-contributor standards: docs reorg, review skill, agent guidance #290's lock change;properdocsinjects an "MkDocs is abandoned" banner into every build). Worth a separate review of those pins.tests/circular/andtests/config_view/directories remain from the test-layout move.