Development¶

Requires uv and Docker. PowerShell (pwsh) is optional: with it, the unit tests also run the real scripts against stub cmdlets.

git clone https://github.com/thomaschristory/netbox-windows-dhcp-plugin
cd netbox-windows-dhcp-plugin
uv sync

Make targets¶

The dev stack runs in branching mode. Its first start migrates a fresh database and takes several minutes. Log in as admin with the SUPERUSER_PASSWORD from dev/env/netbox.env.

Code layout¶

netbox_windows_dhcp_plugin/
  windows/      pure Python: PowerShell scripts, transports (WinRM, SSH), the client (one function per cmdlet),
                normalisation, and an in-memory fake server for tests. No Django imports
  sync/         diff engine, Windows and NetBox records, push planning and writing, import
  models/ api/ graphql/ views.py forms.py ...   the NetBox side
  connection.py builds a client from a Windows server and its credential profile
  jobs.py       every job; all Windows I/O happens here
  integrations/branching.py   the only module that imports netbox-branching and netbox-change-control

The design explains the decisions; the roadmap what is done.

Rules worth knowing before a change:

• Values reach PowerShell only through the $p JSON literal built by windows/psscript.py; never format a value into a script.
• Never log or store credentials.
• A new cmdlet gets an implementation in windows/fake.py, a JSON fixture under tests/windows/testdata/ and a pwsh stub test; mark it # unverified: until it has run against a real server.
• Model changes need a migration and refreshed query-count baselines in both standalone and branching modes.
• Update CHANGELOG.md under Unreleased with every user-visible change, and these pages when behaviour changes.

Testing tiers¶

1. Unit (make test): script rendering and envelope parsing, normalisation, the client against recorded fixtures and the fake server, the diff engine, and checks on these docs.
2. PowerShell (part of make test, skipped without pwsh; the PWSH variable picks the binary): the real scripts run against stub cmdlets in tests/windows/testdata/stubs.ps1.
3. NetBox (make test-netbox): models, views, API, import, push and leases against the fake server. CI runs it in standalone and branching modes.
4. Lab (opt-in): a real Windows DHCP server, see below.

CI runs lint, unit tests on Python 3.12 to 3.14, the build, the docs build, and the NetBox tests in both modes.

Lab tests¶

The lab tier checks the client and the whole sync against a real Windows DHCP server. CI never runs it.

Preparing a lab VM¶

Any Windows Server 2016 or later VM will do; an evaluation edition on a host-only network is enough, since the tests never serve real clients. In an elevated PowerShell on the VM, run the setup script from the repository:

Set-ExecutionPolicy -Scope Process Bypass
.\dev\scripts\lab-server-setup.ps1 -AllowFrom 192.168.56.0/24

It installs the DHCP role, creates a local account nbwd-lab in DHCP Administrators and Remote Management Users (asking for its password), sets up WinRM over HTTPS on 5986 with a self-signed certificate, opens the firewall (optionally only to the given network), and prints the settings for the next step. It is safe to run again.

Running them¶

Put the connection settings in dev/env/netbox.env (never committed) or the environment:

Then:

make test-lab        # the client over WinRM, one round trip per unverified cmdlet
make dev             # recreate the dev stack once, so it mounts the lab helpers
make lab-e2e         # import, push creates, updates and deletes, leases, on the dev stack

make test-lab writes property dumps to .lab/probe/. make lab-e2e prints PASSED at the end and exits non-zero on failure. Both leave the server as they found it. Everything under .lab/ can identify the lab and is ignored by git: scrub host names and addresses before turning a recording into a fixture.

Documentation¶

These pages live in docs/ and are built with Zensical from mkdocs.yml:

make docs-serve      # http://localhost:8001, reloads on save
make docs            # strict build into site/

make test checks the docs too: no em dashes, the configuration table matches the plugin's defaults, every page is in the navigation, and the PLUGINS_CONFIG examples are valid. The site is published to GitHub Pages when a release is tagged.

Releasing¶

1. Update netbox_windows_dhcp_plugin/version.py and move the Unreleased section of CHANGELOG.md under the new version and date.
2. make dist, merge to main.
3. Tag vX.Y.Z on main and push the tag. The release workflow checks the tag is on main, builds, and publishes to PyPI through trusted publishing after a maintainer approves the pypi environment; the docs workflow publishes the site.