sonic: document config ownership regimes

[ideaship]

Problem

SONiC config is written to two stores with deliberately different ownership disciplines, and only one was documented:

• config_db.json — table-level ownership: the generator owns whole tables and drops-and-rebuilds them every regen. Safe because the file has no external co-owner.
• NetBox device local_context_data — co-owned with other generators (frr_parameters, netplan_parameters), so save_config_to_netbox owns only its sonic_config key: it carries the existing context forward and overwrites just that key, so the value written back always still holds the siblings. A distinct regime — partitioned key ownership.

The contrast was implicit, inviting a future change to "simplify" the exporter into writing back a context that holds only sonic_config and drops the siblings.

Why the existing lock wasn't enough

The sibling preservation is already enforced by tests in test_exporter.py. But that lock wasn't discoverable: the tests asserted a bare dict equality, so a regression failed with only a dict diff. An author who didn't already know the contract could read the test as stale and weaken it — instead of recognizing the broken behavior, which is exactly the regression the test guards against.

Change

Make the lock teach at the point of failure (docs and test messages only — no behavior change):

• Add the regime, its reason, and the deciding factor (an external co-owner) to the save_config_to_netbox docstring.
• Name both regimes in the generate_sonic_config ownership-model docstring, so the two read as one model.
• Give the sibling-preservation assertions an explanatory message that states the partitioned-key-ownership contract and points to the docstring, so a regression surfaces the reasoning rather than a bare diff.

Related

• SONiC config_db.json ownership model: open decisions + a hidden PR collision #2340

[sourcery-ai]

Hey - I've left some high level feedback:

• The _PARTITIONED_KEY_OWNERSHIP message largely restates the save_config_to_netbox docstring; consider shortening it and explicitly referencing the docstring instead of duplicating the reasoning, to reduce future drift between the two.
• The save_config_to_netbox docstring is now quite dense; consider breaking the ownership explanation into a short summary plus a bulleted or clearly separated rationale so future readers can quickly grasp the key rule (only own sonic_config) without wading through the full background each time.

Prompt for AI Agents

Please address the comments from this code review:

## Overall Comments
- The `_PARTITIONED_KEY_OWNERSHIP` message largely restates the `save_config_to_netbox` docstring; consider shortening it and explicitly referencing the docstring instead of duplicating the reasoning, to reduce future drift between the two.
- The `save_config_to_netbox` docstring is now quite dense; consider breaking the ownership explanation into a short summary plus a bulleted or clearly separated rationale so future readers can quickly grasp the key rule (only own `sonic_config`) without wading through the full background each time.

---

Sourcery is free for open source - if you like our reviews please consider sharing them ✨

• X
• Mastodon
• LinkedIn
• Facebook

_{Help me be more useful! Please click 👍 or 👎 on each comment and I'll use the feedback to improve your reviews.}