overview
overview copied to clipboard
ansible-collections
Update README.rst
Added link to RFC2119 to describe use of MUST and SHOULD etc as per feedback from community WG meeting.
SUMMARY
ISSUE TYPE
- Docs Pull Request
COMPONENT NAME
README.rst
ADDITIONAL INFORMATION
This document does not use any of these wordings. Should this maybe have been a PR for https://github.com/ansible-collections/ansible-inclusion/blob/main/README.md ?
@Ompragash what do you think? Did I pop this quickie PR on the wrong file?
@samccann thanks for the quick PR!:) I was thinking of having something like the below in the primary docs somewhere and then have a reference for it in ansible-collections/ansible-inclusion and ansible-collections/overview wherever required.
Notational Conventions
=================
The keywords "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" are to be interpreted as described in [RFC 2119](http://tools.ietf.org/html/rfc2119).
The keywords "unspecified", "undefined", and "implementation-defined" are to be interpreted as described in the [rationale for the C99 standard](http://www.open-std.org/jtc1/sc22/wg14/www/C99RationaleV5.10.pdf#page=18).
An implementation IS compliant if it satisfies all the MUST, REQUIRED, and SHALL requirements.
An implementation IS NOT compliant if it fails to satisfy one or more of the MUST, REQUIRED, or SHALL requirements.
Any thoughts?
@Ompragash - we could put it in the collection contributor guide on docs.ansible.com, but I don't know that we've ever evaluated those docs to ensure they actually follow this convention. That's why I considered adding it instead to the appropriate README.md file (in whichever repo we know is following this convention).
I could put links to both of those repos into the collection contributor guide and then add the note to say 'the following repositories follow these notational conventions.." with your note above.