14:32:14 <samccann> #startmeeting DaWGS (Documentation working group)
14:32:14 <zodbot> Meeting started Tue Feb 11 14:32:14 2020 UTC.
14:32:14 <zodbot> This meeting is logged and archived in a public location.
14:32:14 <zodbot> The chair is samccann. Information about MeetBot at http://wiki.debian.org/MeetBot.
14:32:14 <zodbot> Useful Commands: #action #agreed #halp #info #idea #link #topic.
14:32:14 <zodbot> The meeting name has been set to 'dawgs_(documentation_working_group)'
14:32:37 <samccann> oh wow... startmeeting is parentheses sensitive... TIL
14:32:48 <samccann> ok who else is around today to talk the docs??
14:33:15 <acozine> I'm here
14:33:24 <samccann> #chair acozine
14:33:25 <zodbot> Current chairs: acozine samccann
14:33:40 * samccann hands over baton
14:33:49 <cbudz> I've got to dip in and out today, working on a potential release among a few other things
14:34:25 <acozine> andersson007_: baptistemm cbudz cyberpear felixfontein kmaxwell madonius mrproper Pilou shaps tributarian Xaroth you folks around?
14:34:39 <acozine> gundalow: you chatting docs today?
14:34:49 <felixfontein> I'm halfway around :)
14:35:14 <acozine> #chair felixfontein
14:35:14 <zodbot> Current chairs: acozine felixfontein samccann
14:35:31 <acozine> even half a presence gets to be furniture!
14:35:50 <acozine> #chair cbudz
14:35:50 <zodbot> Current chairs: acozine cbudz felixfontein samccann
14:36:20 <cbudz> lol
14:36:27 <gundalow> acozine: Hi, I'm in another meeting at the moment
14:36:37 <acozine> ah, the duelling meetings!
14:36:56 <acozine> gundalow: join us at the top of the hour if you can
14:37:55 <acozine> okay, I'm going to do the agenda items out of order, I think
14:38:02 <acozine> #topic March Docs Madness
14:38:26 <samccann> rebel
14:38:32 <acozine> heh
14:38:59 <acozine> samccann and i were chatting at the end of last week, and we think it's time to see if we can reduce the number of open docs issues
14:39:13 <acozine> so that's our theme for March this year
14:39:14 <samccann> \o/
14:39:54 <acozine> so if anyone has free time, pick an issue with the label `docs` - it can be any issue
14:39:56 <samccann> can we do things like post this on reddit etc to see if we can bring in other contributors? I figure we can mark some as easyfix and hope for the best?
14:40:06 <acozine> that's a great idea
14:40:19 <samccann> unfortunately I'm not on twitter but maybe we can find someone who is
14:40:35 <cbudz> I started on a few last week. Will get back to that asap
14:40:38 <samccann> and on the ansible channel here
14:40:54 <acozine> here's a link to the full list: https://github.com/ansible/ansible/issues?utf8=%E2%9C%93&q=is%3Aissue+is%3Aopen+label%3Adocs
14:41:33 <samccann> #info we are focusing on fixing docs issues in the month of March - https://github.com/ansible/ansible/issues?utf8=%E2%9C%93&q=is%3Aissue+is%3Aopen+label%3Adocs
14:41:36 <acozine> there may be some that are old enough to be irrelevant
14:42:01 <samccann> yeah I figure that's part of the strategy - attack it from both ends and see what we get.
14:42:27 <samccann> would be great to at least go through all 200+ to know what level of work we're talking about
14:42:40 <acozine> for anyone who doesn't have admin rights on the repo, if you find a docs issue that can/should be closed, put a comment on it and mention it here
14:43:16 <samccann> #info for anyone who doesn't have admin rights on the repo, if you find a docs issue that can/should be closed, put a comment on it and mention it here
14:43:36 <acozine> if you find one that should be labelled `easyfix` and you can't add labels, do the same thing - post a comment on GitHub and mention it here
14:44:05 <samccann> is it worth opening up a docs issue called 'march madness' or something and put all the details there? That way we can use that link to share on social media, irc, etc etc each week to try drawing in contributors?
14:44:12 <acozine> and if you find one you can fix, go for it and ping us with the PR
14:44:21 <acozine> samccann: another great idea, yeah, let's do that
14:44:45 <samccann> #info and if you can find a docs issue you can fix, go for it and ping us with the PR for review here
14:44:47 <acozine> it will add one more open issue to the list, but it may help us keep track and bring folks in!
14:45:23 <samccann> #action samccann to create a March Madness docs issue to describe the details of how folks can help etc so we can share the issue on social media/reddit/irc etc
14:45:40 <samccann> yeah it's a one stop pointer to whatever folks need to help us out I think.
14:45:41 <felixfontein> there's also the question on when most of the modules are moved out of ansible/ansible, because that's when a lot of issues will point to nothing (and potentially will be closed)
14:45:43 <acozine> \o?
14:46:03 <acozine> felixfontein: yes, we're thinking ahead to that as well
14:46:37 <acozine> we'll need to have a major clearing-out of issues and PRs when the modules migrate
14:46:42 <samccann> oof... that will hit open PRs pretty hard as well, won't it?
14:46:56 <acozine> some of the issues can move to the new repos
14:47:09 <acozine> samccann: probably so, though I'm not sure of numbers
14:47:12 <felixfontein> samccann: yep, and I hope there will be an announcement ahead of time
14:47:56 <acozine> felixfontein: announcement like "modules are moving out of core next week, please get ready to move your PRs and issues"?
14:48:01 <samccann> feels like part of this discussion should be happening on the community channel
14:48:30 <felixfontein> acozine: more like a hint to people to review and merge them in time, if possible
14:48:39 <samccann> acozine do you want me to 'minute' these ideas so we don't lose them anyway?
14:48:59 <acozine> felixfontein: I'd say review and merge now, if possible
14:49:13 <felixfontein> if you convince people to start docs PRs, and they are suddenly all closed, that's probably not helpful :)
14:49:37 <acozine> felixfontein: that's why I'm hoping people will post their PRs here
14:49:45 <acozine> so we can merge them as quickly as possible
14:49:49 <samccann> hmm. is there a timing problem here?  I don't know the timeframe when modules move out of ansible/ansible
14:50:06 <acozine> I'm not sure how much advance notice we will get before the move
14:50:30 <acozine> so I'd like to keep up with merging PRs, as much as possible
14:50:44 <felixfontein> samccann: I think it's not really known yet. I've heard that it should be around now, but that was 1-2 weeks ago...
14:50:52 <samccann> eep
14:50:55 <felixfontein> or at least not publicly known :)
14:51:33 <samccann> ok maybe we need to reconsider march madness then. maybe it needs to be the clearingout time to move issues to whatever repo the underlying modules moved to?
14:52:05 <acozine> if there are issues that are still relevant, they will still be relevant after the move
14:52:15 <samccann> i feel like we are in a tricky time right now, that gathering community help to fix issues will hit that modules have moved wall and annoy new contributors
14:52:26 <acozine> hmmmm
14:52:35 <samccann> acozine - yes, but they will need to be moved and fixed in a differenet repo
14:52:43 <acozine> that's true
14:53:01 <acozine> all right, maybe we have to keep the March Madness thing internal
14:53:14 <acozine> but it sure would be nice to bring those numbers down before the migration if we can
14:53:45 <acozine> otherwise we'll have double the work - identify the issues that are still relevant, move them to the correct repos, then fix them
14:53:48 <samccann> Well March Madness had a ring to it in the US because of basketball.. but there's nothing to say we can start looking at and drawing down issue count now
14:53:49 <felixfontein> maybe gundalow knows more
14:54:53 * samccann wonders if gundalow is like betelgeuse - say it three times and he shows up...
14:55:30 <acozine> while we wait for more info, shall we chat about the Common Return Values page?
14:55:38 <samccann> meanwhile we have two problems - issues that will have to be moved... and PRs that will no longer be valid
14:55:46 <samccann> which to address and when.
14:57:01 <samccann> #info timing of ansible/ansible modules moving out will impact open issues and PRs. So March Madness may be just an effort starting now to fix issues or close out those no longer relevant
14:57:33 <acozine> things are rarely as straightforward as I wish they were
14:57:39 <samccann> #info please bear with us as we don't know when the change happens so PRs may have to be moved to another repo when that happens
14:57:46 <samccann> does that ^^ sound about right?
14:57:51 <acozine> sounds good
14:58:37 <acozine> all right, anything else on the topic of existing issues?
14:58:49 <acozine> going once . . .
14:59:05 <acozine> going twice . . .
14:59:14 <acozine> gone
14:59:21 <acozine> #topic common return values
15:00:34 <acozine> so, yesterday baptistemm opened a PR that would have stripped any values documented on the Common Return Values page out of the shell module docs
15:01:31 <acozine> felixfontein pointed out that the "common" return values do not come from common/shared code
15:02:01 <felixfontein> it should be made clear that modules in general do not return these values (except `failed` and `changed`), and that modules should really document everything they return except these two
15:02:01 <acozine> so they are commonly used, but there's nothing guaranteeing consistence in them from one module to another
15:02:23 <felixfontein> there is a bit of magic, I think: if a module returns stdout, something will add stdout_lines (and same for stderr I think)
15:02:55 <felixfontein> I don't really have an overview of what magic happens where with that regard, though :)
15:03:20 <acozine> the page is here: https://docs.ansible.com/ansible/devel/reference_appendices/common_return_values.html
15:04:08 <felixfontein> and the paragraph inserted into every module docs is here: https://docs.ansible.com/ansible/latest/modules/ldap_attr_module.html#return-values
15:04:39 <samccann> #info modules in general do not return these values (except `failed` and `changed`), and that modules should really document everything they return except these two
15:05:00 <acozine> what about the four marked `internal use` on the common return values page?
15:05:08 <samccann> #link https://docs.ansible.com/ansible/devel/reference_appendices/common_return_values.html
15:05:20 <acozine> ansible_facts, exception, warnings, deprecations . . . are they truly shared?
15:05:50 <samccann> #info the paragraph inserted into every module docs is here: https://docs.ansible.com/ansible/latest/modules/ldap_attr_module.html#return-values
15:05:56 <felixfontein> for Python modules (using the standard framework), they are only inserted when needed
15:06:20 <acozine> ah
15:07:20 <acozine> so that page should really go away, and each module should fully document its own return values
15:07:42 <acozine> we can create a shared docs fragment for `failed` and `changed`
15:08:02 <felixfontein> no idea what happens for binary modules, or Windows modules though...
15:08:17 <acozine> me neither ;-)
15:08:47 <felixfontein> and then there's special stuff like `results` and `skipped`, which isn't returned by the module, but set by Ansible itself if this isn't a single module invocation (but a loop, or a skipped task)
15:10:39 <acozine> do we have a page for "what Ansible output looks like"?
15:10:42 * gundalow returns
15:10:49 <acozine> #chair gundalow
15:10:49 <zodbot> Current chairs: acozine cbudz felixfontein gundalow samccann
15:11:21 <acozine> gundalow: if you scroll back, we were talking about the timing of the Great Module Migration and its effect on PRs and issues
15:11:32 <gundalow> samccann:  `can we do things like post this on reddit etc to see if we can bring in other contributors? I figure we can mark some as easyfix and hope for the best?` --- Yes Reddit it good for finding other people
15:12:01 <acozine> are we going to auto-migrate issues and PRs with modules?
15:12:10 <gundalow> +1 to docs issue called 'march madness'
15:13:11 <gundalow> I don't expect every issue and PR to be migrated
15:13:34 <acozine> gundalow: we don't want people to open PRs only to have them rendered obsolete when the modules migrate
15:13:36 <felixfontein> gundalow: is there an update to when the migration will happen?
15:13:51 <gundalow> If there are under 25 issues and 25 PRs for a collection (ie one results page in GitHub) then auto migrating them might be good
15:13:52 <acozine> if that's going to happen in early March, maybe we should wait for a later Madness Month?
15:14:09 <gundalow> No date confirmed, though there is some talk of early March
15:14:27 <gundalow> Reviewing and merging PRs (rather than creating new ones) would be good
15:15:05 <gundalow> `is:open label:docs is:pr -label:backport ` = 108 PRs
15:15:29 <gundalow> take away `support:core` and it's down to 24 Prs
15:15:34 <samccann> most of those are not docs only. We don't tend to merge any PRs that also have code
15:15:39 <acozine> yeah, they bred while I was out with the flu and samccann was holding the fort down single-handed
15:16:24 <acozine> I take your point, though, gundalow, and it's the same thing samccann and felixfontein were saying
15:16:37 <acozine> instead of focusing on issues, let's keep the focus on PRs
15:16:46 <samccann> #info focus on reviewing/merging open PRs until the Great Module Migration happens. So March Madness on docs issues may be pushed out depending on the timing of it all
15:16:48 <acozine> and try to whittle away at those while we can still merge them without moving them
15:17:14 <samccann> is there a strategy we can follow for prs that are both docs  and code?
15:18:48 <samccann> or maybe we put an approval/LGTM for docs on them and assume the code portion gets reviewed separately/on time?
15:20:12 <acozine> or post them in ansible-devel daily?
15:20:59 <samccann> :-)  cuz everyone loves a good nag
15:21:16 <acozine> to use another basketball metaphor, we do a full court press
15:21:29 <samccann> we could definitely do that for the ones that look (to us) like a simple code fix. might help move 'em along
15:21:49 <samccann> what triggers an automerge?
15:22:06 <acozine> approvals from owners
15:22:10 <samccann> i've seen people add shipit to the comments.
15:22:19 <samccann> ah so the shipit does nothing?
15:22:30 <acozine> sorry, a shipit is an approval
15:22:47 <acozine> I think Ansibot requires two shipits from two different people
15:23:00 <samccann> ah okay. but no need for us to add shipit as well, right?  just approval from us?
15:23:02 <gundalow> I've just merged 67099, 67164, 67082, 66973, 66899, 66794
15:23:08 <acozine> wow, thanks gundalow
15:23:17 <acozine> six down, 102 to go ;-)
15:23:17 <gundalow> They were all fairly simple
15:23:22 <felixfontein> if the PR author is maintainer/author, one additional shipit suffices
15:24:08 <acozine> ah, so Ansibot sees that as the equivalent of two shipits . . .
15:24:10 <acozine> cool
15:24:11 <samccann> but  again, do we as doc peeps (me at least since I can't approve code to save my soul) - should I approve AND put a shipit comment?
15:24:22 <acozine> I'd say one or the other
15:24:32 <samccann> which one moves it along better :-)
15:24:54 <samccann> or do we not want a docs shipit to be the deciding factor in a code PR with docs?
15:25:00 * samccann beats this one to death
15:25:02 <acozine> heh
15:25:19 <acozine> we should have been keeping track of that over the last year
15:25:26 <acozine> then we would have actual data
15:25:33 <gundalow> If you think it's good, mention it in #ansible-devel for a 2nd review (or if we get bored we can just hit merge)
15:25:48 <samccann> ok sounds good
15:25:50 <acozine> generally speaking if a PR has one shipit from someone who knows the code, and the docs look good, I merge
15:26:09 <acozine> (for "mixed" code-and-docs PRs)
15:26:20 <samccann> #info on PR with docs and code - approve and mention in #ansible-devel for code review or someone to merge
15:26:33 <acozine> oops, we have four minutes left
15:26:39 <samccann> yeah that's something I haven't done acozine, but I could
15:26:40 <acozine> #topic open floor
15:26:48 <gundalow> acozine: +1 to that merging methodology
15:26:54 <acozine> samccann: you totally can!
15:27:06 <samccann> ooph Pilou had a pr with comments can we grab that quickly?
15:27:27 <acozine> sure . . . do you have the link?
15:27:33 <acozine> is this the one he was tweeting about?
15:27:35 <samccann> https://github.com/ansible/ansible/issues/50278
15:27:43 <samccann> #link https://github.com/ansible/ansible/issues/50278
15:28:59 <samccann> I can't tell quickly if it's asking for a docs clarification, or if it's a bug as bcoca mentioned in the comments way back when?
15:29:12 <acozine> I'm confused, this is an issue, not a PR
15:29:29 <samccann> o sorry, yeah it's an issue.
15:29:54 <samccann> but since Pilou put it on the agenda, I wanted to at least have a short groupthink on it if we could and decide what's next for it
15:30:03 <samccann> might be out of time tho
15:30:22 <acozine> it looks to me like he found a bug
15:30:29 <felixfontein> it might be better suited for the core meeting, until it is decided whether this is a core bug or a docs bug :)
15:31:19 <acozine> sounds good to me - will you add it felixfontein ?
15:31:24 <samccann> ok thanks
15:31:53 <samccann> #info issue 50278 should be discussed in the core meeting to determine if it's a code bug or docs bug
15:31:54 <acozine> sorry I should have gotten to that sooner
15:32:09 <samccann> np busy day and lots to chat about!
15:32:17 <acozine> I got carried away ;-)
15:32:32 <acozine> all right, anything else we need to address?
15:32:51 <acozine> any updates, comments, questions, complaints, suggestions?
15:32:56 <felixfontein> I'm right now not near my github account, so if anyone wants to add it there, please do so :)
15:33:21 <acozine> felixfontein: okay, we'll add it
15:33:30 <acozine> I forgot you're probably on a train
15:33:46 <felixfontein> no, still at work ;)
15:33:51 <acozine> oh, even worse
15:34:03 <acozine> all right, looks like we've gone three minutes over
15:34:52 <acozine> thanks samccann cbudz felixfontein gundalow
15:35:00 <acozine> #endmeeting