15:33:24 <acozine> #startmeeting DaWG weekly
15:33:24 <zodbot> Meeting started Tue Nov 27 15:33:24 2018 UTC.
15:33:24 <zodbot> This meeting is logged and archived in a public location.
15:33:24 <zodbot> The chair is acozine. Information about MeetBot at http://wiki.debian.org/MeetBot.
15:33:24 <zodbot> Useful Commands: #action #agreed #halp #info #idea #link #topic.
15:33:24 <zodbot> The meeting name has been set to 'dawg_weekly'
15:33:47 <acozine> #chair
15:33:47 <zodbot> Current chairs: acozine
15:33:53 <acozine> oh, that won't do
15:34:10 <acozine> #chair gundalow Xaroth
15:34:10 <zodbot> Current chairs: Xaroth acozine gundalow
15:34:14 <acozine> who else is around?
15:34:32 <samccann> *waves*
15:34:43 <acozine> #chair samccann
15:34:43 <zodbot> Current chairs: Xaroth acozine gundalow samccann
15:35:39 <acozine> so, full disclosure, last week was Thanksgiving in the US, so there's been a lot of turkey-eating and not a lot of working going on on this side of the pond
15:36:48 <acozine> gundalow and I did finish the new Community index page (TOC): https://docs.ansible.com/ansible/devel/community/index.html
15:36:58 <acozine> comments, suggestions, feedback of all types welcome!
15:37:24 <samccann> +1 like it!
15:37:40 <Xaroth> +1 from me as well
15:38:37 <acozine> awesome!
15:38:54 <acozine> today's WIP is currently in google-docs form
15:39:18 <acozine> #topic new docs page: How to review & test a PR
15:39:34 <acozine> https://docs.google.com/document/d/1nMevQ0W7MZgJA1tJrJbNHIhTiHYHYUlO3IHXBs_usGE/edit?ts=5be2cd87#heading=h.1w7q6hj6vskz
15:40:21 <acozine> Once this content is ready, we will link to it from the Community index page via this line:
15:40:23 <acozine> "I’d like to participate in conversations about features and fixes. How do I review GitHub issues and pull requests?"
15:42:46 <samccann> looks comprehensive....I'll need to read it more closely, but in general +1 for the direction it's going
15:44:12 <Xaroth> Agreed, +1, very useful information
15:44:19 <gundalow> Cool, thanks
15:44:36 <acozine> gundalow: anything specific you'd like to call out?
15:44:54 <samccann> maybe once it's public, we can get those w/ twitter accounts etc to share the link, draw in some help?
15:45:05 <gundalow> Just any feedback on the "how to test" section
15:45:15 <gundalow> samccann: cool idea
15:45:31 <acozine> samccann: ++ for the social media win!
15:47:20 <gundalow> Fleshing out the how, what, why
15:47:52 <gundalow> I'm currently working in updating https://docs.ansible.com/ansible/devel/dev_guide/developing_locally.html
15:48:12 <gundalow> Help/ideas on the rest would be good
15:49:27 <acozine> gundalow: that page came out of a discussion with sdoran about helping people whose modules hadn't been merged into core
15:50:25 <acozine> the idea was to let people know that merging into core is optional, that there are other ways to use and distribute Ansible modules
15:51:40 <acozine> I agree that it's relevant to testing, and connecting the two topics will help people understand the context even better
15:52:21 <gundalow> ACK, thanks for the background
15:53:35 <acozine> Xaroth: can I pick your brains a bit about Sphinx themes, canonical URLs, etc?
15:53:44 <Xaroth> sure
15:53:47 <gundalow> Any other feedback on the Google Doc?
15:53:50 <Xaroth> you saw my pr?
15:54:02 <acozine> gundalow: sorry, I leapt too early
15:54:19 <gundalow> #topic Canonical URLs
15:54:48 <acozine> gundalow: I have a PR I'd like to get fixed and merged that is currently failing CI - maybe we could use it as an example?
15:55:04 <acozine> heh
15:55:58 <gundalow> Sure
15:56:06 <acozine> Xaroth: I saw you said that only one of the two themes we have will support a canonical URL reference
15:56:12 <acozine> how did you determine that?
15:56:25 <Xaroth> not will, more 'currently has'
15:56:56 <Xaroth> https://github.com/ansible/ansible/blob/devel/docs/docsite/_themes/sphinx_rtd_theme/layout.html#L37-L40
15:57:18 <Xaroth> that's the part in the current active theme (sphinx_rtd_theme) that checks if there's a theme option set for a canonical url, and if so, adds it
15:57:21 <acozine> ah, okay, that makes sense
15:57:37 <Xaroth> the srtd theme, does not have that currently configured
15:57:48 <acozine> gotcha
15:57:55 <Xaroth> but from what I can see, srtd was used up until 2.4, where 2.5 and beyond moved to sphinx_rtd_theme
15:58:01 <acozine> I really want to get rid of the duplication
15:58:18 <Xaroth> I don't see google indexing many 2.4 and below docs anymore
15:58:25 <acozine> thank goodness for that
15:58:28 <Xaroth> mainly because the main docs site only links to 2.5, 2.6 and latest
15:58:47 <Xaroth> so only changing sphinx_rtd_theme would 'fix' those three (granted backporting etc etc etc)
15:58:49 <acozine> we're making progress
15:59:18 <acozine> yeah, that also means we can get rid of the `srtd` theme entirely
15:59:19 <Xaroth> which is what https://github.com/ansible/ansible/pull/49190 does for devel, so it can be backported into 2.7, 2.6, and 2.5
15:59:59 <acozine> that's awesome
16:00:03 <Xaroth> Might need some checking I think, make sure there aren't any lingering references to srtd
16:00:21 <acozine> though I have some evidence that the `sphinx_rtd_theme` isn't actually being used
16:00:46 <acozine> see https://github.com/ansible/ansible/pull/47450 - I don't think it's the right fix, but it's part of the trail of evidence
16:01:20 <Xaroth> yeah, looks more like lingering references to srtd
16:01:30 <acozine> yep: https://github.com/ansible/ansible/pull/47450/commits/9d81cda4d34cbd3d0f925d07123a028a3d55e7e8
16:01:46 <acozine> where are we actually pointing to the newer theme?
16:01:58 <Xaroth> docs/docsite/rst/conf.py
16:02:23 <Xaroth> docs/docsite/rst/dev_guide/style_guide/conf.py  seems to point to .. both
16:02:56 <Xaroth> no, correction, only srtd
16:03:06 <Xaroth> but I'm not sure if that conf.py is actually used
16:03:16 <acozine> I'd like to get rid of that, too
16:03:21 <acozine> ah, here we go: https://github.com/ansible/ansible/blob/devel/docs/docsite/rst/conf.py#L127
16:03:37 <Xaroth> yes
16:03:50 <acozine> the duplication is making me crazy, and we're still making some changes to one theme, some to the other
16:05:11 <acozine> see https://github.com/ansible/ansible/tree/devel/docs/docsite/_themes - both themes have changes that are a month old
16:05:57 <samccann> could we sneak a README into the old one to say stop updating we are deprecating this?
16:06:14 <acozine> samccann: why not just nuke the old one?
16:06:15 <samccann> dunno if that would break anything, but a message 'somewhere obvious' might help stop the extra changes
16:06:38 <samccann> oh I'm fine w/ the nuke. I just wasn't sure we were at the point where we can... if we are... *zips lips*
16:06:57 <acozine> (once we've captured all the changes that have been made to it in the last year, that is . . . )
16:07:25 <acozine> samccann: oh, good - I thought you'd come up with a blocker of some kind
16:08:03 <samccann> yeah that's why I was thinking a readme done TODAY could stop anyone from starting another set of changes, while we merge anything into the theme we wanna keep
16:08:15 <acozine> I've been alternately nervous about it and determined to "damn the torpedos"
16:08:53 <acozine> that's a good idea
16:09:14 <samccann> damn those torpedos!!  (but watch for those icebergs...:-)
16:09:27 <acozine> heh
16:09:47 <acozine> Xaroth: are you up for expanding your PR to address some (or all) of these issues?
16:10:36 <Xaroth> Might be better to have a separate PR for that
16:10:42 <Xaroth> a "get rid of the srtd theme" PR
16:10:50 <acozine> okay
16:11:11 <samccann> yeah something we can back out quickly if we blow something up!  (those damn torpedos)
16:11:20 <acozine> BBOOOMMMM!
16:12:54 <samccann> heh
16:12:59 <acozine> Xaroth:  one more question - you said in a PR comment that make webdocs took forever to run
16:13:05 <acozine> do you know about how long?
16:13:13 <acozine> longer than without this change?
16:13:21 <Xaroth> the change didn't change the runtime
16:13:33 <acozine> gotcha - just the same slow build
16:13:54 <Xaroth> aye
16:14:05 <acozine> speeding it up is on my to-do list as well . . . suggestions welcome!
16:14:16 <Xaroth> it's just a very large amount of data that's being processed
16:14:32 <acozine> yes, possibly not in the most efficient way
16:15:38 <acozine> Xaroth: for changes like this one, you can run the build with `MODULES=none`, which speeds the process (though it also creates a bunch of spurious error messages)
16:15:58 <Xaroth> well yeah, but I wanted to make sure it actually generates the canonical on everything :0
16:16:22 <Xaroth> I checked with MODULES=none to make sure my assumption was correct, then started the slow build as I started the PR
16:16:27 <acozine> for posterity, so folks searching this log have a reference point: https://docs.ansible.com/ansible/devel/community/documentation_contributions.html#building-all-the-rst-pages
16:16:41 <acozine> Xaroth: excellent, that is definitely the best practice
16:17:15 <acozine> all right, I'm fired up for some sphinx-theme changes, thanks Xaroth
16:17:23 <acozine> #topic open floor
16:17:25 <Xaroth> My pleasure
16:17:40 <acozine> anybody have things to discuss?
16:17:44 <acozine> PRs to review?
16:18:05 <samccann> I have a general discussion but let's see if anyone pops in with PRs first
16:18:21 * acozine hums the Jeopardy theme song
16:18:33 <Xaroth> The only PR I had on my list got its own topic, so I have nothing
16:18:46 <acozine> BTW, I'll merge that after the meeting
16:19:57 <gundalow> Nothing else from me
16:19:58 <samccann> ok I'll start. we can pause if a PR pops in.
16:20:06 <acozine> samccann: go for it!
16:20:24 <samccann> i'm pondering how we handle the really old PRs in the docs backlog.  I see three categories:
16:20:33 <samccann> 1 - old and we can review/merge
16:20:52 <samccann> 2- old but needs rebase and/or revisions but the owner hasn't acted in ages
16:21:03 <samccann> 3 - old but also has code changes, so we can't 'nix' it on our own
16:21:36 <samccann> I'm wondering really what we can do for 2 and 3.  Is there a point where we say the owner hasn't reacted to request or rebase and we start closing out these?
16:21:49 <samccann> (i'm talking stuff 6 months to a year old)
16:22:29 <samccann> or alternately, do we review individually and decide we should take over the PR and fix/merge etc?
16:22:59 <acozine> my proposal: anything over a year old (which would be version <=2.4) we should assess for quality of the idea - is it something we *want* to merge/add?
16:23:40 <acozine> if the answer is yes, then we rebase/fix/merge; if the answer is no, we put one "warning" comment on it - if no response, we close it
16:23:43 <Xaroth> To be fair, if a PR remains open for >1 year without other people piping in (read: "I have this problem too", or "This fixes my issue"), then it probably amounts to a change that doesn't affect much... so if they then don't respond to a request to update their PR, I'd say close it but invite them to re-open it if/when they have the time to update i
16:23:43 <Xaroth> t.
16:24:30 <acozine> that's a fair perspective
16:24:47 <Xaroth> At some point the cost/benefit equation turns around
16:24:48 <samccann> ok how about the 6 months to a year range of PRs?
16:25:01 <Xaroth> where it costs more time from a maintainer to keep prodding people, than the change contributes
16:25:17 <acozine> maybe we can make this a priority for December - comment on all open docs PRs more than a year old, and have a "New Year's Cleaning" day just before or just after the Red Hat holiday shutdown
16:26:00 <acozine> samccann: good point - actually I'd say anything older than the release of 2.5 gets the same treatment as the oldest PRs
16:26:20 <gundalow> With my "Contributor Experience" hat on. I'm OK closing PRs that don't meet the cost:benefit, or are really old
16:26:27 <samccann> #info doc PRs a year or more older - we will review for importance, and either take ownership if deemed worth it, or query PR author to update. If no response, we will close with an invite to reopen when they feel they can address it
16:26:46 <gundalow> If there are old PRs with good content in we can pull that into a newer PR (or rebase theirs)
16:27:03 <gundalow> So I'd expect most of #1 & #2 to be merged
16:27:14 <samccann> #info apply the above to any doc PR older than 2.5
16:27:15 <acozine> 3/23/2018 was the first 2.5.0 release
16:27:22 <samccann> (am I doing that right btw??  meeting noob)
16:27:44 <samccann> #info anything older than 3/23/2018)
16:27:48 <gundalow> difficulty is #3 where it includes code. Could add a `label/candidate_to_close` then we can review with others
16:27:48 <Xaroth> yeah, so if it doesn't target 2.5 or later, it's bound to be >6 months old anyhow
16:28:00 <gundalow> samccann: you are doing it right
16:28:07 <samccann> thanks gundalow
16:28:29 <acozine> thanks samccann for focusing on the backlog - it needs pruning!
16:28:42 <samccann> yeah in general I struggle with doc PRs that are also code (regardless of age). Not sure what the right nag strategy is :-)
16:28:52 <acozine> so we can free our time and energy for forward-looking changes
16:29:24 <samccann> gundalow" is `candidate_to_close` an existing label?
16:29:34 <gundalow> nop, but it can be :)
16:29:54 * gundalow is happy to do a few hours in here reviewing PRs (or over BlueJeans)
16:30:33 <samccann> thanks gundalow!
16:31:20 <acozine> all right, our hour of documentation fun is done, DaWGs
16:31:29 <acozine> thanks everybody
16:31:36 <samccann> #action - create `candidate_to_close` or applicable label to mark old doc PRs that we can't close on our own because they have coding changes
16:32:13 <gundalow> #info https://github.com/ansible/ansible/labels/candidate_to_close
16:32:14 <gundalow> done
16:32:25 <acozine> thanks gundalow
16:32:38 <acozine> any other final items?
16:32:39 <gundalow> acozine: samccann feel free to add `candidate_to_close` to any PR or issue
16:32:47 <samccann> great, thanks!!
16:33:12 <acozine> #endmeeting