Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 2 additions & 1 deletion en/guide/define_xml_element.md
Original file line number Diff line number Diff line change
Expand Up @@ -182,7 +182,8 @@ The main rules for messages are:
- The total payload size (for all fields) must not exceed 255 bytes.
- All other fields are optional.
- There must be at least one field and no more than 64 fields.
- The `<wip/>` tag may be added to messages that are still being tested.
- The [`<wip>`](../guide/xml_schema.md#wip) tag marks messages that are still being tested.
Definitions in `development.xml` must have one, with the date they were proposed and the standard comment after it.
- Fields:
- must have unique `name`s within a message.
- _should_ have a description.
Expand Down
21 changes: 13 additions & 8 deletions en/guide/xml_schema.md
Original file line number Diff line number Diff line change
Expand Up @@ -365,23 +365,28 @@ Work in progress elements have been proposed for inclusion in the standard, but
They should not be included in release builds.
The generator toolchain can be configured to conditionally build messages omitting the `<wip>` entries.

Generally new elements should be defined in `development.xml`, and any definitions in that file are considered WIP by default.
The `wip` element is intended primarily for indicating WIP additions to `common.xml` that for whatever reason could not be added to `development.xml`.
New definitions should be added to `development.xml` by preference, and `common.xml` only if necessary (such as for a new value for an enum already defined in `common.xml`).
Everything in `development.xml` is unstable and may change, and each top level definition must be marked with a `<wip>` element.

Once the associated definition has been tested, it may be accepted into `common.xml` and the `<wip>` tag removed.

The tag is usually applied like this (including the comment):
The tag is applied like this, with the date that the definition was proposed, and followed by the comment:

```xml
<wip/>
<wip since="2026-03"/>
<!-- This message is work-in-progress and it can therefore change. It should NOT be used in stable production environments. -->
```

The comment starts "This message", "This enum", "This command" (for a `MAV_CMD` entry) or "This entry" (for any other enum entry), to match what is marked.

Attributes:

- `since` (optional): A datestamp indicating when the corresponding element was proposed.
This should be formatted as such as `YYYY-MM`
- `since`: A datestamp indicating when the corresponding element was proposed, formatted as `YYYY-MM`.
This hints to the maintainer team when WIP elements should be reviewed for addition or removal.
- The attribute is optional in the MAVLink schema, so a dialect may use a bare `<wip/>`.
- It is required in the XML files managed by the MAVLink project (`minimal.xml`, `standard.xml`, `common.xml` and `development.xml`), and must not be a date in the future.

In the files managed by the MAVLink project the date and the comment are checked in CI by `scripts/xml_consistency_check.py`.

Nested elements

Expand All @@ -403,7 +408,7 @@ The element is usually applied like this:
Attributes:

- `since` (required): A datestamp indicating when the new element was accepted into files managed by the MAVLink team.
This should be formatted as such as `YYYY-MM`.
This should be formatted as such as `YYYY-MM`, and must not be in the future.
- `replaced_by` (required): The name of the definition that supersedes this element.

Nested elements
Expand Down Expand Up @@ -434,7 +439,7 @@ For example, where we show that `MAV_CMD_REQUEST_PROTOCOL_VERSION` is deprecated
Attributes:

- `since` (required): A datestamp indicating when the element was deprecated.
This should be formatted as such as `YYYY-MM`.
This should be formatted as such as `YYYY-MM`, and must not be in the future.
- `remove_on_date` (optional): The date at which the deprecated element is expected to be removed.
- `replaced_by` (required): The name of the definition that replaces this element.

Expand Down
Loading