Skip to content

Add XML Lifecycle Management guide (incl. C/C++ WIP/deprecated/superseded diagnostics) - #802

Open
hamishwillee wants to merge 2 commits into
mavlink:masterfrom
hamishwillee:xml-lifecycle-management
Open

hamishwillee wants to merge 2 commits into
mavlink:masterfrom
hamishwillee:xml-lifecycle-management

Conversation

@hamishwillee

@hamishwillee hamishwillee commented Nov 18, 2026 •

Copy link
Copy Markdown
Collaborator

@peterbarker This is how Claude thinks it works, along with my tweaks so I "think" I understand it. Please sanity check.

Adds a new guide page, XML Lifecycle Management, covering:

  • Lifecycle: how definitions move through development.xml → common.xml → standard.xml, and the <wip> / <superseded> / <deprecated> elements. Includes a note on the stakeholder-agreement review gates at each step.
  • Compile-time diagnostics (C/C++ only): the opt-in macros added in Add opt-in compile-time diagnostics for WIP/deprecated/superseded MAVLink messages and enum entries ArduPilot/pymavlink#1284. Projects can get a warning or an error where they use WIP, deprecated, or superseded definitions. For example, they can block WIP use in release builds and find deprecated uses ahead of removal. The page covers:
    • the macro sets
    • how the attribute mechanism works
    • C, C++ 11, and release/dev CMake examples
    • attribute choice
    • limitations
    • generated test suites

The page is linked from SUMMARY.md (Guide section), from the C and C++ 11 library pages, and from the XML schema "Lifecycle Elements" section.

Commits

  1. Add XML Lifecycle Management guide: the new page and links, plus compiler terms added to the cspell.json word list.
  2. xml_schema: correct generator claims for <wip>/<deprecated>: a separate wording fix. The <wip> section said the generator can be configured to omit WIP entries, but no mavgen option does this. The claim is replaced with a pointer to the diagnostics. The matching commented-out <deprecated> line is replaced the same way.

Verification

  • The C and C++ 11 examples were compile-checked with gcc 13 and clang 18 against headers generated by pymavlink at the #1284 merge commit (e9ab78b6). Each produces the diagnostic the page describes. Builds without the macros stay clean under -Werror. The CMake release/dev snippet was also checked.
  • yarn docs:build passes, and yarn linkcheck reports no issues on the changed pages.

Note: mavlink/mavlink's pymavlink submodule and c_library_v2 don't include #1284 yet.

🤖 Generated with Claude Code

hamishwillee and others added 2 commits November 18, 2026 18:41
New guide page explaining how MAVLink definitions move through
development.xml / common.xml / standard.xml and the <wip>, <superseded>
and <deprecated> lifecycle elements, and how C/C++ projects can get
compile-time diagnostics for flagged definitions using the opt-in macros
added in ArduPilot/pymavlink#1284.

Adds the page to SUMMARY.md and links to it from the C and C++11 library
pages and the XML schema "Lifecycle Elements" section. Adds compiler
terms used on the page to the cspell word list.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The <wip> section said the generator toolchain can be configured to
build messages omitting <wip> entries; no mavgen option does this.
Replace it (and the matching commented-out <deprecated> line) with a
pointer to the C/C++ compile-time diagnostics in the XML Lifecycle
Management guide.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@hamishwillee
hamishwillee marked this pull request as ready for review November 18, 2026 07:46
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant