[Vote ended on 2022-08-03] Vote on https://github.com/ansible-community/community-topics/issues/116: normalize booleans in documenation, ansible-lint, ansible-doc, ...?

[felixfontein]

Vote on #116. We aim at normalizing boolean options in documentation, ansible-lint, ansible-doc, AH/GalaxyNG, and other places as follows:

1. true and false
2. yes and no
3. True and False
4. no normalization (basically what we have right now)

Please mention your preferred option as your vote. If you prefer more than one, please give a preference.

Also please note that if we decide on one of options 1) to 3), this does not mean that a) no other possibilities will be mentioned in the documentation anymore, and b) we can force anyone to use these normalized values.

Please review issue #116 before voting so you are informed of the issues with each option.

[felixfontein]

My order of preference is 1 > 2 > 4 > 3

[jillr]

Order of preference:
1
3
2
4

[p-rintz]

My order of preference: 1 > 3 > 2 > 4

[samccann]

1 > 2 > 4 > 3

[briantist]

1 > 2 > 4 > 3

[ssbarnea]

1, 1, 1, 1 -- I like following specs, and we happen to have two that we can follow. Fixing current situation is only about fixing docs, without any code change, as it is not about preventing use of old values, is only about documenting the optimal/standard values. I have no idea if in 2.5 years from now we might remove support for old YAML 1.1 boolean-aliases, but we need to educate people to use safe and future proof values.

[gotmax23]

+1 for option 1

[markuman]

2 > 4 > 1 > 3

it feels a bit like a similar discussion about linting,
shall we want to follow a strict yaml linting ruleset in the future?

extends_documentation_fragment:
    - amazon.aws.aws
    - amazon.aws.ec2

vs

extends_documentation_fragment:
- amazon.aws.aws
- amazon.aws.ec2

+1 for option 2

[russoz]

Option 1

[cidrblock]

Option 1, reasoning in #116

[KB-perByte]

+1 for option 1 true and false

[sivel]

I vote for new options called yes_true and no_false, or maybe yes_false and no_true.

[acozine]

how about working 1/0 into there somehow? I mean no_0_false would be stunningly confusing

[jamescassell]

2 > 4 > 1 > 3

[alinabuzachis]

+1 for option 1. BTW, my order of preference is 1>3>2>4.

[sean-m-sullivan]

+1 for option 1. BTW, my order of preference is 1>3>2>4.

module options are lowercase, so are module names, uniformity is best.

[qaxi]

1 > 2 > 4 > 3

[amott-rh]

For me it's 1 then 2. Unnecessary capitalisation is horrible.
While most programmers will understand true/false, the point of ansible is it's easy to read for non-coders and I'd suggest where English is not a first language most people will understand yes or no more readily than true/false. Plus its less typing ;)

[bcoca]

Note that by default ansible-doc output is 'YAML' (1.1 version as we use pyyaml) but it also outputs JSON (using a switch) and probably other formats in the future, each one has/can have a different standard for 'boolean'. This is irrespective on what values you set on the module documentation as it all gets auto translated by the YAML parser, so if you have mybool: on it still appears as True or true when displayed, so changing the source documentation is mostly futile and irrelevant to the display.

You also have to consider ansible-config as it displays the 'configuration definitions' which can also be considered 'documentation'.

The html pages are controlled by a Jinj2 template which currently displays:

{#   Turn boolean values in 'yes' and 'no' values #}
{%   if value['default'] is sameas true %}
{%     set _x = value.update({'default': 'yes'}) %}
{%   elif value['default'] is not none and value['default'] is sameas false %}
{%     set _x = value.update({'default': 'no'}) %}
{%   endif %}

This one is in the end the only one we can consistently set to a 'standard' .. but it won't be true for other outputs as that depends on the 'format' being used.

[mariolenz]

+1 for option 1

[branic]

1 > 3 > 2 > 4

[NilashishC]

+1 for option 1, preference: 1>3>2>4.

[ivarmu]

+1 for option 1, preference: 1>3>2>4

[watsonb]

+1 for option 1, preference: 1>3>2>4

[Andersson007]

+1 for option 2
preference: 2>1>3>4

[apple4ever]

1 > 3 > 2

(edited because I realized I had it backwards)

[acozine]

My order would be 2>1>4>3.

That said, option 2 (normalize to yes/no) is how we have been doing it, and folks have complained about the linting errors - that's why we started this discussion. So I am definitely open to 1 (normalize to true/false) or 4 (don't normalize at all. Capitalizing just seems silly and distracting, so 3 (normalize to True/False) would be my least favorite.

[pyrodie18]

Option 1

[evanstoner]

2 > 1, definitely not 3 or 4.

[ganeshrn]

+1 for option 1

[priyamsahoo]

+1 for Option 1!