15:34:52 #startmeeting Ansible Docs Working Group 15:34:52 Meeting started Tue Feb 5 15:34:52 2019 UTC. 15:34:52 This meeting is logged and archived in a public location. 15:34:52 The chair is gundalow. Information about MeetBot at http://wiki.debian.org/MeetBot. 15:34:52 Useful Commands: #action #agreed #halp #info #idea #link #topic. 15:34:52 The meeting name has been set to 'ansible_docs_working_group' 15:34:52 samccann: Error: Can't start another meeting, one is in progress. 15:35:04 #chair samccann 15:35:04 Current chairs: gundalow samccann 15:35:07 lol, woops 15:35:14 heh jinx! 15:35:36 anyone else around for some docs fun? 15:35:42 hi 15:35:50 I'm here; mostly watching along and getting a feel for things 15:35:53 #info Agenda https://github.com/ansible/community/issues/389 15:35:54 i am new to the work group 15:35:58 #chair imack alongchamps 15:35:58 Current chairs: alongchamps gundalow imack samccann 15:36:20 imack: Welcome :) How did you hear about the working group, what you like to get out of it? 15:36:38 (this is all very informal, so feel free to jump in at any point during the discussions) 15:37:07 i have attended one webinar on how to get into contributing for ansible, and here i am :) 15:37:26 imack: ah, excellent 15:37:27 well welcome imack ! 15:37:43 thanks :) 15:38:52 https://github.com/ansible/community/issues/389#issuecomment-458179675 last time we get to `* Integrating & cross linking parts of the User Guide` 15:39:13 imack: alongchamps anyting you'd like to add to the agenda, or ask before we begin? 15:39:48 I was looking last week at some of the contributions material since I'm working on a module and had a particular behavior I wanted to check was OK 15:40:05 alongchamps: sure 15:40:15 in this case, it would be when a module is going to configure something (this is for VMware ESXi in particular) should it replace what is there or append to it, or both? 15:40:49 o/ 15:40:54 the module I'm workin on in particular is for VMware host kernel modules, which take text options (e.g. ipv6=0) and I'm wondering if there's a best practice on if it should replace what's present or append 15:41:14 #chair dag 15:41:14 Current chairs: alongchamps dag gundalow imack samccann 15:42:39 alongchamps: do you have a PR ready ? 15:43:15 I don't have one yet; I'm testing it on my side for functionality and then I came up with this question 15:44:13 alongchamps: this question is not really related to documentation though 15:44:38 ah, ok! 15:44:45 dag: not directly, but alongchamps looked in our guide and couldn't find the answer 15:44:46 but let's discuss in private 15:45:08 so seems like whatever the end result is - there should be a docs PR to add that detail to the dev. guide? 15:45:42 samccann: I understand, however I don't think we ever can answer all questions people will ever have (if we would, people wouldn't likely find the necessary stuff ;-) 15:46:22 is this most likely going to be a per-module or per-working group thing for how they behave, and then it's up to the contributors to document it properly? 15:46:35 if so, that gives me some direction to go in 15:46:39 but isn't whether to replace or append functionality important necessary stuff? or am I misinterpreting the request? 15:46:58 samccann: I don't think we have a good answer (not one that is acceptable) 15:47:08 do you want to discuss this here ? 15:47:37 dag: not looking to make a decision here, but I think IF you come up with some general guidance, it seems something worth having in the dev guide 15:47:50 but not if it's a case by case thing 15:47:58 it might 15:48:39 samccann: +1 15:48:42 "it depends" 15:48:57 that's my favorite answer :) 15:49:12 * gundalow feels bad for using it though L( 15:49:35 with the modules already in place though for lots of different things, I can see why it would be on a case-by-case basis 15:49:42 so the problem is that users may want to add, remove or replace items in a list to an object 15:50:02 roughly, yes 15:50:18 and lots of infrastructure modules have separate modules for managing items in lists 15:50:56 generally if you manage the parent, it replaces the list, if you manage the list itself, you can add, remove and replace (state=pure) 15:51:16 some modules have an option "purge", but I don't think that is a good convention 15:52:27 I think I will go with having it replace what's there on state: present and remove options when state: absent 15:52:38 ty all for the discussion, this helps me 15:52:57 (we have modules that allow operations on child-objects etc, but those become very complex very quickly and doesn't give you proper feedback as to what has changed.happened) 15:53:22 alongchamps: it helps if we know what the module does, and what the user interface (arg_spec) is 15:53:53 but state=pure is what would replace what exists, and removes what is not provided 15:54:19 this one configures vmware host kernel modules which have a module name then a space separated list of options. e.g. module: "tpcip4" and options: "ipv6=0" 15:54:20 (which is not exactly the same as remove everything, and then add) 15:54:27 s/tpcip4/tcpip4 15:54:48 alongchamps: I think it makes more sense to manage the complete command line as a single object (i.e. not consider it a list) 15:54:48 someone could run another module call that says module: "tcpip4" and options: "ipportScsiReserved=20" 15:55:04 right 15:55:12 ESXi stores it internally that way, "kvpair1=option1 kvpair2=option2" 15:55:17 just space separated 15:55:25 if that's the only thing the module does, yes, present/absent/pure would be best 15:55:34 sounds good to me 15:55:52 and I would make it a dictionary (unless keys can be repeated, in that case it should be a list) 15:56:41 alongchamps: put me in (cc @dagwieers) in the PR and I will review and give feedback 15:56:53 alongchamps: hope that's helped :) 15:56:57 dag: Thanks :) 15:57:09 it did, thanks dag and gundalow 15:57:35 ace 15:57:37 NEXT 15:57:49 #topic Integrating & cross linking parts of the User Guide 15:58:57 alongchamps: BTW don't we have a module doing this for Linux kernel modules ? (If we do, don't expect that module to have a good interface, it might be old ;-)) 15:59:16 So this is partly discoverability & promotion 15:59:19 this one is for VMware ESXi hosts - their hypervisor 15:59:27 https://docs.ansible.com/ansible/latest/modules/modprobe_module.html 15:59:27 s/their/the 15:59:56 it's managing the module mostly (and optionally replaces any module options) 16:00:00 so this would go into the VMware working group and based on my prior searches of the codebase/issues, there isn't one - I decided to use it to get my feet wet in writing modules 16:00:01 We have https://docs.ansible.com/ansible/latest/community/other_tools_and_programs.html though I'm wondering if we should mention some of those items in the Getting Started guides 16:00:04 so not the best example 16:00:29 Some people didn't know that `ansible-lint` was a thing 16:00:37 i'll give both of those a look, thanks 16:00:54 likewise people didn't know you can make it easier to write Playbooks in your $EDITOR 16:00:59 What do people thing? 16:01:08 gundalow: I'd like us to give a boost to ansible-lint for sure 16:01:40 * dag has some doubts on ansible-lint related to personal preferences and existing defaults 16:02:05 for $EDITOR - maybe just a note to point over to that other tools etc section? editor choice is ..ahem...a very opinionated selection for some folks 16:02:09 I am not certain we have shipped it in the past with the best defaults (and changing defaults is hard to impossible) 16:02:55 samccann: oh, sure, defo want to avoid editor wars. https://docs.ansible.com/ansible/latest/community/other_tools_and_programs.html covers a lot of editors 16:05:12 gundalow: yeah that's why I'm thinking a strategically placed note 'somewhere' that says some editors have build in 'whatever' to help you write playbooks... and then a link to that existing section might be enough 16:05:36 Yup, that sounds good 16:10:26 #agreed - add a note about editors making playbooks easier to write, with a link to https://docs.ansible.com/ansible/latest/community/other_tools_and_programs.html 16:10:53 were we also agreed about `ansible-lint` ? sounds like dag had some thoughts? 16:14:57 hmm... things got quiet round here... anyone left here w/ an opinion on pointing users to `ansible-lint` to test playbooks etc? 16:16:34 samccann: yup, lets mention it 16:17:35 #action samccann - add notes about editors and playbooks and ansible-lint 16:18:36 #topic Open Floor 16:18:49 Anyone have another docs topic they want to bring up? 16:19:57 Friendly reminder we have 95 open docs PRs - so if you have some spare time, consider reviewing/commenting (and merging if you have those rights) - https://github.com/ansible/ansible/pulls?q=is%3Aopen+is%3Apr+label%3Adocs 16:20:35 or even going to the oldest in that list and adding a comment to ask the owner if they are making progress/still interested in the fix etc 16:23:09 And for those new or looking for a place to jump in - this has some suggestions for docs (and other areas to contribute) - https://docs.ansible.com/ansible/latest/community/how_can_I_help.html#review-fix-and-maintain-the-documentation 16:24:46 okay looks like we're winding down here. 16:24:59 Thanks everyone for today's meeting! 16:25:07 #endmeeting