From 4f6325636b80469067cb62c7c34bb2653e1a237b Mon Sep 17 00:00:00 2001 From: Bearchitek Date: Tue, 15 Sep 2026 14:43:57 +0200 Subject: [PATCH] docs: add release notes for Schema Library 2.0.0 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The repository has published tags but no written account of what changed between them: the v1.4.11 release body is a single sentence and v1.1.8 is empty. The 2.0.0 window covers roughly eleven months and fifteen pull requests, so what changed is currently only recoverable by reading commits. Assemble CHANGELOG.md from news fragments covering the user-facing changes in that window, and add a release-notes page to the documentation site. The page leads with what someone can do differently after upgrading, and carries the migration warning up front: 2.0.0 renames and retypes attributes and relationships across the base schemas and most extensions, so data built on a 1.x schema has to be migrated rather than upgraded in place. Every claim was verified against the schema files at this commit rather than taken from pull request descriptions. Several of those descriptions did not match what shipped — the interface MTU stayed on the DcimInterface generic instead of moving to InterfacePhysical, the IpamPrefix supernet role was dropped rather than kept, and the removal of DcimCircuit.location went unmentioned — so the entries follow the schema files. Co-Authored-By: Claude Opus 5 (1M context) --- .vale/styles/spelling-exceptions.txt | 1 + CHANGELOG.md | 74 +++++++++++++ changelog/+towncrier.housekeeping.md | 5 - docs/docs/release-notes/v2.0.0.mdx | 158 +++++++++++++++++++++++++++ docs/sidebars.ts | 11 ++ 5 files changed, 244 insertions(+), 5 deletions(-) delete mode 100644 changelog/+towncrier.housekeeping.md create mode 100644 docs/docs/release-notes/v2.0.0.mdx diff --git a/.vale/styles/spelling-exceptions.txt b/.vale/styles/spelling-exceptions.txt index ee3d2f47..270721b5 100644 --- a/.vale/styles/spelling-exceptions.txt +++ b/.vale/styles/spelling-exceptions.txt @@ -283,6 +283,7 @@ subtyping sudo supernet supernets +swappable SVIs Telecom template_path diff --git a/CHANGELOG.md b/CHANGELOG.md index 8c3b36ac..6ad3e0f2 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -3,3 +3,77 @@ This project uses [*towncrier*](https://towncrier.readthedocs.io/) and the changes for the upcoming release can be found in . + +## [Schema Library - v2.0.0](https://github.com/opsmill/schema-library/tree/v2.0.0) - 2026-09-15 + +> [!WARNING] +> **Breaking changes in this release** +> +> Attribute and relationship names, types and cardinalities change across `base/dcim.yml`, `base/ipam.yml`, `base/location.yml` and most extensions, so loading v2.0.0 over data created with a v1.x schema requires migrating that data first. +> +> - Plan a migration rather than an in-place upgrade: loading v2.0.0 as-is over a v1.x deployment fails, or silently drops data, on the attributes and relationships listed below. +> - Re-point anything that loaded `extensions/modules` at `extensions/device_module`, and anything that loaded `extensions/topology` at `experimental/topology`. `extensions/users` has no replacement. +> - Update renamed paths: `extensions/sfp` to `extensions/transceiver`, `extensions/dwdm` to `extensions/optical_multiplexer`, and `extensions/firewall_policer` to `experimental/firewall_policer`. +> - Re-case stored values for the enums that became Dropdowns — `BGPSession.session_type` and the SNMP community and client enums — for example `EXTERNAL` to `external` and `Read-Only` to `read_only`. +> - Load either `extensions/location_minimal` or `extensions/location_site`, not both: they define the same `Location.Site` node, and `invoke load-all-schemas` no longer refuses the pair. + +### Removed + +- `extensions/users` is removed, along with the `UserGroup` and `UserAccount` nodes it defined. ([#75](https://github.com/opsmill/schema-library/issues/75)) +- `extensions/modules` is removed. Its generic is superseded by the ready-to-use `Module`/`ModuleType` pair in `extensions/device_module`, and `extensions/modules_linecards` and `extensions/modules_routing_engine` now depend on that extension instead. ([#75](https://github.com/opsmill/schema-library/issues/75)) +- `extensions/topology` is removed. `experimental/topology` is now the only topology model in the library, ending the overlap between two competing models. ([#75](https://github.com/opsmill/schema-library/issues/75)) + +### Added + +- Track the commercial terms behind a circuit with `extensions/circuit_contract`, which adds a `DcimCircuitContract` node carrying `contract_start`, `contract_end`, `monthly_cost` and `currency`, related to the circuit it covers. ([#67](https://github.com/opsmill/schema-library/issues/67)) +- Model optical transport networks with `experimental/optical_transport`, which covers four layers: the wavelength layer (the ITU-T G.694.1 grid, optical bands, DWDM channels, channel assignments and fiber mappings), the topology layer (logical optical nodes, passive multiplexers and fiber links as a graph), the equipment layer (transponder, amplifier and ROADM modules, ROADM degrees, WSS cross-connects and cable mappings), and the service layer (end-to-end optical services, optical paths and path segments). ([#68](https://github.com/opsmill/schema-library/issues/68)) +- Model standalone sites with `extensions/location_site`, which adds a `LocationSite` node (facility, physical address, timezone, status) with no region or country tier above it. It defines the same `Location.Site` node as `extensions/location_minimal`, so load one or the other. ([#75](https://github.com/opsmill/schema-library/issues/75)) +- Scope a tenant to the devices, address space and locations it is responsible for with `extensions/tenancy`, promoted out of `experimental/` and rebuilt to wire `Tenant` to `DcimGenericDevice`, `IpamPrefix`, `IpamIPAddress` and `LocationHosting`. It no longer depends on `extensions/circuit`; extending tenancy onto circuits is documented in `tenancy.yml` as a pattern to apply yourself. ([#75](https://github.com/opsmill/schema-library/issues/75)) +- Track swappable hardware as installed inventory with `extensions/device_module`, which adds a `DcimModuleBay` node for a physical slot on a device and a ready-to-use `Module`/`ModuleType` pair that installs into a bay. It replaces `extensions/modules`, which shipped only a generic to build on. A module is tracked once it is installed in a bay; spares awaiting installation are not modelled. ([#75](https://github.com/opsmill/schema-library/issues/75)) +- Capture circuit bandwidth, endpoint sides, VRF uniqueness enforcement, IP address lifecycle and SNMP scoping with the new `DcimCircuit.commit_rate`, `DcimCircuitEndpoint.side`, `IpamVRF.enforce_unique`, `IpamIPAddress.status` and `role`, `SnmpCommunity.devices` and `SnmpClient.ip_addresses` attributes and relationships. ([#75](https://github.com/opsmill/schema-library/issues/75)) +- Model power supplies alongside other modules with `extensions/device_module_psu`, which adds `DcimPSUModule` and `DcimPSUModuleType`, carrying `wattage` (Number) and `hot_swappable` (Boolean) on the type. It depends on `extensions/device_module`. ([#75](https://github.com/opsmill/schema-library/issues/75)) +- Record which registry assigned a block of address space by loading `extensions/ipam_aggregate`, which adds an `Aggregate` node for top-level IPv4/IPv6 blocks and an `RIR` node carrying a `private` flag. Previously top-level space could only be marked with a role on a generic prefix. ([#75](https://github.com/opsmill/schema-library/issues/75)) +- Model racks without adopting a full location hierarchy by loading `extensions/rack`, which takes `LocationRack` out of `extensions/location_minimal` and relates it to a site through an explicit `site`/`racks` relationship rather than hierarchical nesting. The rack gains `status`, `serial_number` and `asset_tag` attributes it did not have before. ([#75](https://github.com/opsmill/schema-library/issues/75)) +- Import the ports a module type declares — what NetBox lists under `interfaces`, `console-ports` and `power-ports` — with `extensions/module_port`. A `DcimModulePort` is a declaration parented by the module, carrying `name`, `category` (`interface`, `console`, `power`, `front` or `rear`), `port_type`, `mgmt_only` and `maximum_draw`, gathered in one typed `DcimGenericModule.ports` collection rather than five parallel relationships. Port names keep NetBox's `{module}` token verbatim, because a template is not bound to a bay; resolving the token and creating the real device interfaces is a generator step once the module is installed. ([#76](https://github.com/opsmill/schema-library/issues/76)) +- Carry NetBox's free-text bay label and a module's weight without losing either to rounding: `DcimModuleBay.bay_label` keeps the label distinct from the auto-populated, title-cased `label` attribute, and `DcimGenericModuleType.weight_grams` records a weight in grams, since integer kilograms round a transceiver or supervisor to `0`. ([#76](https://github.com/opsmill/schema-library/issues/76)) + +### Changed + +- Every node and generic in the library declares a single `display_label` string instead of a `display_labels` list, matching the current Infrahub schema format. ([#62](https://github.com/opsmill/schema-library/issues/62)) +- Aggregated interfaces are modelled consistently across extensions: `extensions/lag` adds `bundle_number`, renames `lag_members` to `bundle_members` and gives both sides the `interface__bundle` identifier, and `extensions/mlag` drops its own `mlag_id` attribute. In `extensions/transceiver`, the transceiver's peer moves from the `DcimInterface` generic to `InterfacePhysical`, and both sides share the `sfp__interface` identifier. ([#66](https://github.com/opsmill/schema-library/issues/66)) +- Model QinQ with dedicated node types instead of a role patched onto a generic VLAN: `extensions/qinq` is rebuilt around `IpamSVLAN` and `IpamCVLAN` on a new `IpamGenericVLAN` generic in `extensions/vlan`, replacing the `qinq_role` Dropdown on `IpamVLAN`. A `CVLAN`'s name is computed from its parent `SVLAN` and VLAN ID, and the file is renamed `qinq.yaml` to `qinq.yml`. ([#75](https://github.com/opsmill/schema-library/issues/75)) +- `extensions/hosting_cluster` renames `cluster_type` to `technology` and replaces the cloud-specific `aws` and `gcp` choices with a single `public_cloud`. ([#75](https://github.com/opsmill/schema-library/issues/75)) +- `extensions/firewall_policer` moves to `experimental/firewall_policer`. ([#75](https://github.com/opsmill/schema-library/issues/75)) +- Set an MTU that reflects the IP payload rather than the full Ethernet frame: `DcimInterface.mtu` changes its default from `1514`, the full Ethernet frame size, to `1500`, and becomes optional. ([#75](https://github.com/opsmill/schema-library/issues/75)) +- `IpamL2Domain` is replaced by `IpamVLANGroup`, scoped to a location through the new `IpamVLANGroupScope` mixin in the same way `extensions/ipam_aggregate` scopes to an RIR. ([#75](https://github.com/opsmill/schema-library/issues/75)) +- `BGPSession.session_type` and the SNMP community and client enums (`SnmpCommunityV2.access`, `SnmpCommunityV3.auth_protocol` and `privacy_protocol`) move from `kind: Text` with an `enum:` list to `kind: Dropdown`. Their stored values change case with the move, for example `EXTERNAL` to `external` and `Read-Only` to `read_only`. ([#75](https://github.com/opsmill/schema-library/issues/75)) +- `DcimCircuitEndpoint.name` is now computed from the circuit ID and the side, replacing free text. ([#75](https://github.com/opsmill/schema-library/issues/75)) +- Import and export more than one route target per VRF: `IpamVRF.import_rt` and `export_rt` move from `cardinality: one` to `many`, and the corresponding `IpamRouteTarget` relationship splits into `import_vrf` and `export_vrf`. ([#75](https://github.com/opsmill/schema-library/issues/75)) +- `VRRPGroup.group` is renamed to `vrid` and retyped from `Text` to `Number`, and `VRRPGroup.ip_address` becomes `ip_addresses`. ([#75](https://github.com/opsmill/schema-library/issues/75)) +- `DcimInterface.role` drops the `lag` choice, which `InterfaceLag` already models, and renames `cust` to `customer`. `DcimInterface.status` drops `deleted` and `outage` and is now mandatory. ([#75](https://github.com/opsmill/schema-library/issues/75)) +- The `extensions/location_minimal` hierarchy changes from `Country → Metro → Site` to `Region → Country → Metro → Site`, adding a region tier above country. `LocationRack` moves out to `extensions/rack`, and `Site.facility_id` is renamed to `facility`. ([#75](https://github.com/opsmill/schema-library/issues/75)) +- `LocationGeneric` and `LocationHosting` drop the `shortname` attribute, and their `human_friendly_id` switches to `name`. ([#75](https://github.com/opsmill/schema-library/issues/75)) +- `DcimCircuit.circuit_type` replaces the `upstream` choice with `internet_access` and adds `point_to_point`. ([#75](https://github.com/opsmill/schema-library/issues/75)) +- A circuit's location is now recorded on its endpoints rather than twice: `DcimCircuit` drops its own `location` relationship, and `DcimCircuitEndpoint.location` remains the place a circuit is tied to a `LocationHosting`. ([#75](https://github.com/opsmill/schema-library/issues/75)) +- Attach a prefix to whatever owns it through one `scope` relationship: `IpamPrefix` drops its separate `organization`, `location` and `gateway` relationships in favour of `scope` (`IpamPrefixScope`). Its `role` choices are fully replaced, from `loopback`, `management`, `public`, `server`, `supernet`, `technical` and `loopback-vtep` to `management`, `link`, `customer` and `backbone`. ([#75](https://github.com/opsmill/schema-library/issues/75)) +- `DcimDevice.status` drops the `drained` choice and adds `reserved` and `deprecated`. ([#75](https://github.com/opsmill/schema-library/issues/75)) +- `DcimModuleBay.position` becomes `Text` rather than a `Number` with `min_value: 1`, because bay positions in the NetBox device-type library are free-form. An Arista DCS-7508N alone uses `F1`–`F6` and `PSU-1`–`PSU-8` alongside `1`–`10`, and an A9K-AC-PEM-V3 starts its bays at `0`. ([#76](https://github.com/opsmill/schema-library/issues/76)) +- Import a line card as a reusable blueprint rather than as an installed card: `DeviceLinecard` in `experimental/modules_linecards` now enables `generate_template`, and its `slot` becomes optional, since a NetBox module type describes a model and carries no slot. ([#76](https://github.com/opsmill/schema-library/issues/76)) +- `extensions/sfp` is renamed to `extensions/transceiver`, broadening its scope from SFP alone to pluggable transceivers across form factors — SFP, SFP+, QSFP, QSFP28, QSFP-DD, OSFP, CFP and XFP. `extensions/dwdm` is renamed to `extensions/optical_multiplexer`. ([#89](https://github.com/opsmill/schema-library/issues/89)) +- `invoke load-all-schemas` no longer refuses mutually exclusive extension pairs. The `exclusive_with` key is removed from `.metadata.yml`, so the overlap between `extensions/rack` and `experimental/location_extended`, and between `extensions/location_minimal` and `extensions/location_site`, is now described in each extension's description rather than enforced at load time. ([#89](https://github.com/opsmill/schema-library/issues/89)) + +### Fixed + +- The Infrahub sidebar no longer shows two top-level entries pointing at the same records. `DcimGenericDevice`, `DcimChannelMapping` and `DcimOpticalDevice` are abstract generics whose concrete descendants already render their own top-level entries, so all three are now hidden from the auto-generated menu, in line with the other abstract generics in `base/dcim.yml`. ([#73](https://github.com/opsmill/schema-library/issues/73)) +- `experimental/security` loads again. It referenced kinds from the old `Infra` namespace, which had been renamed to `Dcim` for devices, interfaces and endpoints and `Ipam` for addresses and prefixes, so the load aborted with `SecurityFirewall Unable to find the generic InfraGenericDevice`. `SecurityFirewall` also now inherits `DcimPhysicalDevice`, matching `DcimDevice`, which the deployed schema already expected. ([#74](https://github.com/opsmill/schema-library/issues/74)) +- `DcimCircuit.enpoints` is corrected to `endpoints`. ([#75](https://github.com/opsmill/schema-library/issues/75)) +- `IpamIPAddress.interface` and `InterfaceLayer3.ip_addresses` now carry a matching `identifier`, so both sides resolve as one relationship instead of being treated as unrelated. ([#75](https://github.com/opsmill/schema-library/issues/75)) +- A BGP session's routing policies are no longer conflated with a peer group's. `RoutingBGPSession.import_routing_policies` and `export_routing_policies` pointed at the generic `RoutingPolicy` peer and reused the `bgp__import_policies` and `bgp__export_policies` identifiers already used by `RoutingBGPPeerGroup`; both now point at `RoutingPolicyBGP` and use distinct identifiers. ([#75](https://github.com/opsmill/schema-library/issues/75)) + +### Housekeeping + +- The changelog is now assembled from news fragments with [towncrier](https://towncrier.readthedocs.io/). + Add a file under `changelog/` named `..md` describing your change, where `` is one of + `security`, `removed`, `deprecated`, `added`, `changed`, `fixed` or `housekeeping`. A CI check fails a + pull request that carries none, unless it is labelled `ci/skip-changelog`. Releases up to and including + v1.4.11 are not back-filled. diff --git a/changelog/+towncrier.housekeeping.md b/changelog/+towncrier.housekeeping.md deleted file mode 100644 index 4f3444e1..00000000 --- a/changelog/+towncrier.housekeeping.md +++ /dev/null @@ -1,5 +0,0 @@ -The changelog is now assembled from news fragments with [towncrier](https://towncrier.readthedocs.io/). -Add a file under `changelog/` named `..md` describing your change, where `` is one of -`security`, `removed`, `deprecated`, `added`, `changed`, `fixed` or `housekeeping`. A CI check fails a -pull request that carries none, unless it is labelled `ci/skip-changelog`. Assembling the fragments -into `CHANGELOG.md` at release time is a follow-up; existing releases are not back-filled. diff --git a/docs/docs/release-notes/v2.0.0.mdx b/docs/docs/release-notes/v2.0.0.mdx new file mode 100644 index 00000000..4270f557 --- /dev/null +++ b/docs/docs/release-notes/v2.0.0.mdx @@ -0,0 +1,158 @@ +--- +title: Schema Library 2.0.0 +description: What changes in your modelling workflow when you move from Schema Library 1.x to 2.0.0. +--- + +Version 2.0.0 is a full pass over the base DCIM and IPAM schemas and most extensions, rather than an incremental update. After upgrading you can track swappable hardware as installed inventory, import the NetBox device-type library without losing bay positions or module ports, and record which registry assigned a block of address space. Attribute and relationship names, types, and cardinality change across the base schemas and most extensions, so data built on a 1.x schema has to be migrated before it will load. + +:::warning Breaking changes in this release + +Loading 2.0.0 over data created with a 1.x schema fails, or silently drops data, on the attributes and relationships that changed shape. + +- Plan a migration rather than an upgrade in place. +- Re-point anything that loaded `extensions/modules` at `extensions/device_module`, and anything that loaded `extensions/topology` at `experimental/topology`. `extensions/users` has no replacement. +- Update renamed paths: `extensions/sfp` to `extensions/transceiver`, `extensions/dwdm` to `extensions/optical_multiplexer`, and `extensions/firewall_policer` to `experimental/firewall_policer`. +- Re-case stored values for the enumerations that became dropdowns, for example `EXTERNAL` to `external`. + +See [Upgrade notes](#upgrade-notes) for the full list. + +::: + +## Release highlights + +- **Track modules and power supplies as device inventory.** `extensions/modules` shipped two generics and no node you could create a record with. `extensions/device_module` now ships `DcimModuleBay`, `DcimModule`, and `DcimModuleType`, and `extensions/device_module_psu` adds `DcimPSUModule` and `DcimPSUModuleType`. See [Track swappable hardware as installed inventory](#track-swappable-hardware-as-installed-inventory). +- **Import the NetBox device-type library without dropping module detail.** Bay positions were a number with a minimum of 1, which rejected every non-numeric bay, and the ports a module type declares had nowhere to go. Positions are now text, and `extensions/module_port` records the declared ports. See [Import the NetBox device-type library](#import-the-netbox-device-type-library). +- **Record which registry assigned a block of address space.** Top-level space could only be marked with a role on an ordinary prefix. `extensions/ipam_aggregate` adds an `Aggregate` node tied to an `RIR`. See [Model address space and VLANs closer to industry practice](#model-address-space-and-vlans-closer-to-industry-practice). +- **Attach a prefix to whatever owns it through one relationship.** A prefix carried separate `organization`, `location`, and `gateway` relationships. It now carries a single `scope` relationship, which any node inheriting `IpamPrefixScope` can satisfy. See [Model address space and VLANs closer to industry practice](#model-address-space-and-vlans-closer-to-industry-practice). +- **Model racks and standalone sites without a full location hierarchy.** A rack existed only as the bottom tier of `extensions/location_minimal`, and a site always needed the tiers above it. `extensions/rack` and `extensions/location_site` can each be loaded on their own. See [Model locations and tenancy at the level your network needs](#model-locations-and-tenancy-at-the-level-your-network-needs). +- **Scope tenancy to devices, prefixes, and locations.** The experimental tenancy schema linked a tenant to buildings and circuits only. `extensions/tenancy` now wires a tenant directly to devices, prefixes, addresses, and hosted locations. See [Model locations and tenancy at the level your network needs](#model-locations-and-tenancy-at-the-level-your-network-needs). + +## Track swappable hardware as installed inventory + +Devices with swappable hardware, such as fan trays, line cards, and power supplies, can be modelled as modules installed in a slot rather than as static attributes on the device. A module is tracked once it is installed in a bay; spares awaiting installation are not modelled. + +What changed: + +- Load `extensions/device_module` to get `DcimModuleBay`, a physical slot on a device, together with the `DcimModule` and `DcimModuleType` pair that installs into a bay. It replaces `extensions/modules`, which defined only the `DeviceGenericModule` and `DeviceGenericModuleType` generics and left you to build the concrete nodes yourself. +- Load `extensions/device_module_psu` alongside it to model power supplies as `DcimPSUModule` and `DcimPSUModuleType`, with `wattage` and `hot_swappable` recorded on the type. +- Track a patch panel's modules through the same `DcimModuleBay` mechanism as any other device. `extensions/patch_panel` no longer defines its own `DcimPatchPanelModule` node. +- Point `experimental/modules_linecards` and `experimental/modules_routing_engine` at `extensions/device_module`, which they now depend on. + +## Import the NetBox device-type library + +The NetBox device-type library describes a chassis in more detail than the 1.x model could hold, and a batch of module types failed to load outright. Importing that library now preserves bay positions, bay labels, module weights, and the ports a module type declares. + +What changed: + +- `DcimModuleBay.position` is text rather than a number with a minimum of 1. Bay positions in that library are free-form: an Arista DCS-7508N uses `F1` to `F6` and `PSU-1` to `PSU-8` alongside `1` to `10`, and an A9K-AC-PEM-V3 starts its bays at `0`. +- `DcimModuleBay.bay_label` carries the label NetBox supplies. An attribute named `label` is populated from `name` and title-cased when it is unset, so a separate attribute is what keeps "no label supplied" distinct from "label equals name". +- `DcimGenericModuleType.weight_grams` records a module weight in grams. Infrahub has no float attribute kind, so a weight in whole kilograms rounds a transceiver or a supervisor to `0`, which reads as data rather than as a missing value. +- Load `extensions/module_port` to record the ports a module type declares, which NetBox lists under `interfaces`, `console-ports`, and `power-ports`. A `DcimModulePort` is a declaration parented by the module, carrying `name`, `category`, `port_type`, `mgmt_only`, and `maximum_draw`, gathered in one `DcimGenericModule.ports` collection. Port names keep the `{module}` token verbatim, because a template is not bound to a bay; resolving the token and creating the real device interfaces is a generator step once the module is installed. +- Import a line card as a reusable blueprint: `DeviceLinecard` in `experimental/modules_linecards` enables `generate_template`, and its `slot` is optional, because a module type describes a model and carries no slot. + +## Model address space and VLANs closer to industry practice + +Address space, VLANs, and VRFs pick up the structure that industry practice assumes, and several values that could not previously be expressed at all. + +What changed: + +- Load `extensions/ipam_aggregate` to record top-level IPv4 and IPv6 blocks as `Aggregate` nodes tied to an `RIR`, which carries a `private` flag for space assigned by a private authority. +- Attach a prefix to its owner through the single `scope` relationship on `IpamPrefix`, replacing the separate `organization`, `location`, and `gateway` relationships. A location extension satisfies it by inheriting `IpamPrefixScope`. +- Choose a prefix role from `management`, `link`, `customer`, `backbone`, or none. The previous set of `loopback`, `management`, `public`, `server`, `supernet`, `technical`, and `loopback-vtep` is fully replaced. +- Import and export more than one route target per VRF. `IpamVRF.import_rt` and `export_rt` move from a cardinality of one to many, and the matching relationship on `IpamRouteTarget` splits into `import_vrf` and `export_vrf`. +- Model QinQ as dedicated node types rather than a role on an ordinary VLAN. `extensions/qinq` is rebuilt around `IpamSVLAN` and `IpamCVLAN` on the new `IpamGenericVLAN` generic, and the name of a customer VLAN is computed from its parent service VLAN and its VLAN ID. +- Group VLANs with `IpamVLANGroup`, which replaces `IpamL2Domain` and is scoped to a location by inheriting `IpamVLANGroupScope`. +- Set an interface MTU that reflects the IP payload: `DcimInterface.mtu` defaults to `1500` rather than `1514`, and is now optional. + +## Model locations and tenancy at the level your network needs + +Racks and sites are no longer tied to one location hierarchy, and a tenant can own the infrastructure it is responsible for rather than only the buildings and circuits around it. + +What changed: + +- Load `extensions/rack` on its own to model racks. `LocationRack` moves out of `extensions/location_minimal` and relates to a site through an explicit `site` and `racks` relationship instead of hierarchical nesting, and it gains `status`, `serial_number`, and `asset_tag`. +- Load `extensions/location_site` to model a site with no region or country above it. It defines the same `Location.Site` node as `extensions/location_minimal`, so load one or the other. +- The `extensions/location_minimal` hierarchy is now `Region`, `Country`, `Metro`, `Site`, adding a region tier above country, and `Site.facility_id` is renamed to `facility`. +- Load `extensions/tenancy`, promoted out of `experimental/`, to wire a `Tenant` to `DcimGenericDevice`, `IpamPrefix`, `IpamIPAddress`, and `LocationHosting`. It no longer depends on `extensions/circuit`; extending tenancy onto circuits is documented in `tenancy.yml` as a pattern to apply yourself. +- `LocationGeneric` and `LocationHosting` drop `shortname`, and their human friendly ID is built from `name`. + +## Model optical transport and circuit commercials + +Two areas the library did not cover before: optical transport networks, and the commercial terms attached to a circuit. + +What changed: + +- Load `experimental/optical_transport` to model an optical network across four layers: wavelength (the ITU-T G.694.1 grid, optical bands, DWDM channels, channel assignments, and fiber mappings), topology (logical optical nodes, passive multiplexers, and fiber links as a graph), equipment (transponder, amplifier, and ROADM modules, ROADM degrees, WSS cross-connects, and cable mappings), and service (end-to-end optical services, optical paths, and path segments). +- Load `extensions/circuit_contract` to record `contract_start`, `contract_end`, `monthly_cost`, and `currency` against the circuit a contract covers. +- Record a circuit's location on its endpoints. `DcimCircuit` drops its own `location` relationship, and `DcimCircuitEndpoint.location` is where a circuit is tied to a `LocationHosting`. +- `DcimCircuitEndpoint.name` is computed from the circuit ID and the side, replacing free text, and `side` is chosen from `a` or `z`. + +## Bug fixes + +- The Infrahub sidebar no longer shows two top-level entries pointing at the same records. `DcimGenericDevice`, `DcimChannelMapping`, and `DcimOpticalDevice` are abstract generics whose concrete descendants already render their own entries, so all three are hidden from the generated menu. +- `experimental/security` loads again. It referenced kinds from the old `Infra` namespace and aborted with `SecurityFirewall Unable to find the generic InfraGenericDevice`. `SecurityFirewall` also inherits `DcimPhysicalDevice` now, matching `DcimDevice`. +- A BGP session's routing policies are no longer conflated with a peer group's. `RoutingBGPSession.import_routing_policies` and `export_routing_policies` reused the identifiers already used by `RoutingBGPPeerGroup`; both now point at `RoutingPolicyBGP` and use their own identifiers. +- `IpamIPAddress.interface` and `InterfaceLayer3.ip_addresses` carry a matching identifier, so both sides resolve as one relationship. +- `DcimCircuit.enpoints` is corrected to `endpoints`. + +## Minor changes + +### Documentation + +- Every base and extension schema file carries a header noting that it is a starting point rather than a finished production model, and pointing to `docs.infrahub.app` or OpsMill for architectural review. +- The schema reference pages are regenerated for the 2.0.0 model, with new pages for the extensions added in this release. + +### Developer experience + +- The changelog is assembled from news fragments with towncrier, and a CI check fails a pull request that carries none. +- Every node and generic declares a single `display_label` string rather than a `display_labels` list. + +### Reliability + +- `invoke load-all-schemas` no longer refuses mutually exclusive extension pairs. The `exclusive_with` key is gone from `.metadata.yml`, so the overlap between `extensions/rack` and `experimental/location_extended`, and between `extensions/location_minimal` and `extensions/location_site`, is advisory. + +## Upgrade notes + +### Existing 1.x data + +If: you have data created with a 1.x schema. + +Then: migrate that data before loading 2.0.0. + +Notes: attribute and relationship names, types, and cardinality changed across `base/dcim.yml`, `base/ipam.yml`, `base/location.yml`, and most extensions. Loading 2.0.0 in place fails, or silently drops data, on everything listed above. + +### Removed and relocated extensions + +If: your schema loads `extensions/modules`, `extensions/topology`, `extensions/users`, `extensions/sfp`, `extensions/dwdm`, or `extensions/firewall_policer`. + +Then: update the path, or drop the extension. + +Notes: `extensions/modules` becomes `extensions/device_module`, `extensions/topology` becomes `experimental/topology`, `extensions/sfp` becomes `extensions/transceiver`, `extensions/dwdm` becomes `extensions/optical_multiplexer`, and `extensions/firewall_policer` becomes `experimental/firewall_policer`. `extensions/users` is removed with no replacement. + +### Enumerations that became dropdowns + +If: you store values for `BGPSession.session_type`, `SnmpCommunityV2.access`, `SnmpCommunityV3.auth_protocol`, or `SnmpCommunityV3.privacy_protocol`. + +Then: re-case the stored values. + +Notes: `EXTERNAL` becomes `external`, `Read-Only` becomes `read_only`, `MD5` becomes `md5`, and `DES` becomes `des`. The attribute kind moves from text with an enumeration to a dropdown. + +### Choices that were removed + +If: you store `lag` on `DcimInterface.role`, `deleted` or `outage` on `DcimInterface.status`, `drained` on `DcimDevice.status`, `upstream` on `DcimCircuit.circuit_type`, or any prefix role other than `management`. + +Then: map those values to a choice that still exists. + +Notes: `cust` on `DcimInterface.role` is renamed to `customer`, and `upstream` on `DcimCircuit.circuit_type` is replaced by `internet_access`. `DcimInterface.status` is also mandatory now, so every interface needs a value. + +### Overlapping location extensions + +If: you load `extensions/location_minimal` together with `extensions/location_site`, or `extensions/rack` together with `experimental/location_extended`. + +Then: load one of each pair. + +Notes: each pair defines the same node, and `invoke load-all-schemas` no longer stops you from loading both. + +## Full changelog + +The complete list of changes, with a link to the pull request behind each one, is in [CHANGELOG.md](https://github.com/opsmill/schema-library/blob/main/CHANGELOG.md). The commit range is [v1.4.11...v2.0.0](https://github.com/opsmill/schema-library/compare/v1.4.11...v2.0.0). diff --git a/docs/sidebars.ts b/docs/sidebars.ts index a60e4e1d..80c6602f 100644 --- a/docs/sidebars.ts +++ b/docs/sidebars.ts @@ -14,6 +14,17 @@ const sidebars: SidebarsConfig = { }, ], }, + { + type: 'category', + label: 'Release notes', + collapsed: true, + items: [ + { + type: 'autogenerated', + dirName: 'release-notes', + }, + ], + }, 'contributing', ] };