15:31:01 #startmeeting Docs Working Group 15:31:01 Meeting started Tue Jan 8 15:31:01 2019 UTC. 15:31:01 This meeting is logged and archived in a public location. 15:31:01 The chair is samccann. Information about MeetBot at http://wiki.debian.org/MeetBot. 15:31:01 Useful Commands: #action #agreed #halp #info #idea #link #topic. 15:31:01 The meeting name has been set to 'docs_working_group' 15:31:18 Hello! Who's around for today's Doc fun? 15:31:33 o/ 15:32:22 Welcome dag! 15:32:27 o/ 15:32:52 #chair dag sdoran 15:32:52 Current chairs: dag samccann sdoran 15:33:05 oo that worked :-) (hashtag meeting newbie) 15:33:53 Anyone else around here? 15:35:26 ok could be a bit sparse, but let's discuss the first #topic Boolean values in Docs 15:35:35 hmm 15:35:43 #topic Boolean values in documentation 15:35:47 that's better 15:36:03 dag: do you want to start this one? 15:36:47 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 but the main question is, what would be preferred here (I have conflicting ideas around this) and what is the impact 15:37:33 sdoran had some interesting insights 15:37:41 #link https://github.com/ansible/community/issues/389 15:38:14 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 and greybeards want 0/1 15:38:35 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 true/false just bugs me, but JSON ¯\_(ツ)_/¯ 15:39:05 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 and yaml2 will parse yaml files as 1.1 by default (need pragma above present to do otherwise) 15:39:52 @bcoca Do we/can we support the 1.1 pragma in Ansible for the long term? 15:40:02 syntax highlighters follow YAML1.2 standard, and also linters do 15:40:08 yes, even if we move to yaml2, it will be the default 15:40:27 dag: except pyyaml, which is the yaml parser we use .. only does 1.1 for now 15:40:43 So if Ansible can support it, then it's just linters that will complain by default. 15:40:53 but personally, non-native speaker, yes/no is easier to read/understand than true/false (especially with negative-warded parameters) 15:40:59 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 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 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 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 bcoca: but obviously the longterm vision influences this 15:42:13 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 what about ansible-lint? does that complain with yes/no? 15:42:18 im not against standarizing 15:42:19 bcoca: agreed 15:42:41 i really dont have a strong pref, but i do want to make clear we do it for 'valid' reasons 15:42:47 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 both yes/no and true/false work for me, the question is what would most users react better to 15:43:16 BTW true/false (lowercase), not True/False, right ? 15:43:20 sdoran: yeah, it's those failed tests/warnings that bother me. 15:43:45 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 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 actually I think jinja allows lowercase too 15:44:02 samccann: Which I think we can solve by documenting why that is the case and how to change your linter settings. 15:44:33 good point sdoran 15:44:43 bcoca: yes/no is linguistically better IMO (human friendly) versus true/false is the path of least reisstance 15:45:03 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 dag: agreed, why i think this is a 'toss up' 15:45:44 #info yes/no for boolean may cause linter warnings/errors, but docs could recommend how to change linter settings 15:45:45 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 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 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 +1 for true / false over yes / no, and recommending it for docs 15:46:56 @bcoca Molecule uses `yamllint` 15:47:28 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 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 it won't fail unles you have yamllint -s 15:47:55 i expect a lot of division on yes/no vs true/false 15:47:59 is that the default for molecule now? 15:48:01 So it's indirectly Molecule. 15:48:14 That's how it worked when I started using it. 15:48:16 So maybe? 15:49:15 There is an issue about yamllint being strict and not matching docs or expectations: https://github.com/ansible/molecule/issues/1308 15:49:15 does anyone know why yaml decided to get stricter? 15:49:33 Ideally we could settle on `yes/no`, or `true/false`, and configure Molecule to honor that by default as well. 15:49:44 samccann: yaml itself or the linter? 15:49:46 But I don't know the Molecule codebase 15:50:01 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 yaml spec 1.2 was done with user feedback, many programmers annoyed at yes/no and other variants 15:50:02 I mainly just want our docs and tools to be in agreement. 15:50:11 sdoran: https://github.com/ansible/molecule/blob/e464e0c8d2266c27e718bc692e893be1fd7d40f6/molecule/lint/yamllint.py#L81-L85 15:50:13 linter .. well programmers are very opinionated 15:50:21 #link related issue -https://github.com/ansible/molecule/issues/1308 15:51:20 bcoca: are programmers our primary user base? (or at least having a programmer mindset?) 15:51:27 @sivel You are a wizard. 15:51:35 no, but they are a big part of it 15:51:35 also fwiw, we use yamllint in CI, but don't use -s 15:52:04 #chairs sivel bcoca 15:52:13 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 sivel: but we don't yamllint examples, do we ? 15:52:48 another option is just leave strict mode enable, and have users override settings via .yamllint file 15:52:49 sivel: sorry, I meant ansible-lint 15:53:04 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 dag: I know that validate-modules verifies that examples is YAML, unsure about our use of yamllint in ansible-test 15:53:17 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 samccann: how do we do rst snippet includes? 15:54:15 samccann: we can lint exampes too, I think it's already done for Python example blocks 15:54:21 dag: I *think* we do yamllint examles 15:54:23 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 based on https://github.com/ansible/ansible/blob/a8d4bf86421d151d8df7132e8e87d04b6662f45a/test/sanity/yamllint/yamllinter.py#L112 15:54:44 sival: yes for yaml-lint, my thoughts were with ansible-lint (which I think we should validate as well) 15:55:17 maybe, but that might be very contentious 15:56:35 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 can we vote on this, should we vote in a core meeting instead ? 15:57:09 my 2 cents, is that is just doesn't matter 15:57:29 sivel: i kind of agree, im willing to allow 'both ways' in docs 15:57:31 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 sivel: I would simply like to see consistency in the documentation though 15:58:10 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 I vote for only `yes/no` and `true/false` in docs with a blurb explaining bools and how it's flexible. 15:58:29 it can lead to confusion, but i think it is a minor point of it 15:58:39 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 And I'll work on a PR for molecule to make it work with those by default. 15:58:49 Though I have no idea if it'll get merged. 15:58:56 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 samccann: we create PRs for those projects 15:59:35 and ensure that they are only strict true/false if there is a %YAML1.2 pragma in the file 15:59:43 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 `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 I'll see if I can find the rule to make it accept more flexible booleans. 16:00:28 I don't think `anisble-lint` cares about boolean values. It's looking at other things. 16:00:35 @sdoran: why not expose a new setting in molecule config to allow user to toggle strict mode then 16:00:41 pabelanger: the point is moslty 'programmers' will be suprised, many other users are not 16:00:57 mostly cause of lack of programing norm knowledge ... 16:01:20 pabelanger: agreed, it should be toggle, but i think we agree it shoudl be 'off by default' 16:01:32 or at least the 'truthy' flag 16:01:35 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 maybe not the whole 'strict' one 16:02:10 @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 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 +1 16:02:47 And really just trying to unify these things, docs to program to linters. 16:03:06 like enforcing to use `when: foo` instead of `when: foo is True` or `when: 'foo != ""'` 16:04:12 anyway, we're probably veering off topic 16:04:18 :-) 16:04:52 Let's vote one A. yes/no, B. true/false, C. yes/no/true/false D. something else 16:05:10 I think C had the most votes, but I am not sure 16:05:21 @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 but just my opionin 16:05:35 opinion* 16:06:04 c++ 16:06:19 ^ non intentioal pun .. but im rolling with it 16:06:20 in order to have a consistent documentation, I would go for A (but wouldn't mind C as a general rule) 16:06:49 I vote C 16:06:51 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 C 16:07:09 +1 for sdoran's recommendation 16:07:14 an C for the vote 16:07:45 also +1 for docs update 16:07:51 If you go A, won't this break everybody who is already doing B? 16:08:07 pabelanger: wont break, since its docs update, not asnible parser update 16:08:09 in general, looks like we are agreed on C 16:08:24 Currently the parameter list in the module docs will do yes/no for booleans 16:08:40 even if you stated true/false, on/off, ... 16:08:42 @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 Because currently we have a disagreement between what Ansible views as valid and what Molecule considers valid. 16:09:23 dag: probably change that to 'boolean values' link/hover that explains true/false or yes/no are all valid 16:09:44 bcoca: Good idea, but it will conflict with possible descriptions 16:10:02 and 'default' 16:10:19 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 i think im ok with that, unless you want to parse description + default to try to figure out which is used? 16:10:27 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 (in documentation) 16:10:39 dag: that also works 16:11:10 sdoran: yeah, on/off and 0/1 are the only thing i think we all agree to ignore 16:11:35 they exist, but we dont awknoledge them .. kind of like step kids 16:11:37 @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 wouldn't 0 and 1 become integer values instead of booleans? 16:12:02 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 dag: they can, depends 16:12:22 @sdoran: fwiw, others have the same idea too: https://github.com/adrienverge/yamllint/issues/150 16:12:32 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 ^ that is after 'lower()' on source for comparisson 16:12:52 @sdoran: if we land it upstream, then molecule doesn't need to carry anything 16:13:44 sivel: I was only talking about YAML, 0 and 1 are not valied YAML booleans AFAIK 16:14:17 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 YAML booleans: https://yaml.org/type/bool.html 16:15:19 @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 @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 sdoran: does the strict option only apply to boolean or are we turning off more when we do that? 16:16:40 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 Nothing like trying to coordinate changes across three projects. :) 16:17:21 sdoran: :-) 16:17:36 sdoran: yah, that wfm 16:17:42 I updated the entry in the agenda: https://github.com/ansible/community/issues/389#issuecomment-452327393 16:17:58 I can look into yamllint today and see if I can write a patch 16:18:06 @samccann The strict option causes a failure on warnings. Without strict, only errors result in a failure. 16:18:26 I'll work on the Molecule patch to disable the truthy rule by default. 16:18:58 #agreed allow yes/no or true/false in docs 16:19:22 #agreed open a PR on molecule to disable truthy rule by default 16:19:48 #agreed open a PR in docs to explain boolean values in Yaml 16:19:55 So all our docs should have `yes/no/true/false` for YAML booleans 16:20:02 yep 16:20:14 And a blurb about other options work too, but this is what we use. 16:20:28 And the more advanced folks can figure out what those are. 16:20:36 #action verify that docs only contain yes/no/true/false for yaml booleans 16:21:24 Thank you everyone for your input or this seemingly mundane topic. 16:21:31 okay we have about 10 minutes left so I'm going to open it up to other issues 16:21:35 This has bugged me a lot. :) 16:21:36 #topic Open Floor 16:21:55 anyone have anything else doc-related they wanted to bring up? or a fav. PR to discuss? 16:22:51 i've got one PR I'd like some thoughts on - https://github.com/ansible/ansible/pull/50548/files 16:23:30 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 I would not clutter the choices with inline comments 16:28:27 That will causes that column to be much too wide. 16:28:41 great thanks 16:29:14 Just have them put those comments in the `description`. 16:30:30 ok that's about it. thanks everyone! 16:30:34 #endmeeting