Skip to content

docs: add release notes for Schema Library 2.0.0 - #94

Open
BeArchiTek wants to merge 1 commit into
mainfrom
docs/release-notes-2.0.0
Open

BeArchiTek wants to merge 1 commit into
mainfrom
docs/release-notes-2.0.0

Conversation

@BeArchiTek

Copy link
Copy Markdown
Contributor

Summary

Schema Library 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. Anyone upgrading from 1.x has to read commits to find out what moved. This assembles the 2.0.0 changelog and adds a release-notes page to the documentation site, so the upgrade path is written down before the tag is cut.

Key Changes

  • Readers can see what 2.0.0 changes for them: CHANGELOG.md now carries a 2.0.0 section, assembled from news fragments covering the user-facing work merged since v1.4.11 (roughly eleven months and fifteen pull requests).
  • Anyone planning an upgrade is warned before they start. Both the changelog and the docs page open with the breaking-change callout: 2.0.0 renames and retypes attributes and relationships across the base schemas and most extensions, so v1.x data has to be migrated rather than upgraded in place.
  • The documentation site gains a Release notes section. The 2.0.0 page is organised by what someone can do differently after upgrading — track modules and power supplies as installed inventory, import the NetBox device-type library, model address space and VLANs, model locations and tenancy, model optical transport — followed by bug fixes, minor changes and upgrade notes.
  • Upgrade notes spell out the actions required: removed and relocated extensions, enumerations that became dropdowns and whose stored values change case, choices that disappeared, and the location extensions that now overlap.

Notes for reviewers

Every entry was verified against the schema files on this branch rather than taken from the originating pull request descriptions. Several of those descriptions did not match what shipped, and the entries follow the schema files where they disagreed:

The description said The schema files say
mtu moved to InterfacePhysical still on the DcimInterface generic; default 1514 to 1500, now optional
IpamPrefix.role keeps supernet supernet is dropped; the set is management, link, customer, backbone
SnmpClient.ip_address ships as ip_addresses
RIR flag is_private ships as private
QinQ built on GenericVLAN IpamGenericVLAN, defined in extensions/vlan
PSU type carries hotswappable ships as hot_swappable, on DcimPSUModule / DcimPSUModuleType
(not mentioned) DcimCircuit.location was removed; location now lives on the endpoint
a load_demo_ipam_dcim invoke task was added no such task exists in tasks/schemas.py, so it is not claimed

Two judgement calls worth a second opinion:

  • The version number. 2.0.0 reflects the namespace and attribute renames being breaking for existing consumers.
  • Scope. Only user-facing changes were written up. Documentation regeneration, CI and dependency chores in the same window were deliberately left out.

Documentation Updates

  • docs/docs/release-notes/v2.0.0.mdx — new page
  • docs/sidebars.ts — Release notes category added

Test Plan

  • uv run invoke docs.build — builds clean, zero broken links or anchors
  • Markdown lint over CHANGELOG.md and the new page — clean
  • Vale over docs/ — 0 errors, 0 warnings
  • Watch the markdown-lint and validate-documentation CI jobs

Assisted-by: opsmill-docs-writing-release-notes 0.1.0
Assisted-by: opsmill-dev-commit 0.1.0
Assisted-by: opsmill-dev-pr 0.2.0

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) <noreply@anthropic.com>
@BeArchiTek BeArchiTek added type: documentation Improvements or additions to documentation claude-code-assisted ci/skip-changelog No changelog fragment required labels Sep 15, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

ci/skip-changelog No changelog fragment required claude-code-assisted type: documentation Improvements or additions to documentation

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant