14:02:59 <acozine> #startmeeting Supplemental Docs Working Group aka DaWGs
14:02:59 <zodbot> Meeting started Thu May 28 14:02:59 2020 UTC.
14:02:59 <zodbot> This meeting is logged and archived in a public location.
14:02:59 <zodbot> The chair is acozine. Information about MeetBot at http://wiki.debian.org/MeetBot.
14:02:59 <zodbot> Useful Commands: #action #agreed #halp #info #idea #link #topic.
14:02:59 <zodbot> The meeting name has been set to 'supplemental_docs_working_group_aka_dawgs'
14:03:11 <acozine> hi briantist, welcome!
14:03:15 <acozine> who else is around?
14:03:27 <acozine> #chair bcoca briantist samccann
14:03:27 <zodbot> Current chairs: acozine bcoca briantist samccann
14:04:37 <acozine> dmellado relrod andersson007_ cbudz cyberpear felixfontein jhawkesworth madonius Pilou Sayee shaps tadeboro Tas-sos you folks talking docs today?
14:05:37 * acozine reads through this morning's chat to catch up
14:06:13 <bcoca> ^ why i stopped keeping backlog .. or i would be done by 11pm with 'catchup'
14:06:41 <acozine> heh, yep
14:06:55 * samccann waves late
14:07:52 <acozine> samccann: welcome, I already made you furniture ;-)
14:08:22 * acozine searches through her many tabs for the agenda
14:08:58 <acozine> here we go: https://github.com/ansible/community/issues/521#issuecomment-634113165
14:09:33 <acozine> first question comes from the community team
14:10:14 <acozine> We are almost ready to migrate PRs and issues that relate to modules and other plugins that have moved to collections.
14:10:16 <acozine> The question is:
14:10:32 <acozine> What documentation do we need about contributing to collections?
14:10:56 <samccann> sorry was that the question though?
14:11:00 <samccann> I mean good question :-)
14:11:16 <acozine> So that when folks get a notification from GitHub that their PRs or issues have been closed or moved, they know what to do.
14:11:21 <acozine> heh
14:11:32 <samccann> yeah that's the detail i was thinking
14:11:35 <acozine> at least it's more answerable than "to be or not to be"
14:11:38 <samccann> LOL
14:11:49 <samccann> i'm all in favor of the to be
14:12:04 <acozine> heh, yep
14:12:09 <samccann> so the big question is - contributor guide for collections vs ansible-base etc
14:12:30 <acozine> yeah, I think it's partly a location thing - where do those docs belong?
14:12:37 <samccann> the narrower question is  - specifically what do we need written so that anything/anyone that closes or moves a PR/issue can point to docs about what and why and what to do next
14:12:45 <acozine> and it's partly a content thing - what do people need to know?
14:12:51 <acozine> yes
14:13:04 <samccann> i got the feeling the narrow question was urgent so someone can clean out the backlog
14:13:10 <acozine> briantist: are you involved in any of the collections?
14:13:18 <samccann> but you know, my feelings aren't always spot on :-P
14:13:32 <acozine> yes, ansibot is going to close or move everything soon
14:13:48 <samccann> #topic contributing to collections and docs for when issues/prs move via ansibot
14:13:56 <acozine> oops, thanks samccann
14:14:14 <samccann> np.  I don't have your knack for short summary topics for sure :-)
14:14:15 <briantist> Yes I'm mostly involved in windows collections, with a little contribution to c.g, and in the AWS collections mostly submitting issues
14:14:51 <acozine> So you are already comfortable with questions like "How do I raise a PR against a collection" and "How do I know where this plugin went?"
14:14:52 <samccann> #info ansibot will soon close/move much of the backlog. We need a doc link it can point to to explain what is happening, why, and what the OP should do now
14:14:56 <briantist> but I'm just an outside user/contributor, not sure how involved counts as "involved" :)
14:15:19 <samccann> #info as part of an overall contributing to collections vs contributing to ansible-base docs rewrite
14:15:23 <acozine> outside users/contributors are the audience for this, so you are very, very involved
14:15:48 <acozine> also, I dispute the "just" in your sentence briantist
14:15:54 <briantist> I am ok with it but it can be difficult, especially for stuff that's split between ansible/community, like Windows and AWS
14:16:07 <samccann> congrats briantist you just made target audience level!  (insert badge here)
14:16:26 <acozine> so-called "outside contributors" are the heart and soul of the Ansible project
14:16:45 <acozine> oh, interesting - what's the most difficult part?
14:17:24 <samccann> so are you saying the difficulty for example, is that for AWS or Windows, what you want is possibly in community.general, community.windows, or windows.azure (making up names here btw - but can be split across related collections?)
14:17:25 <briantist> something I've brought up in #ansible-aws previously is that it's super confusing to know where to even submit issues, especially because of the module utils for many of the community  modules living in the amazon collection, and end users for the most part don't know that their issue with `elb_network_lb` (in `amazon.community`) is really about `elbv2.py` module util in `amazon.aws`
14:18:09 <felixfontein> hey
14:18:15 <felixfontein> sorry, got totally sidetracked :/
14:18:16 <samccann> #info an example of confusion the module utils for many of the community  modules living in the amazon collection, and end users for the most part don't know that their issue with `elb_network_lb` (in `amazon.community`) is really about `elbv2.py` module util in `amazon.aws
14:18:24 <acozine> welcome felixfontein!
14:18:27 <briantist> thanks acozine by "just" I meant that I don't have merge privs or any special status within the projects (I'm not sure how I started getting tagged in these meetings specifically but I'm here for it! haha )
14:18:29 <samccann> great example briantist
14:18:48 <acozine> #chair felixfontein
14:18:48 <zodbot> Current chairs: acozine bcoca briantist felixfontein samccann
14:18:51 <samccann> show up once and there's always a chair waiting for you :-)
14:19:30 <acozine> yep
14:19:46 <felixfontein> about the deprecation info for modules (removed_in): I have a PR to fix that (https://github.com/ansible/ansible/pull/69727), it allows other versions than Ansible-base versions and also allows to add dates
14:20:10 <felixfontein> (also it adds a sanity check so that meta/runtime.yml and docs say the same)
14:21:02 <felixfontein> ok, read up until now
14:21:19 <acozine> felixfontein: that's awesome, let's put the deprecation/removed_in thing next on the agenda
14:22:32 <acozine> follow-up question about figuring out where to put issues for collections
14:23:11 <felixfontein> issues for collections is definitely hard :)
14:23:44 <felixfontein> especially (as briantist mentioned) when it concerns things that might come from another repo (module_utils, docs fragments)
14:23:46 <acozine> briantist: you said: it's confusing to know where to submit issues, especially for module utils that may live in one collection but affect modules in one ore more other collections
14:24:04 <acozine> how do the folks "in the know" figure that out?
14:24:40 <felixfontein> all the modules I work with don't have code spread over multiple repos (except code from ansible/ansible that is)
14:24:54 <acozine> is there a procedure that would help newbies figure this out?
14:24:56 <felixfontein> I guess this is a good question for jillr and tremble
14:24:58 <samccann> the network team has a similar spread.
14:24:59 <felixfontein> (both of whom are not here)
14:25:18 <briantist> there's no documentation on which modules use which utils, so you either have to have worked on the module or need to know how to browse a module's code to know it even uses a util. The actually know that a particular bug is in the util and not the main module? you need deeper knowledge to know that, something the majority of users would never know
14:25:33 <briantist> so good triagers are essential for that
14:25:35 <acozine> oh, interesting
14:25:52 <acozine> I wonder if we *could* document that in future
14:26:01 <felixfontein> true. someone who knows the module's internals usually can help, but anyone who doesn't is usually completely lost
14:26:04 <acozine> it seems possible - the code has to "include" them, right?
14:26:05 <samccann> feels difficult to solve in just docs
14:26:28 <felixfontein> I don't think it makes sense to document it; this is probably the job of the module maintainers to figure this out and redirect pepole if possible
14:26:33 <samccann> so if I'm using aws and something breaks and I want to open an issue, where do I open it?
14:26:42 <briantist> The relationship itself, yes I think I that's possible, and useful. But anything deeper as samccann said isn't really possible
14:26:47 <samccann> and then when it's in the wrong place, who is responsible for moving it? Can't expect the user to know
14:26:54 <felixfontein> samccann: I would open the issue in the repo where the module (or plugin) is from
14:27:10 <samccann> +1 for that
14:27:17 <felixfontein> samccann: I would say that both repos should have an issue (so the original is also correct), with a link between them
14:27:29 <briantist> but re: even documenting the relationship, there's also no docs on the utils themselves; so nowhere to link to it would just be a statement that doesn't mean that much to most people
14:27:51 <felixfontein> like "this bug (in community.aws.s3) is caused by bug #xxxx in ansible.aws."
14:29:23 <briantist> felixfontein: oh that's interesting, as a contributor I might start doing that, but I don't foresee end users submitting 2 issues
14:29:25 <samccann> goes github allow you to close out an issue in one repo w/ a PR in a separate repo?
14:29:58 <samccann> or would you close out the first issue (that the user created) by saying you moved this to ansible.aws issue xxx?
14:30:01 <felixfontein> briantist: I guess the second issue could be filed by the maintainer
14:30:07 <felixfontein> (depending on what the problem is)
14:30:15 <samccann> yeah I think ^^^ is critical here
14:30:20 <felixfontein> if it's a feature request, you could also let the one wanting the feature do it :)
14:30:34 <acozine> so for docs, maybe we say something like "Plugins rely on module utilities, which may be shared across collections. A bug in a module may come from code in `module_utils`.  Collection maintainers can help find the root cause of any issue in a collection."
14:30:37 <samccann> a user shouldn't necessarily be responsible for picking the correct repo when things are split so much
14:31:13 <felixfontein> acozine: I'd also explicitly mention "code in `module_utils` from ansible-base or another collection."
14:31:27 <acozine> felixfontein: good thought
14:32:05 <samccann> so we can add something to the 'how to open an issue' section of the docs to clarify some of this.
14:32:29 <samccann> do we also need buyin from collection owners that they will own the followthrough when something is opened in the wrong but related repo?
14:32:34 <acozine> yeah, "how to open an issue" and maybe "what to expect when you open an issue"
14:33:09 <samccann> #info add to the "how to open an issue" to explain what to expect, esp with content in different repos/collections that are related
14:34:10 <felixfontein> we can hope or ask them to do it, but I guess we can't expect them to really do it (like we can't expect that community maintainers do what we want from them :) )
14:34:14 <samccann> What I worry about is  - i open an issue in community.foo but it really belongs in bar.foo (a related collection owned by someone else).  how do we prevent community.foo from just closing it and saying 'wrong repo' ?
14:35:00 <briantist> samccann: I think buyin is critical; I don't know if it's just because they're not officially open or what but I haven't had even a comment on any issue I've submitted to either AWS collection, for example, and I moved the ones I had in the wrong place myself; someone else who submitted a small fix hasn't got any review or response either and seemed frustrated
14:35:01 <acozine> samccann: I don't think we can control that
14:35:05 <samccann> ok but we do have categories where we CAN expect them to do the right thing (the network collection overlaps, Windows and AWS I think we have relationships with the owners etc)
14:35:30 <samccann> and for those that don't, they will find less and less community interaction
14:36:13 <samccann> perhaps a bigger category tho  - people using ansible 2.10 (aka acd) hit an issue, and just run to ansible/ansible to open the issue
14:36:35 <samccann> does the ansibot magic work to redirect that to the appropriate collection repo?
14:36:47 <felixfontein> I think there is already some magic partially set up
14:36:50 <felixfontein> at least there will be labels
14:36:58 <felixfontein> and eventually I think it will have some redirection text
14:37:05 <acozine> for those we can at least control the response, and I think now that the routing PR is merged, we should be able to auto-redirect those
14:37:17 <felixfontein> https://github.com/ansible/ansible/issues?q=is%3Aissue+is%3Aopen+label%3Aneeds_collection_redirect
14:37:36 <acozine> briantist: sorry to hear you haven't had responses on your AWS issues
14:37:58 <briantist> something in the github issue template is probably also good (get people to look at collections before submitting); even though it might get ignored anyway
14:38:08 <acozine> that's a good idea
14:38:13 <felixfontein> indeed!
14:38:19 <felixfontein> some people actually read the things in there :)
14:38:36 <acozine> #info update the github template to encourage people to look at collections before opening issues
14:38:36 <samccann> #agreed something in the github issues template to get people to look at collections before submitting would help
14:38:39 <samccann> HAHA
14:38:39 <acozine> heh
14:38:53 <acozine> samccann: as usual, you are the IRC meeting guru!
14:39:08 <samccann> well, it should be an action so...
14:39:17 <acozine> yes, it should!
14:39:21 <samccann> #action  edit github issue template as above
14:39:25 <samccann> :-)
14:39:40 <acozine> heh
14:40:06 <acozine> circling back to the original question of providing docs for the collections PR/issue migration
14:40:14 <acozine> it looks like we need to update https://docs.ansible.com/ansible/devel/community/reporting_bugs_and_features.html#reporting-bugs
14:40:50 <acozine> heh, and we have duplicated content at https://docs.ansible.com/ansible/devel/community/reporting_bugs_and_features.html#request-features
14:40:50 <samccann> #action - update https://docs.ansible.com/ansible/devel/community/reporting_bugs_and_features.html#reporting-bugs
14:40:55 <briantist> I wish the "devel" documentation that's currently published was more up-to-date with the collections, and actually pointed at where the modules are. That would be very nice in finding where an existing module has moved to. Right now I guess which collection then browse its modules in github :-/
14:41:27 <briantist> guessing that will come fairly soon anyway, but even before 2.10 while developing/contributing it would have been helpful
14:41:27 <acozine> briantist: now that the routing PR is in, I think we can do that
14:41:28 <samccann> #action remove duplicate content from https://docs.ansible.com/ansible/devel/community/reporting_bugs_and_features.html#request-features
14:41:34 <briantist> oh cool
14:41:37 <felixfontein> briantist: part of the problem is that right now, the list of "where was module X moved to" is not really up to date
14:41:54 <samccann> wouldn't the where a module is be more obvious once the docs pipeline is there?
14:42:04 <felixfontein> samccann: true
14:42:09 <briantist> makes sense felixfontein
14:42:14 <acozine> that will definitely help, as long as we can get the redirects in
14:42:14 <samccann> as in the collection location is added to the module page at that point
14:42:41 <samccann> though I think it's the galaxy location, but galaxy has the repo where a public repo is available
14:43:05 <acozine> it will be a couple of clicks, but at least it will be available
14:43:26 * samccann votes for a click and a clack
14:43:33 <felixfontein> :)
14:43:46 <acozine> and for modules in the big omnibus collections, most folks will know which GitHub repo that is without looking at Galaxy
14:44:03 <acozine> heh, the Tappit Brothers visit the DaWGs
14:44:05 <briantist> haha, but it will still have to wait until the first version is published in galaxy. I used to abuse the "edit in github" link (and then click cancel) on modules previously
14:44:28 <briantist> acozine: nice lol that was such a great show
14:45:07 <acozine> briantist: we hope to reinstate the Edit in GitHub feature for at least some collections, but we're pretty swamped right now
14:45:55 <briantist> 👍
14:46:21 <acozine> felixfontein: we're joking about a radio show called Car Talk that featured two actual brothers - they joked that their names were "Click and Clack, the Tappit Brothers"
14:46:44 <acozine> one of the brothers dies a few years ago
14:46:52 <felixfontein> oh
14:46:52 <acozine> s/dies/died
14:47:00 <felixfontein> and now it's just click? or clack?
14:47:29 <acozine> yeah, i don't remember which was which
14:47:41 <briantist> very sad, they were so funny and helpful
14:48:15 <acozine> yep, they were awesome
14:49:02 <acozine> all right, we have some action items for documenting the Collections PR and Issue Migration
14:49:48 <acozine> I'll pull a draft PR together by the end of the week
14:50:04 <acozine> and folks can comment on it, add to it, etc.
14:50:37 <acozine> looks like we have time for one more quick topic
14:50:38 <felixfontein> sounds good :)
14:50:42 <acozine> I'll even skip the open floor today
14:51:07 <acozine> what else shall we cover samccann ?
14:51:23 <samccann> oh lemme check the agenda quick
14:51:44 <felixfontein> oh just FYI: multi-paragraph changelog entries should work (with a small PR): https://github.com/ansible-community/antsibull/pull/47
14:51:50 <samccann> is there anything else we need to talk about for the version added?
14:52:11 <samccann> https://github.com/ansible/ansible/pull/69291
14:52:31 <acozine> felixfontein: awesome news on changelogs
14:52:46 <felixfontein> samccann: that PR definitely won't make it for 2.10
14:52:47 <samccann> or maybe it's not a docs thing to track at this point and we drop it from the agenda?  not sure
14:53:12 <felixfontein> I still have hopes for https://github.com/ansible/ansible/pull/69631 , depends on the next meeting...
14:53:44 <felixfontein> ah wait
14:53:56 <felixfontein> here it is: https://github.com/ansible/ansible/pull/69680
14:54:42 <acozine> erm, it hasn't been triaged, even
14:55:00 <samccann> hmm. that assumes a version based deprecation but a bunch of collections are using a date based deprecation. what's the impact of that on the PR?
14:55:12 <abadger1999> Did nitzmahone commit to that one?
14:55:20 <acozine> felixfontein: when you say "depends on the next meeting" you mean the core meeting?
14:55:30 <acozine> abadger1999: welcome!
14:55:30 <felixfontein> acozine: yes
14:55:36 <acozine> okay, good
14:55:50 <abadger1999> And if docs needs int, perhaps it needs to go up the internal hierarchy to be flagged as a 2.10 blocker?
14:55:51 <felixfontein> samccann: I started adding date tagging support in the PR, so that will be fine too
14:56:00 <abadger1999> I hate that we don't have go-no-go meetings in this project....
14:56:21 <acozine> those would be helpful
14:58:27 <felixfontein> I guess it would be good if at least parts of the PR could make it into 2.10, most importantly the support for Display.deprecate() to handle tagged versions/dates in a nice way
14:58:58 <acozine> it would be very good to include that in 2.10
14:59:03 <felixfontein> (unfortunately one would need a lot of ignore.txt entries then)
14:59:17 <acozine> when is the meeting where it will be discussed next?
14:59:24 <felixfontein> in one minute in #ansible-meeting
14:59:29 <acozine> oh, jeez
14:59:31 <felixfontein> IIRC
14:59:34 <acozine> I'm triple-booked
14:59:39 <felixfontein> it's 17:00 UTC
14:59:55 <acozine> I will raise my voice as/when I can
15:00:06 <acozine> meanwhile, speaking of other meetings . . .
15:00:09 <felixfontein> I put two other PRs first which hopefully don't require much discussion
15:00:20 <samccann> oh yeah time to end this one
15:00:25 <acozine> I need to close this one out so I can follow the other three ;-)
15:00:29 <samccann> hahah
15:00:33 <felixfontein> :)
15:00:34 <felixfontein> good luck!
15:00:49 <acozine> thanks abadger1999 briantist felixfontein samccann and everyone following along at home!
15:01:00 <acozine> #endmeeting