docs: complete Management Procedures spec versions, document the citation convention - #1879
Open
kewde wants to merge 6 commits into
Open
docs: complete Management Procedures spec versions, document the citation convention#1879kewde wants to merge 6 commits into
kewde wants to merge 6 commits into
Conversation
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## kewde/refactor-procedures-2 #1879 +/- ##
============================================================
Coverage 97.79% 97.79%
============================================================
Files 181 181
Lines 13202 13202
============================================================
Hits 12911 12911
Misses 291 291
🚀 New features to boost your workflow:
|
kewde
force-pushed
the
kewde/knx-spec-references
branch
from
July 28, 2026 18:22
4df0451 to
96204f7
Compare
kewde
force-pushed
the
kewde/knx-spec-references
branch
from
July 28, 2026 19:54
c2aaac7 to
168a2f2
Compare
kewde
force-pushed
the
kewde/knx-spec-references
branch
from
August 1, 2026 07:56
168a2f2 to
2e31ed8
Compare
… CLAUDE.md Finish adding the Management Procedures 03.05.02 spec version to the remaining files PR #1832 didn't touch (nm_individual_address_read, nm_individual_address_serial_number_read/write, and their tests). Add CLAUDE.md documenting the "KNX v<version> - <Document Title> <number> - <paragraph>" citation format, why the version matters (different KNX documents carry different versions - Transport Layer is v01.02.02, Management Procedures is v02.01.02), and the hard rule to never guess a document's version/title/number - ask first. Lists the documents with confirmed versions so far and the ones still needing input (Application Layer 03.03.07, LTE Application Layer, Routing 3.8.5, Communication Medium KNX IP 3.2.6).
Add the confirmed version to every Application Layer (03.03.07) spec citation across xknx/telegram/apci.py, xknx/management/management.py, xknx/exceptions/exception.py, xknx/cemi/cemi_frame.py and test/telegram_tests/apci_test.py, following the same "KNX v<version> - <Document Title> <number> - <paragraph>" convention already applied to Management Procedures 03.05.02. Note this document's version (v02.01.01) is different from Management Procedures' (v02.01.02), even though both are cited side by side in management.py - update CLAUDE.md to make that explicit so it isn't assumed to be one shared "current" version next time.
… citations Add the confirmed versions to the remaining spec citations: - Routing (3.8.5) -> v01.05.02 - Communication Medium KNX IP (3.2.6) -> v01.01.02 - Logical Tag Extended (10.1, previously cited only as "KNX Logical Tag Extended (LTE) Application Layer" with no document number) -> v01.02.02 Versions cross-checked against the local KNX Standard v3.0.0 PDF corpus (added alongside the repo, converted to text with pdftotext for grepping) - document the corpus location in CLAUDE.md as the reference to check first before asking for a version next time. Every document xknx currently cites now has a confirmed version.
That section pointed at a local, machine-specific PDF folder outside the repo - not something relevant to other contributors reading this file in the public repo.
Add a section explaining that document numbers start with a Volume number (xknx cites almost exclusively Volume 3 - System Specifications, plus Volume 10 - Application Specific Standards for the LTE extension), and that the <volume>.<chapter>.<subchapter> numbering scheme has no bearing on a document's version - two documents in the same volume can still be versioned independently. Keeps the rationale for "always ask, never guess the version" grounded in how the standard is actually structured, without referencing any local file layout.
Retitle to "xknx contributor conventions" and nest the existing KNX Standard citation guidance under it, then add three more sections that came up repeatedly this session: - Management procedures naming convention: summarizes the xknx(...)/_conn(...) split, pointing at xknx/management/procedures/__init__.py as the canonical, code-adjacent version rather than duplicating it in full. - Changelog: where entries go (# Unreleased changes), how to pick a ### category, and that breaking changes need a before/after snippet. - Pull requests: use .github/pull_request_template.md rather than a free-form description. Left out anything about local dev workflow (venv setup, running tests/lint) - that's our own shortcut, not a project convention worth documenting for other contributors.
kewde
force-pushed
the
kewde/knx-spec-references
branch
from
August 1, 2026 22:22
2e31ed8 to
70b2247
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Description
Stacked on #1832.
KNX v02.01.02 - Management Procedures 03.05.02 - ...to the spot-checks in refactor(management): add composable connection-based procedure cores #1832 that missed some files (nm_individual_address_read,nm_individual_address_serial_number_read/_write, and their tests).CLAUDE.mddocumenting the citation format and, importantly, that the version number must never be guessed — different KNX documents carry different versions (Transport Layer isv01.02.02, Management Procedures isv02.01.02), so an unconfirmed version is worse than no version at all.This is a first pass — several other documents cited in the codebase (Application Layer 03.03.07, the LTE Application Layer extension, Routing 3.8.5, Communication Medium KNX IP 3.2.6) still need their versions confirmed before they can get the same treatment;
CLAUDE.mdlists them explicitly so that's tracked rather than silently guessed.Fixes # (issue)
Type of change
Checklist