Skip to content

Add v3 to v4 migration guide#288

Merged
jtdub merged 1 commit into
nextfrom
docs-v3-migration
Jul 19, 2026
Merged

Add v3 to v4 migration guide#288
jtdub merged 1 commit into
nextfrom
docs-v3-migration

Conversation

@jtdub

@jtdub jtdub commented Jul 19, 2026

Copy link
Copy Markdown
Contributor

Summary

Adds docs/user/migrating-from-v3.md (nav: User Guide → Migrating from v3, right after Getting Started) — the missing piece for existing 3.x users, since v4 renames or removes nearly every entry point.

Contents:

  • Quick-reference rename tables: constructors (get_hconfigHConfig.from_text, etc.), methods (config_to_get_toremediation(), dump_simpleto_lines(), ...), and utilities (load_hconfig_v2_optionsload_driver_rules, removed v2 mappers).
  • Negation rule migration with before/after code for all three old models → NegationRule + NegationStrategy, and a note that load_driver_rules() still accepts the old dict keys.
  • Typed exceptions table (ValueError/TypeErrorHierConfigError subclasses) for updating except clauses.
  • Config-view transition: isinstance(view, InterfaceVlanViewMixin) replacing NotImplementedError catching.
  • Behavior changes to review: future() negation resolution (future() negation edge cases: value-carrying negation on idempotent lines leaves a literal 'no ...' line; bare shorthand negation never matches; empty parents not pruned #269), structured-input rejection, registry-based custom driver wiring.
  • New-in-v4 pointers for features worth adopting during the upgrade.

Test plan

  • Every import and API name in the guide executed against the package (InterfaceVlanViewMixin, HierConfigError, NegationRule/NegationStrategy, load_driver_rules/load_tag_rules, ...).
  • poetry run mkdocs build --strict — zero warnings.
  • poetry run ./scripts/build.py lint-and-test — "No issues found".

🤖 Generated with Claude Code

New docs/user/migrating-from-v3.md with rename tables for constructors,
methods, and utilities, the unified NegationRule mapping with
before/after examples, the typed exception hierarchy, the config-view
mixin transition (isinstance instead of NotImplementedError), behavior
changes to review (future() negation resolution, structured-input
rejection, driver registration), and pointers to the new v4 features.
Every import and API name in the guide is verified against the package.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@jtdub
jtdub requested a review from aedwardstx as a code owner July 19, 2026 01:32
@jtdub
jtdub merged commit f66e3b6 into next Jul 19, 2026
5 checks passed
@jtdub
jtdub deleted the docs-v3-migration branch July 19, 2026 01:35
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant