14:31:49 <samccann> #startmeeting DaWGs aka Docs Working Group
14:31:49 <zodbot> Meeting started Tue Oct  8 14:31:49 2019 UTC.
14:31:49 <zodbot> This meeting is logged and archived in a public location.
14:31:49 <zodbot> The chair is samccann. Information about MeetBot at http://wiki.debian.org/MeetBot.
14:31:49 <zodbot> Useful Commands: #action #agreed #halp #info #idea #link #topic.
14:31:49 <zodbot> The meeting name has been set to 'dawgs_aka_docs_working_group'
14:31:59 <samccann> #chair felixfontein
14:31:59 <zodbot> Current chairs: felixfontein samccann
14:32:15 <samccann> who else is around and dyin' to be turned into furniture???
14:32:40 <samccann> gundalow bcoca alongchamps cyperpear ??
14:32:49 * gundalow waves
14:32:58 <alongchamps> I can't be a chair today, I'm on a meeting with VMware
14:33:09 <samccann> ok thanks alongchamps !
14:33:14 <samccann> #chair gundalow
14:33:14 <zodbot> Current chairs: felixfontein gundalow samccann
14:33:16 <felixfontein> no furniture for you then ;)
14:33:23 <gundalow> :)
14:33:47 <samccann> well, there's always the option for a comfy pillow  - all the joy of furniture w/o the need to reply to every comment :-)
14:34:18 <samccann> okay let's get started with some easy stuff
14:34:27 <samccann> #topic - linking PRs in changlog fragments
14:34:40 <acozine> you can turn me into furniture
14:34:52 <acozine> though I am double-booked for the next 20 minutes or so
14:34:54 <samccann> This one is based on a user reading the changelog and finding something interesting, but not enough detail
14:34:59 <samccann> #chair acozine
14:34:59 <zodbot> Current chairs: acozine felixfontein gundalow samccann
14:35:10 <felixfontein> sounds like a good idea to me
14:35:23 <samccann> So I thought, since our guidelines are to name the changelog fragment file with the PR, we could also ask folks to include a link to the PR in the changelong
14:35:30 <felixfontein> should this be formalized, or be a "guideline"?
14:35:32 <samccann> changelog
14:36:03 <felixfontein> for formalizing, it would be nice to have a `PRs:` list in the changelog fragment which links to all PRs involved in this changelog fragment
14:36:05 <samccann> well, I did a quick check the other day, and only about 1/2 of the changelog filenames included the PR number.  So I'm thinking strongly worded guidelines are about all we can hope for
14:36:13 <felixfontein> (there can be multiple since stuff can be changed before it appears in a release)
14:36:44 <samccann> ah hadn't thought about that.  Do they usually have an issue they each group up to? We could ask for the issue number instead?
14:36:55 <gundalow> just looked in `changelog/fragments`, not seeing as many PR links as I would have expected
14:37:07 <felixfontein> there's not necessarily an issue (and if there is, there could be multiple as well)
14:37:11 <samccann> yeah that's where I looked - just the filenames
14:37:51 <samccann> hmm... perhaps we could word it as 'please add a link to the most significant PR or issue related to this changelog fragment' or something vague like that?
14:38:03 <gundalow> +1
14:38:06 <samccann> or is it worth adding all PRs?
14:38:48 <felixfontein> good question - sometimes multiple PRs should be mentioned, since later ones can change a lot important things. but also small bugfixes (before release) would be nice to know.
14:39:39 <samccann> I'm +1 for adding all PRs that affect the documented change
14:40:02 <samccann> as a guideline. don't know that we can enforce except for the ones we happen to review (which ain't alot for me in docs land)
14:40:18 <acozine> +1 for encouraging PR numbers in changelogs
14:40:48 <felixfontein> since docs-related changes usually don't have changelog fragments, there's not a lot
14:41:18 <felixfontein> I'm wondering how many PRs actually do have a changelog fragment (of the ones that need one)
14:41:43 <samccann> not sure felixfontein
14:42:27 <felixfontein> I regularly remind people that they need to add changelog fragments, and I'm not sure whether everyone is paying attention (and ansibot also happily merges without changelog fragments)
14:42:31 <samccann> but I think we are agreed to request PR links in changelog fragments.  Anyone disagree?
14:43:26 <felixfontein> I agree. and if we decide to do it, we should announce it here: https://github.com/ansible/community/issues/346
14:43:52 <samccann> okay #agreed add section to changelog docs to request PR links in each for all associated PRs.  Socialize this request on appropriate channels
14:44:30 <gundalow> +1 to announcing on https://github.com/ansible/community/issues/346
14:44:36 <samccann> #link https://github.com/ansible/community/issues/346 for where to announce this change
14:45:10 <samccann> ok onto another easy peasy topic
14:45:27 <samccann> #topic - creating a new issue for the DaWGs agenda
14:45:53 <felixfontein> I'm +1 for that, I'd do that every 3 to 6 months maybe to avoid it getting burried to deep
14:46:01 <samccann> anyone here a bit early would have seen chatter on this - but the current issue where we put the DaWGs agenda comments is old and long to scroll etc
14:46:02 <felixfontein> (and getting too long)
14:46:20 <felixfontein> and one will only find it on page 2 of the issues list in ansible/community
14:46:20 <samccann> Seems other groups create one annually or quarterly etc and I assume close out the old one with a link to the new.
14:47:21 <samccann> so any opinions on if we should do it 3 months or 6 months?
14:47:35 <gundalow> annually should be OK. If you change it too frequently you will lose people
14:47:48 <gundalow> Also you can mark done items as resolved
14:47:51 <samccann> The one we have now isn't quite a year old
14:48:05 <samccann> and that's what's become harder to find/scroll down to etc
14:48:15 <gundalow> https://help.github.com/en/articles/managing-disruptive-comments#hiding-a-comment which is what I do for done items in other agendas
14:49:09 <samccann> ah... so we could hide all the old agenda items, say every month or two. That would solve the scrolling on that particular page
14:49:24 <samccann> but still leaves it on the 2nd page or so of the community issues list.
14:50:05 <samccann> personally, I go here https://github.com/ansible/community  and then to the All working groups, then to DaWGs to find the agenda issue
14:51:42 <samccann> so I can create a new issue since it's been almost a year... and then hide old comments say monthly? (each comment is usually the agenda for the week)
14:52:04 <samccann> do folks agree/disagree with that approach? And we do a new issue annually?
14:52:06 <felixfontein> maybe create a new issue for 2020, and keep using the current one til then. and hide stuff monthly or so.
14:52:22 <samccann> hmm. that does have an appeal, new year, new issue
14:53:12 <felixfontein> hmm, I completely missed the DaWGs logo on https://github.com/ansible/community/wiki/Docs since I never used that page to find the agenda :)
14:53:37 <samccann> hah!  yes we have a spiffy logo now!
14:53:59 <felixfontein> how long has it been there?
14:54:05 <samccann> ok not hearing any disagreements on hiding comments for the rest of this year and starting new agenda issues in 2020
14:54:17 <samccann> Logo was added... maybe a month a go? hasn't been there for long
14:54:20 <acozine> felixfontein: we have stickers, too - unveiled at AnsibleFest
14:54:26 <felixfontein> cool!
14:54:37 <acozine> I will happily send you some, or if you see gundalow, he has some too
14:54:55 <samccann> and credit where do - logo design by https://www.leodurham.com/
14:54:58 <gundalow> felixfontein: I'll send you some
14:55:04 <acozine> not sure where you're based, other than the other side of the Atlantic
14:55:11 <gundalow> closer to me than you :)
14:55:13 <felixfontein> cool!
14:55:27 <felixfontein> gundalow: you could also visit some meetup in zurich or bern ;)
14:55:45 <felixfontein> acozine: in switzerland
14:56:07 <samccann> I don't travel much at all, but when someone decides to have an ansible meetup in Cork, I'm THERE
14:56:11 <samccann> meanwhile
14:56:20 <gundalow> felixfontein: yes, now that Fest is over I can get my head around that
14:56:36 <samccann> #agreed - hide resolved comments in the current DaWGs agenda issue and start a new one with the new year, and annually
14:56:47 <felixfontein> samccann: cork in ireland?
14:56:51 <samccann> #link https://help.github.com/en/articles/managing-disruptive-comments#hiding-a-comment for how to hide comments
14:57:14 <samccann> yeah, my relations came from a TINY  TINY island over there, so someday I wanna go visit said tiny island.
14:57:26 <felixfontein> I don't know any other, but then for a lot of city names from europe, there's tens of similarly named small cities all over the US ;)
14:57:44 <samccann> that there are. I used to live in Berlin (MA) for a decade
14:57:51 <samccann> ok meanwhile,
14:57:53 <felixfontein> hehe :)
14:58:14 <samccann> #topic elements in return values
14:58:17 <samccann> #link https://github.com/ansible/ansible/pull/62929
14:58:21 <felixfontein> I once drove through west berlin and east berlin in nova scotia :)
14:58:30 <samccann> hahaha!!
14:58:45 <felixfontein> two tiny places located next to each other ;)
14:58:45 <samccann> our Berlin was pronounced differently.. BUUURHlin
14:59:21 <samccann> so on the elements in return values felixfontein - I tried the sanity-test locally on your branch and it  didn't have the errors
14:59:55 <felixfontein> #62929 is about how "blabla: <something which is not a sentence>" should be handled in docs.
15:00:46 <samccann> oh did I grab the wrong PR?
15:00:47 <felixfontein> I added both in the same comment to the agenda :)
15:00:55 <acozine> felixfontein: isn't 62929 for clarifying complex return values?
15:01:01 <samccann> ok which do you want to start talking about?
15:01:03 <felixfontein> oh wait
15:01:07 <felixfontein> now I'm confused
15:01:20 <felixfontein> you're totally right!
15:01:28 <felixfontein> I looked at the wrong tab in my browser...
15:01:45 <acozine> heh, the famous ETOOMANYTABS
15:01:50 <felixfontein> I reran the test some minutes ago on CI, with the same result
15:02:54 <samccann> yeah and that's what I ran locally on both devel and your branch and didn't get those errors.  I did ` ansible-test sanity --test docs-build`
15:03:11 <acozine> can we talk about the goal for a second? I think it's a great idea, but will the placement be confusing, since folks are used to seeing the `required` marker in that spot (for options/params)?
15:03:18 <samccann> is that the correct test?  Can anyone see a reason for tha batch of 90+ errors
15:03:34 * samccann blinks in confusion
15:04:14 <samccann> for a return value?
15:04:24 <acozine> maybe those modules got deprecated recently?
15:04:29 <felixfontein> I also saw these errors when running make docs locally once
15:04:48 <samccann> ok maybe I'm doing it wrong locally then. I seldom run the tests (bad me)
15:05:15 <felixfontein> samccann: about required: there's no required for return values (that information is in the "returned" column). and that information was already added earlier for options (where there is "required")
15:05:23 <acozine> samccann: I know, there's never `required` for return values, only for options, but visually the two data sets are very similar
15:06:09 <acozine> if nobody else is concerned, then that answers my question
15:06:14 <acozine> probably not an issue
15:06:24 <felixfontein> samccann: did you run the tests in a clean environment?
15:07:07 <felixfontein> ah sorry, I meant acozine: not samccann: :)
15:07:33 <felixfontein> acozine: about required: there's no required for return values (that information is in the "returned" column). and that information was already added earlier for options (where there is "required")
15:07:37 <felixfontein> there ^
15:08:01 * felixfontein just started a build with "make clean" first. now I can turn off the heating...
15:08:19 <acozine> yup, just for a second with the `blah`/`blah` format, I wasn't sure if i was looking at return values or options
15:08:28 <acozine> that's probably because the screenshot has no context
15:08:46 <felixfontein> acozine: the same thing for module options has been merged here: https://github.com/ansible/ansible/pull/59244
15:08:52 <felixfontein> my PR also adds it for module return values
15:09:59 <acozine> ah, okay, so we do have cases where all three elements appear: `type`/`elements: other_type`/`required`
15:10:01 <acozine> and it looks fine
15:10:28 <acozine> and required is always in red, so anyone with color vision can easily tell the difference
15:10:50 <acozine> within the full context of the module doc, i think this will be very helpful
15:11:21 <felixfontein> with a clean build, I also get these warnings
15:11:31 <acozine> huh
15:12:39 <felixfontein> and when grepping in the docs/docsite/rst folder, I actually cannot find the definition for some of them
15:13:20 <acozine> the error is saying "I'm trying to build a list of all modules, and I can't find the pages for these 97 of them"
15:13:42 <felixfontein> like online_server_info_module.rst is not added to docs/docsite/rst/modules, even though that module exists
15:13:48 <acozine> somehow the template includes the links, but the module docs aren't getting build
15:13:53 <acozine> s/build/built
15:14:03 <felixfontein> (that file sould define the link online_server_info_module)
15:14:37 <samccann> I was working it from the bottom up - the infoblox scenario guide error
15:14:42 <acozine> is that true for all 97? do we have a single problem, or more than one?
15:14:49 <felixfontein> so it looks like some .rst files are not created
15:14:52 <felixfontein> (for modules)
15:15:05 <felixfontein> I didn't check all :) but one missing .rst file is already bad enough
15:15:14 <samccann> it looks like the label used to point to this - https://docs.ansible.com/ansible/latest/plugins/lookup/nios.html#nios-lookup
15:15:34 <felixfontein> ah
15:15:40 <felixfontein> now I see what's happening, I think:
15:15:40 <felixfontein> [WARNING]: Could not parse vultr_firewall_group_facts due to 'list object' has no attribute 'get'
15:15:59 <felixfontein> apparently something went wrong during writing the .rst file for these modules
15:16:08 <felixfontein> but instead of dying, it only emitted a warning
15:17:56 <acozine> the nios lookup plugin has a complex value in its return docs:
15:18:17 <acozine> https://www.irccloud.com/pastebin/3gZ3wyxq/return%20docs%20for%20plugins%2Flookup%2Fnios.py
15:19:09 <acozine> maybe with the changes, any field that has `type: complex` but doesn't have `elements` causes a failure? that's a guess
15:21:25 <felixfontein> I think the problem isn't `type: complex`, but the abuse of `contains:`
15:22:05 <felixfontein> compare `status` in https://docs.ansible.com/ansible/latest/modules/nosh_module.html#return-values with https://github.com/ansible/ansible/blob/devel/lib/ansible/modules/system/nosh.py#L134-L187
15:23:19 <acozine> ah, that should be a sample
15:23:33 <felixfontein> yep
15:24:37 <felixfontein> I think I have a workaround
15:24:56 <felixfontein> simply replacing value.get('elements') --> value.elements seems to work
15:25:14 <acozine> sounds elegant
15:25:31 <felixfontein> yep. easier to read and also works in this case :)
15:25:39 <acozine> but we should also make a list of the plugins that fail in this way
15:25:51 <acozine> at least let the maintainers know they should clean them up
15:25:58 <acozine> and by "we" I mean me, really
15:26:09 <felixfontein> that are probably exactly the modules whose labels are listed in the PR ;)
15:26:27 <acozine> yep
15:26:41 <felixfontein> having a better module validation which catches them would also be good IMO
15:26:48 <acozine> that would be great, yes
15:28:54 <acozine> for the new pipeline from collections, we need a way for failures like this to block publication of specific plugins/modules to docs.ansible.com, while allowing the rest of the build to succeed
15:29:46 <acozine> but the first step is giving folks the tools to do documentation right, and that's what your current PR does, felixfontein
15:30:01 <acozine> thank you!
15:30:54 <samccann> ok we are about at the end here
15:31:01 <samccann> anything before we close?
15:31:05 <felixfontein> yep
15:31:15 <felixfontein> https://github.com/ansible/ansible/pull/63165#discussion_r331860160
15:31:37 <felixfontein> (in case you meant closing the meeting?)
15:32:23 <samccann> ok so on that one - I'd rerewrite to get around the period, not period conundrum if you feel strongly about it
15:32:28 <acozine> I'd vote for "Device read limit in format `thingy`."
15:32:40 <samccann> +1
15:32:41 <acozine> it's not a full sentence
15:32:50 <acozine> but it's closer and the period feels okay there
15:33:00 <felixfontein> ok!
15:33:01 <acozine> or without a period would work too
15:33:10 <felixfontein> then I'll rewrite them so they are "proper" sentences with a period :)
15:33:31 <felixfontein> it's kind of nice if there's a period when there's a next paragraph
15:33:40 <acozine> maybe "Device read limit. Use format `blah`."
15:33:45 <acozine> that's a full sentence at the end
15:33:59 <acozine> I agree, a period there makes things look tidy
15:34:29 <felixfontein> ok, then I'll do some rewriting :)
15:35:00 <acozine> samccann and I have not been keeping up with PRs, sorry
15:35:13 <acozine> but glad you brought that one to the meeting!
15:35:36 <felixfontein> no problem, I thought that when I'm around I can also ask ;)
15:35:47 <acozine> \o/
15:35:53 <samccann> #agreed a period at the end of a description makes it tidy, but doesn't have to be a full sentence to add it.
15:36:07 <samccann> #link https://github.com/ansible/ansible/pull/63165#discussion_r331860160
15:36:18 <samccann> any other tidbits before we close?
15:36:30 <acozine> not from me . . .
15:36:37 <samccann> goin once....
15:36:58 <samccann> twice...
15:37:16 <samccann> #endmeeting