I would give zuul-jobs roles a good example of big repository with well defined policies about how to write roles, including requirements for variables names and ways to document arguments. There is already work done towards adding support in ansible for declaring in/out variables for roles. They will likely look similar to how module arguments are now documented and reside inside "meta" folder. Still, until then use of README inside each role looks like a decent solution.
On 2 Nov 2020, at 18:24, Jesse Pretorius <jesse@odyssey4.me> wrote:
t reminds me - to really make roles work more like an API, we should also probably implement tests which determine whether the API is changing in an acceptable way. We'd have to agree what 'acceptable' looks like - at the very least, I would imagine that we should be enforcing the