15:31:01 <samccann> #startmeeting Docs Working Group
15:31:01 <zodbot> Meeting started Tue Jan  8 15:31:01 2019 UTC.
15:31:01 <zodbot> This meeting is logged and archived in a public location.
15:31:01 <zodbot> The chair is samccann. Information about MeetBot at http://wiki.debian.org/MeetBot.
15:31:01 <zodbot> Useful Commands: #action #agreed #halp #info #idea #link #topic.
15:31:01 <zodbot> The meeting name has been set to 'docs_working_group'
15:31:18 <samccann> Hello!  Who's around for today's Doc fun?
15:31:33 <dag> o/
15:32:22 <samccann> Welcome dag!
15:32:27 <sdoran> o/
15:32:52 <samccann> #chair dag sdoran
15:32:52 <zodbot> Current chairs: dag samccann sdoran
15:33:05 <samccann> oo that worked :-)  (hashtag meeting newbie)
15:33:53 <samccann> Anyone else around here?
15:35:26 <samccann> ok could be a bit sparse, but let's discuss the first #topic Boolean values in Docs
15:35:35 <samccann> hmm
15:35:43 <samccann> #topic Boolean values in documentation
15:35:47 <samccann> that's better
15:36:03 <samccann> dag: do you want to start this one?
15:36:47 <dag> samccann: Sure, I think the entry in the agenda is clear, we want to standardize the boolean values in documentation and examples
15:37:22 <dag> but the main question is, what would be preferred here (I have conflicting ideas around this) and what is the impact
15:37:33 <dag> sdoran had some interesting insights
15:37:41 <samccann> #link https://github.com/ansible/community/issues/389
15:38:14 <bcoca> i can see it both ways, programmers will lean to True/False, other users will prefer Yes/No and some weirdo wants 'on/off'
15:38:30 <bcoca> and greybeards want 0/1
15:38:35 <samccann> so to be sure I understand the issue -  the current doc standard is yes/no, but YAML2 is standardizing on true/false..correct?
15:38:49 <sdoran> true/false just bugs me, but JSON ¯\_(ツ)_/¯
15:39:05 <bcoca> samccann: yes and no, yaml1.2 with a %YAML1.2 pragma in the doc will default to true/false being only boolean, but there are toggles for it
15:39:23 <bcoca> and yaml2 will parse yaml files as 1.1 by default (need pragma above present to do otherwise)
15:39:52 <sdoran> @bcoca Do we/can we support the 1.1 pragma in Ansible for the long term?
15:40:02 <dag> syntax highlighters follow YAML1.2 standard, and also linters do
15:40:08 <bcoca> yes, even if we move to yaml2, it will be the default
15:40:27 <bcoca> dag: except pyyaml, which is the yaml parser we use .. only does 1.1 for now
15:40:43 <sdoran> So if Ansible can support it, then it's just linters that will complain by default.
15:40:53 <dag> but personally, non-native speaker, yes/no is easier to read/understand than true/false (especially with negative-warded parameters)
15:40:59 <bcoca> they ARE working on 1.2 support, but no release yet .. and then adoption, so it is something to consider for the future, but i think its premature at this point to restrict to yaml1.2
15:41:29 <bcoca> also, yaml is not only consideration, ansible internally overrides 'jinja2 booleans' and in other spots to ensure yes/no are also 'boolean values'
15:41:41 <sdoran> We're mainly just trying to nail down how to document booleans across docs. Because right now it's inconsistent, and YAML linters are yelling at everyone to move to true/false.
15:41:43 <dag> bcoca: I don't want to change what we accept in Ansible, I am only looking on what we recommend/promote in the documentation
15:42:05 <dag> bcoca: but obviously the longterm vision influences this
15:42:13 <bcoca> dag: understood, im just pointing out that the 'what yaml accepts' reason is not really a good one to go one way or the other
15:42:17 <samccann> what about ansible-lint? does that complain with yes/no?
15:42:18 <bcoca> im not against standarizing
15:42:19 <dag> bcoca: agreed
15:42:41 <bcoca> i really dont have a strong pref, but i do want to make clear we do it for 'valid' reasons
15:42:47 <sdoran> So everyone thinks they need to move to true/false or their playbooks will break. And Molecule (which uses YAML lint) will fail tests in the default configuration if you use booleans other than true/false.
15:43:04 <bcoca> both yes/no and true/false work for me, the question is what would most users react better to
15:43:16 <dag> BTW true/false (lowercase), not True/False, right ?
15:43:20 <samccann> sdoran: yeah, it's those failed tests/warnings that bother me.
15:43:45 <bcoca> actually, both work true/false and True/False (yaml and ansible are case insensitive here, but jinja2 is not, requires True/False)
15:44:00 <samccann> I agree yes/no is easier to understand for the general reader, but if our doc examples are used 'as is' and cough up failures or warnings, that's also bad
15:44:01 <sivel> actually I think jinja allows lowercase too
15:44:02 <sdoran> samccann: Which I think we can solve by documenting why that is the case and how to change your linter settings.
15:44:33 <samccann> good point sdoran
15:44:43 <dag> bcoca: yes/no is linguistically better IMO (human friendly) versus true/false is the path of least reisstance
15:45:03 <samccann> but still leaves us with - do we keep using yes/no and recommending linter settings, or do we move to true/false so the user doesn't have to change linter settings
15:45:05 <bcoca> dag: agreed, why i think this is a 'toss up'
15:45:44 <samccann> #info yes/no for boolean may cause linter warnings/errors, but docs could recommend how to change linter settings
15:45:45 <bcoca> which 'linters' are we talking about? if it is asnible-lint and molecule .. i think we should just change the linters to accept either pair
15:46:32 <samccann> bcoca - at the least, if we keep yes/no, then yeah, I agree our own tools have to accept it.  Question is - what do ansible users use? just those tools, or something more?
15:46:37 <sdoran> So it seems we are good on the technical side of supporting a flexible boolean syntax into the future, now we just need to decide on a recommendation and document how to make linters behave.
15:46:51 <pabelanger> +1 for true / false over yes / no, and recommending it for docs
15:46:56 <sdoran> @bcoca Molecule uses `yamllint`
15:47:28 <sdoran> So when you run `molecule test`, it will run `yamllint`, which will fail if you don't use `true/false` boolean values in its default state.
15:47:46 <bcoca> i really dont care either way, i think the only thing people will agree is to 'not use 0/1 and on/off variants'
15:47:49 <pabelanger> it won't fail unles you have yamllint -s
15:47:55 <bcoca> i expect a lot of division on yes/no vs true/false
15:47:59 <pabelanger> is that the default for molecule now?
15:48:01 <sdoran> So it's indirectly Molecule.
15:48:14 <sdoran> That's how it worked when I started using it.
15:48:16 <sdoran> So maybe?
15:49:15 <sivel> There is an issue about yamllint being strict and not matching docs or expectations: https://github.com/ansible/molecule/issues/1308
15:49:15 <samccann> does anyone know why yaml decided to get stricter?
15:49:33 <sdoran> Ideally we could settle on `yes/no`, or `true/false`, and configure Molecule to honor that by default as well.
15:49:44 <bcoca> samccann: yaml itself or the linter?
15:49:46 <sdoran> But I don't know the Molecule codebase
15:50:01 <dag> sivel: OT surprisingly Jinja2 defines true/false (lowercase) but supports True/False as well for python compatibility (http://jinja.pocoo.org/docs/2.10/templates/#literals)
15:50:01 <bcoca> yaml spec 1.2 was done with user feedback, many programmers annoyed at yes/no and other variants
15:50:02 <sdoran> I mainly just want our docs and tools to be in agreement.
15:50:11 <sivel> sdoran: https://github.com/ansible/molecule/blob/e464e0c8d2266c27e718bc692e893be1fd7d40f6/molecule/lint/yamllint.py#L81-L85
15:50:13 <bcoca> linter .. well programmers are very opinionated
15:50:21 <samccann> #link related issue -https://github.com/ansible/molecule/issues/1308
15:51:20 <samccann> bcoca: are programmers our primary user base? (or at least having a programmer mindset?)
15:51:27 <sdoran> @sivel You are a wizard.
15:51:35 <bcoca> no, but they are a big part of it
15:51:35 <sivel> also fwiw, we use yamllint in CI, but don't use -s
15:52:04 <samccann> #chairs sivel bcoca
15:52:13 <bcoca> samccann: the skew is that most of the users you'll find on irc are programmers, even more so those that engage in the community to contribute
15:52:34 <dag> sivel: but we don't yamllint examples, do we ?
15:52:48 <pabelanger> another option is just leave strict mode enable, and have users override settings via .yamllint file
15:52:49 <dag> sivel: sorry, I meant ansible-lint
15:53:04 <bcoca> but our user base does include a lot of non programmers, becasue ansible is easy to use outside of programmer mindset, which is one of it's big selling points
15:53:11 <sivel> dag: I know that validate-modules verifies that examples is YAML, unsure about our use of yamllint in ansible-test
15:53:17 <samccann> dag: at some point, I'd like to move examples out of docs (not the module examples, but those in rst) into files that we CAN ansible-lint.  but that's just a pipedream for me right now
15:53:45 <bcoca> samccann: how do we do rst snippet includes?
15:54:15 <dag> samccann: we can lint exampes too, I think it's already done for Python example blocks
15:54:21 <sivel> dag: I *think* we do yamllint examles
15:54:23 <samccann> bcoca - not sure but I thought I saw one example of it in the rst content. there's a directory 'somewheres' called snippets.  dunno if it would work, like  I said.. a pipedream for now
15:54:31 <sivel> based on https://github.com/ansible/ansible/blob/a8d4bf86421d151d8df7132e8e87d04b6662f45a/test/sanity/yamllint/yamllinter.py#L112
15:54:44 <dag> sival: yes for yaml-lint, my thoughts were with ansible-lint (which I think we should validate as well)
15:55:17 <sivel> maybe, but that might be very contentious
15:56:35 <dag> so, know that we have dug this hole, how do we get out of it ;-)
15:56:57 * bcoca hands out shovels and hopes there is something on 'the other side'
15:57:01 <dag> can we vote on this, should we vote in a core meeting instead ?
15:57:09 <sivel> my 2 cents, is that is just doesn't matter
15:57:29 <bcoca> sivel: i kind of agree, im willing to allow 'both ways' in docs
15:57:31 <samccann> so attempting to summarize again - we could do either way (yes/no or true/false).  yes/no is considered easier to understand for the nonprogrammer, but leaves is with always having to have a linter setting to avoid warnings/failures.  true/false should work by default for linters. but the docs are heavily skewed today to yes/now as it is our current guideline
15:57:37 <dag> sivel: I would simply like to see consistency in the documentation though
15:58:10 <bcoca> dag: sometimes the variability is a good way to show flexibility to the users, in this specific case, i dont mind it
15:58:28 <sdoran> I vote for only `yes/no` and `true/false` in docs with a blurb explaining bools and how it's flexible.
15:58:29 <bcoca> it can lead to confusion, but i think it is a minor point of it
15:58:39 <sivel> a lack of understanding of YAML will be the users downfall, and severely limiting the syntax in our examples will help lead to that
15:58:42 <sdoran> And I'll work on a PR for molecule to make it work with those by default.
15:58:49 <sdoran> Though I have no idea if it'll get merged.
15:58:56 <samccann> if we leave it yes/no, how do we get molecule, yamlint, ansible-lint to not flag it as a warning/failure?
15:59:10 <bcoca> samccann: we create PRs for those projects
15:59:35 <bcoca> and ensure that they are only strict true/false if there is a %YAML1.2 pragma in the file
15:59:43 <pabelanger> https://yamllint.readthedocs.io/en/stable/rules.html#module-yamllint.rules.truthy are the docs on why true / false is prefered to yes / no
15:59:44 <sdoran> `yamllint` isn't really the issue as @sivel pointed out. It's that Molecule passes the `-s` flag to `yamllint` by default.
16:00:09 <sdoran> I'll see if I can find the rule to make it accept more flexible booleans.
16:00:28 <sdoran> I don't think `anisble-lint` cares about boolean values. It's looking at other things.
16:00:35 <pabelanger> @sdoran: why not expose a new setting in molecule config to allow user to toggle strict mode then
16:00:41 <bcoca> pabelanger: the point is moslty 'programmers' will be suprised, many other users are not
16:00:57 <bcoca> mostly cause of lack of programing norm knowledge ...
16:01:20 <bcoca> pabelanger: agreed, it should be toggle, but i think we agree it shoudl be 'off by default'
16:01:32 <bcoca> or at least the 'truthy' flag
16:01:35 <dag> pabelanger: That is even not a point of discussion here, as Ansible will not be affected, only examples/documentation, we cannot make this more strict at this point
16:01:40 <bcoca> maybe not the whole 'strict' one
16:02:10 <sdoran> @pabelanger The default experience is bad if you have to change defaults. I think the `truthy` flag should be enabled by default in Molecule to be inline with how Ansible processes YAML>
16:02:14 <sivel> I think we have discussed a few things that molecule and ansible-lint are enforcing that are, maybe not what we would consider valid recommendations
16:02:22 <sdoran> +1
16:02:47 <sdoran> And really just trying to unify these things, docs to program to linters.
16:03:06 <sivel> like enforcing to use `when: foo` instead of `when: foo is True` or `when: 'foo != ""'`
16:04:12 <sivel> anyway, we're probably veering off topic
16:04:18 <samccann> :-)
16:04:52 <dag> Let's vote one A. yes/no, B. true/false, C. yes/no/true/false D. something else
16:05:10 <dag> I think C had the most votes, but I am not sure
16:05:21 <pabelanger> @sdoran: as is the user experience if linters are changing default / rules each point release.  I do agree, maybe just default strict to false, with ML post. I also think it is a little confusing if a linter defines 2 ways to do something as value, true / false vs yes / no. would much rather see 1 valid for strict mode
16:05:28 <pabelanger> but just my opionin
16:05:35 <pabelanger> opinion*
16:06:04 <bcoca> c++
16:06:19 <bcoca> ^ non intentioal pun .. but im rolling with it
16:06:20 <dag> in order to have a consistent documentation, I would go for A (but wouldn't mind C as a general rule)
16:06:49 <sivel> I vote C
16:06:51 <sdoran> I would say the main things we should do are use `yes/no` and `true/false` in the docs, add a brief explanation of bools in YAML and how they are used in our docs, and submit a PR to molecule so it does not fail when people have `yes/no/true/false` in their playbooks.
16:06:54 <sdoran> C
16:07:09 <samccann> +1 for sdoran's recommendation
16:07:14 <samccann> an C for the vote
16:07:45 <bcoca> also +1 for docs update
16:07:51 <pabelanger> If you go A, won't this break everybody who is already doing B?
16:08:07 <bcoca> pabelanger: wont break, since its docs update, not asnible parser update
16:08:09 <samccann> in general, looks like we are agreed on C
16:08:24 <dag> Currently the parameter list in the module docs will do yes/no for booleans
16:08:40 <dag> even if you stated true/false, on/off, ...
16:08:42 <sdoran> @pabelanger I agree that a linter should enforce unambiguous syntax in general. But in this specific case of Molecule using `yamllint` for checking YAML used by Ansible, since Ansible is ok with a more flexible boolean syntax, Molecule should be as well.
16:09:10 <sdoran> Because currently we have a disagreement between what Ansible views as valid and what Molecule considers valid.
16:09:23 <bcoca> dag: probably change that to 'boolean values' link/hover that explains true/false or yes/no are all valid
16:09:44 <dag> bcoca: Good idea, but it will conflict with possible descriptions
16:10:02 <bcoca> and 'default'
16:10:19 <sdoran> I think C is the most accurate since it's how Ansible actually works. Yes there are other acceptable values, but we can avoid them to reduce confusion.
16:10:26 <bcoca> i think im ok with that, unless you want to parse description + default to try to figure out which is used?
16:10:27 <dag> bcoca: I wanted to make the parameter types clickable to give some more information related to types (especially things like path, raw ...)
16:10:30 <sdoran> (in documentation)
16:10:39 <bcoca> dag: that also works
16:11:10 <bcoca> sdoran:  yeah, on/off and 0/1 are the only thing i think we all agree to ignore
16:11:35 <bcoca> they exist, but we dont awknoledge them .. kind of like step kids
16:11:37 <pabelanger> @sdoran: as long as we keep it a setting a user could disable via https://molecule.readthedocs.io/en/latest/configuration.html#lint I don't have much objection.  I could see a reason why people just want to run vanilla yamllint rules
16:11:37 <dag> wouldn't 0 and 1 become integer values instead of booleans?
16:12:02 <samccann> so we're agreed on yes/no or true/false , add a note to the docs to explain boolean values in YAML, and open a PR to make molecule ci accept this?
16:12:06 <bcoca> dag: they can, depends
16:12:22 <pabelanger> @sdoran: fwiw, others have the same idea too: https://github.com/adrienverge/yamllint/issues/150
16:12:32 <sivel> We define 0 and 1 as booleans in convert_bool: BOOLEANS_TRUE = frozenset(('y', 'yes', 'on', '1', 'true', 't', 1, 1.0, True))
16:12:52 <bcoca> ^ that is after 'lower()' on source for comparisson
16:12:52 <pabelanger> @sdoran: if we land it upstream, then molecule doesn't need to carry anything
16:13:44 <dag> sivel: I was only talking about YAML, 0 and 1 are not valied YAML booleans AFAIK
16:14:17 <sivel> dag: no, but if you pass 1 or 0 to a bool param, we will make it False or True when parsing module options
16:14:34 <sivel> YAML booleans: https://yaml.org/type/bool.html
16:15:19 <sdoran> @pabelanger That would be the best solution, to may `yamllint` accept a list of valid values. I still think this needs to be configured in Molecule by default, though.
16:16:05 <sdoran> @pabelanger I just tested and you can override the strict option in Molecule, which is what I figured would be the case.
16:16:38 <samccann> sdoran: does the strict option only apply to boolean or are we turning off more when we do that?
16:16:40 <sdoran> So we could add a default to disable the `truthy` rule in Molecule, then later update it to a valid list once `yamllint` adds that feature.
16:16:55 <sdoran> Nothing like trying to coordinate changes across three projects. :)
16:17:21 <dag> sdoran: :-)
16:17:36 <pabelanger> sdoran: yah, that wfm
16:17:42 <dag> I updated the entry in the agenda: https://github.com/ansible/community/issues/389#issuecomment-452327393
16:17:58 <pabelanger> I can look into yamllint today and see if I can write a patch
16:18:06 <sdoran> @samccann The strict option causes a failure on warnings. Without strict, only errors result in a failure.
16:18:26 <sdoran> I'll work on the Molecule patch to disable the truthy rule by default.
16:18:58 <samccann> #agreed allow yes/no or true/false in docs
16:19:22 <samccann> #agreed open a PR on molecule to disable truthy rule by default
16:19:48 <samccann> #agreed open a PR in docs to explain boolean values in Yaml
16:19:55 <sdoran> So all our docs should have `yes/no/true/false` for YAML booleans
16:20:02 <samccann> yep
16:20:14 <sdoran> And a blurb about other options work too, but this is what we use.
16:20:28 <sdoran> And the more advanced folks can figure out what those are.
16:20:36 <samccann> #action verify that docs only contain yes/no/true/false for yaml booleans
16:21:24 <sdoran> Thank you everyone for your input or this seemingly mundane topic.
16:21:31 <samccann> okay we have about 10 minutes left so I'm going to open it up to other issues
16:21:35 <sdoran> This has bugged me a lot. :)
16:21:36 <samccann> #topic Open Floor
16:21:55 <samccann> anyone have anything else doc-related they wanted to bring up? or a fav. PR to discuss?
16:22:51 <samccann> i've got one PR I'd like some thoughts on - https://github.com/ansible/ansible/pull/50548/files
16:23:30 <samccann> very simple, but the owner is adding comments within the 'choices' in a module parameter. I'm incline to reject that and recommend they add the caveats up in the parameter description.
16:27:50 <sdoran> I would not clutter the choices with inline comments
16:28:27 <sdoran> That will causes that column to be  much too wide.
16:28:41 <samccann> great thanks
16:29:14 <sdoran> Just have them put those comments in the `description`.
16:30:30 <samccann> ok that's about it. thanks everyone!
16:30:34 <samccann> #endmeeting