This issue came out of a discussion on this PR.

The current documentation regarding the "stability" field requirement for new commands in the idl could be a little clearer on how it relates to a command forming part of the stableAPI or not.

After reading the documentation, we incorrectly added the "stability" field to a command which did not have an apiVersion set.

The documentation seemed to indicate that the "stability" field was required for any new command, not just commands that are part of the stableAPI.

Adding a new command parameter or reply field requires the stability field. This field indicates whether the command parameter/reply field is part of the Stable API. There are three options for field: unstable, internal, and stable. If you are unsure what the stability field for the new command parameter or reply field should be, it should be marked as stability: unstable.

The idl provided a helpful error message, and we thought it would be nice to have the documentation also point out this restriction:

distinct_command.idl: (73, 16): ID0073: Command 'distinct' specifies 'stability' but has no 'api_version'

This may be a superfluous request, given that this document is titled STABLE_API_README.md, however, since this document may often be used as a point of reference by engineers when adding a new command (whether it is part of the stable api or not), it may be beneficial to clarify that the "stability" field is only required for commands that should be part of the stable api (i.e api_version=1).