[Vote ended on 2022-08-03] Disconnect between Docs and Ansible-lint in regards to truthy statements (booleans)

[p-rintz]

Hi everyone,

I had brought this up on Matrix and was asked to create an issue here after some discussion.

Summary

Currently, the Ansible Docs will always use yes/no for truthy statements.
However, Ansible-Lint will throw an error if yes/no is used and will enforce the use of true/false.

yaml: truthy value should be one of [false, true] (yaml[truthy])

This is rather inconsistent and (at least on my part) leads to confusion.

In a discussion on Matrix it was found that Ansible Docs & Automation Hub both enforce the use of yes/no use for truthy statements via an override.

Related issues (where this issue was also brought up, but wasnt followed up on):
ansible/ansible#77581
ansible/ansible-lint#1954

[felixfontein]

We had a short discussion on this on June 24th, 2021. In there, some links were burried out:

• The PR in ansible/ansible which changed docs to yes/no: Improve default values and choices in module docs ansible/ansible#36901 (@sivel said during that IRC discussion that the reasoning for yes/no, as he remembers, is that true/false is more familiar with programmers, but feels awkward for non-programmers)
• #ansible-docs meeting which allowed both yes/no and true/false in documentation: https://meetbot.fedoraproject.org/ansible-docs/2019-01-08/docs_working_group.2019-01-08-15.31.html
• #ansible-docs meeting where boolean standardization was discussed: https://meetbot.fedoraproject.org/ansible-docs/2020-07-14/docs_working_group_aka_dawgs.2020-07-14-14.31.html

The last meeting ended with an action "create a proposal for creating consistency in the boolean values", which I think didn't happen.

[gundalow]

Thanks for raising this. I know the current situation is confusing.

I've asked @cidrblock to take a look at this, he's one of the Ansible Architects, and responsible for ansible-lint. He's on holiday though and should be back next week.

[samccann]

Regardless of ansible-lint, we should decide again whether that 'user-friendly' override to yes/no is actually user-friendly.
PRs that seem to have set this docs default:
ansible/ansible#37488
ansible/ansible#42361

We also failed to update text/examples beyond the boolean. Here is an example where the text talks about true but the docs override has the parameter using yes/no

[samccann]

Another older PR closed that proposed true/false consistency - ansible/ansible#49072

[felixfontein]

I personally prefer true/false over yes/no. Especially since they are YAML 1.2 booleans, while yes/no are not. (Which seems to be the main reason why ansible-lint seems to prefer true/false.)

We also failed to update text/examples beyond the boolean. Here is an example where the text talks about true but the docs override has the parameter using yes/no

Actually that option was added after the yes/no default was decided. We did talk about this multiple times, and at some time we also said that both true/false and yes/no are OK in docs. I wrote that description back then in this way because I preferred (and still prefer) true/false.

[samccann]

It was agreed in the DaWGs (Docs working group) meeting to back out the docs override that is forcing all boolean parameters to say yes/no in the docsite.

[sivel]

Of note here, and not that it couldn't change, but the core team had discussed that if we started supporting YAML 1.2, we would likely add support back in for 1.1 booleans.

Also one reason that lint has problems is that it's using ruamel.yaml for various reasons including rewriting YAML into a consistent format, but that library only has a 1.2 emitter. This however can be resolved in ruamel.yaml by setting yaml.boolean_representation = ['no', 'yes']

[cidrblock]

I'm inclined to suggest we consistently use true/false while continuing to support the older yaml 1.1 variants in ansible/ansible.

Some reasons include:

• The yaml 1.2 specification is limited to true/false
• Alignment with both JSON and python which use true/false
• I suspect nearly all of the far side systems ansible interacts with use true/false
• Fewer surprises when using yaml libraries across multiple languages

WRT ansible-lint, taken from the docs "The goal of ansible-lint is to ensure the content created by different people has a similar look and feel. This makes the adoption and use of Ansible content easier in the community and enterprise. By keeping the number of configurable features at a minimum, consistent outcomes between authors can be achieved." https://ansible-lint.readthedocs.io/en/latest/philosophy/

This is the main reason why ansible-lint typically suggests one way to do something but still allows for customization by enabling/disabling rules so an organization can make and adhere to a custom rule set.

I'm going to guess it will be a long time before ansible/ansible would drop support for the YAML 1.1 variants but since we can't influence the entire eco-system of tools and systems ansible interacts with, true/false reflecting the YAML 1.2 specification seems to be the best path forward to maintain consistency.

[mariolenz]

@cidrblock I think you have some strong arguments there for using true/false.

Considering your last argument (Fewer surprises when using yaml libraries across multiple languages) I would contest that yes/no is actually user-friendly. It is not for people using ansible and also other tools that follow the usual true/false standard for booleans.

[bcoca]

Python uses True/False, not true/false, so you only align with JSON .. which is the least relevant format for Ansible input validation and conversions.

YAML 1.2 also requires a pragma at the start of any document, since most playbooks don't have it they should be interpreted as 1.1 in any case.

[mariolenz]

Python uses True/False, not true/false, so you only align with JSON .. which is the least relevant format for Ansible input validation and conversions.

Yep, but true/false is still closer to True/False (just uppercase/lowecase difference) than it is to yes/no ;-)

[bcoca]

Except Python also takes as false '', [ ], 0, {}, None and truth can be 'any string' or non 0 number, any container type with elements, etc. Not really a road to go down as each component has it's own set, what Ansible does internally is try to normalize them, using the YAML 1.1 as the basis.

[mariolenz]

Except Python also takes as false '', [ ], 0, {}, None and truth can be 'any string' or non 0 number, any container type with elements, etc.

And how exactly is this a reason to use yes and no? With the same argument, you could also justify using foo and bar...

what Ansible does internally is try to normalize them, using the YAML 1.1 as the basis.

Whatever Ansible does internally, it accepts true and false afaik. So I don't think this is an argument against consistently using true / false in the documentation.

[samccann]

From the documentation perspective, we are leaning toward true/false instead of the current yes/no interpretation for booleans.

[samccann]

Adding...it wasn't an override from docs as i thought - documentation has to decide what to put in the output for boolean, so we chose yes/no back in 2018.

[felixfontein]

I think we should have a vote on this, with options maybe being a) true/false, b) yes/no, c) True/False, d) let every program handle output as it wants. Right now we basically have d), where docs.ansible.com uses b), ansible-doc uses c), and ansible-lint uses a).

[bcoca]

@mariolenz I'm not advocating for either, just pointing out the holes in your argument.

IMHO documentation should favor 'the accepted way' of doing things, but should not exclude the other ways since that will then cause users to be surprised and commit errors when encountering other forms (for example the YAML Norway ISO issue ...).

In this case yes/no was voted on as being more user friendly and understandable, the main reason against it is 'how ruamel does it', which is used by ansible-lint. I"m not against changing the default display, I'm just against using invalid reasons to arrive to the conclusion.

[mariolenz]

@bcoca

I'm not advocating for either, just pointing out the holes in your argument.

I don't see a hole in the argument. Just because Python (and many other languages) evaluate a lot of things to True or False, if people want to express a Boolean, that is a yes/no value, they usually use True or False. At least in the scripting and programming languages that I know. Even SQL uses TRUE and FALSE. And I think PowerShell uses $true and $false, but it's still more or less the same.

In GUIs, you often find yes and no. But in text-based tools, I mainly know true and false... well, with differences in uppercase / lowercase and, in PowerShell, an added $ in front.

IMHO documentation should favor 'the accepted way' of doing things, but should not exclude the other ways since that will then cause users to be surprised and commit errors when encountering other forms (for example the YAML Norway ISO issue ...).

For me, 'the accepted way' to express Boolean values is true and false. Of course, it should be documented that yes and no are valid alternatives.

Btw: I've never heard of the YAML Norway ISO issue, but it sounds interesting. I'll try to find the time and look it up. Thanks!

In this case yes/no was voted on as being more user friendly and understandable, the main reason against it is 'how ruamel does it', which is used by ansible-lint. I"m not against changing the default display, I'm just against using invalid reasons to arrive to the conclusion.

Apart from my personal opinion: The more people using ansible-lint, the more 'the accepted way' might move into the direction of using true and false. If only to shut up ansible-lint ;-P

[bcoca]

Your point was building on cidr's that true/false normalized to Python standards , only reason i went down this rabbit hole.

the norway issue:

myisocode: no 

no is the ISO for Norway, YAML instead returns a boolean false unless you !!str the variable (Norway went as far as getting new alternative ISO code).

[felixfontein]

Suggestion for a vote formulation: https://gist.github.com/felixfontein/9e532485a081266e6e98d9f0469583d2 I will likely create a vote after today's meeting, so if you want something changed, please comment there until then :)

[mariolenz]

Your point was building on cidr's that true/false normalized to Python standards , only reason i went down this rabbit hole.

Sorry, maybe I've expressed myself poorly. I don't want to normalize to Python standards. I just wanted to say that true / false (no matter if lowercase, Upercase or ALLUPPERCASE) is more common than yes/no. I see Python just as an example for this.

[felixfontein]

I created a vote on this in #120. Please vote there. If you want to discuss something, please do it here though :)

[felixfontein]

@gundalow @thaumos since the current vote count for the steering committee is rather tight (6 votes or 1, 4 votes for 2), I think it would be good if you would also vote in #120 (assuming you have an opinion on this :) ).

[samccann]

Issues have been opened for collections so going to close this and thanks everyone for the help!