14:31:42 <samccann> #startmeeting Docs Working Group aka DaWGs
14:31:42 <zodbot> Meeting started Tue Sep 22 14:31:42 2020 UTC.
14:31:42 <zodbot> This meeting is logged and archived in a public location.
14:31:42 <zodbot> The chair is samccann. Information about MeetBot at http://wiki.debian.org/MeetBot.
14:31:42 <zodbot> Useful Commands: #action #agreed #halp #info #idea #link #topic.
14:31:42 <zodbot> The meeting name has been set to 'docs_working_group_aka_dawgs'
14:31:47 <abadger1999> Good morning
14:31:55 <samccann> #topic opening chatter
14:32:00 <samccann> #chair abadger1999
14:32:00 <zodbot> Current chairs: abadger1999 samccann
14:32:12 <samccann> Happy Release Day morning!
14:32:19 <samccann> who else is around?
14:32:37 <acozine> o/
14:32:42 <samccann> #chair acozine
14:32:42 <zodbot> Current chairs: abadger1999 acozine samccann
14:32:43 <felixfontein> hi :)
14:33:06 <acozine> good morning, good afternoon, good evening!
14:33:33 <acozine> #chair felixfontein
14:33:33 <zodbot> Current chairs: abadger1999 acozine felixfontein samccann
14:33:45 <acozine> I'm still getting back up to speed
14:34:40 <abadger1999> :-)
14:34:59 <acozine> official agenda: https://github.com/ansible/community/issues/521#issuecomment-692906350
14:35:22 * gundalow waves
14:35:28 <acozine> #chair gundalow
14:35:28 <zodbot> Current chairs: abadger1999 acozine felixfontein gundalow samccann
14:35:33 * gundalow sits
14:36:27 <acozine> I was half-out yesterday for a family obligation - how is the release-prep looking?
14:36:50 <acozine> any last-minute blockers/surprises?
14:37:20 <gundalow> I believe we are all good, though abadger1999 can correct
14:37:40 <felixfontein> not that I know off. the bulitin FQCN buts I found are not important enough IMO
14:37:49 <acozine> the redirects have been up on the testing site for a while
14:38:00 <acozine> felixfontein: what's wrong with the builtin FQCNs?
14:38:05 <acozine> just some missing in the docs?
14:38:11 <acozine> or links broken?
14:39:03 <gundalow> abadger1999: felixfontein will be alpha & beta release sections on https://github.com/ansible/ansible/blob/devel/docs/docsite/rst/porting_guides/porting_guide_2.10.rst be combined into one when `ansible-2.10` is released?
14:40:55 <felixfontein> acozine: ansible.builtin.include_vars has some bugs, and free-form does not work for modules when prefixed with `ansible.builtin.` (https://github.com/ansible/ansible/issues/71818 https://github.com/ansible/ansible/issues/71817)
14:41:00 <felixfontein> gundalow: yes
14:41:14 <gundalow> though so, just wanted to check
14:41:21 <abadger1999> (no blockers... We're on schedule for release today)
14:42:24 <acozine> that is awesome news
14:42:36 <acozine> (the release on schedule, not the bugs)
14:42:36 <felixfontein> indeed!
14:42:48 <felixfontein> btw, when will the redirects get activated? for the release?
14:42:49 <gundalow> abadger1999: did we previously have something on where to report bugs?
14:43:14 <acozine> felixfontein: yes, the redirects will be published when we "flip the switch" so 2.10 becomes `latest`
14:43:29 <felixfontein> acozine: perfect :)
14:43:30 <acozine> it's a tricky business
14:43:31 <abadger1999> @gundalow For the release announcement?  Or somewhere else?
14:44:25 <gundalow> abadger1999: yup
14:44:44 <abadger1999> @gundalow We were pointing to this page: https://github.com/ansible/community/wiki/User-testing-of-ansible-2.10-pre-releases#bugs-in-modules-and-plugins
14:44:55 <abadger1999> That's for pre-release testing, though.
14:44:56 <gundalow> ah, missed that, thanks
14:45:11 <acozine> as far as I know, the only remaining changes to the 2.10 text docs is the porting guide consolidation
14:45:30 <acozine> heh, I forgot to change hte topic
14:45:36 <acozine> #topic 2.10 release
14:45:52 <samccann> #info merge redirect PR once 2.10 is released and 2.10 docs published
14:46:11 <abadger1999> @gundalow If we want that in the release announcement, we should probably rework it to not be for pre-releases first.  (Maybe it should eventually become a "reporting bugs" page on docs.ansible.com
14:46:19 <acozine> can we generate the consolidated porting guide now?
14:46:38 <samccann> we have an open PR to discuss/merge first for the boilerplate porting guide content
14:46:50 <samccann> #link https://github.com/ansible-community/antsibull/pull/191
14:46:53 <acozine> samccann: ah, excellent
14:47:26 <samccann> wanted your eyes on it before we merge.
14:47:32 <felixfontein> acozine: it will be generated with the release, which I guess can happen anytime soon (or when abadger1999 is ready :) )
14:48:40 <abadger1999> Yep, once that PR is merged, I'll generate the new tarball and then we can do a new docs build and then we'll be ready.
14:50:06 <acozine> samccann: I put three small suggestiins on that PR
14:50:15 <acozine> cat is again "heklpng" me type
14:50:38 <samccann> heh
14:50:42 <felixfontein> meow!
14:50:50 <acozine> she doesn't have "her spot" yet in the new house, so she is on my lap all day
14:51:13 <felixfontein> sounds like 50% super cute and 50% totally annoying
14:51:28 <acozine> yep
14:51:44 <samccann> heh
14:51:44 <acozine> the percentages change depending on what I am trying to do
14:51:50 <acozine> reading PRs is okay
14:51:55 <acozine> typing, not so mich
14:51:58 <acozine> er, much
14:52:58 <acozine> but for the mome nt she isn't chewng on cords, so that's a win
14:54:06 <abadger1999> Side benefit: being able to blame all typos on the cat ;-)
14:54:52 <felixfontein> +1
14:56:27 <acozine> heh, that's the joy of IRC
14:56:31 <abadger1999> acozine: For building docs this time, are we going to build once for testing and then a second time for the production site?
14:56:35 <acozine> you have no idea if i even have a cat
14:56:51 <abadger1999> Hah :-)
14:57:17 <acozine> abadger1999: my native caution says we should
14:57:25 <abadger1999> <nod> Cool.
14:57:39 <acozine> it will be slow,  but sure (I hope)
14:57:56 <acozine> no matter what we do, there will be some small disruptions
14:57:59 <samccann> yeah we need to merge the version switcher, backport it multiple times... then should put them on test site
14:58:21 <acozine> the redirects, the version-switcher changes, etc., can't all hit the site at the same moment
14:58:32 <samccann> erm?
14:58:37 <samccann> not following
14:58:42 <acozine> unless/until we go to a green/blue deployment system
14:58:44 <abadger1999> One thing about testing: the redirects needed webserver config to work properly.  The config for the production site config was merged this morning.  We'll want to test that the redirects for non-module plugins work on production after we push them out and talk to shanemcd/spredzy if they don't.
14:59:03 <acozine> samccann: I just mean that we can't have everything exactly right at the same moment
14:59:15 <acozine> if nothing else, we need to republish the older docs
14:59:45 <acozine> so for a while, 2.8 will be slightly "wrong"
15:00:21 <acozine> abadger1999: okay, sounds good
15:02:15 <acozine> https://github.com/ansible-community/antsibull/pull/191 is passing CI
15:02:50 <acozine> I'll merge that one
15:03:05 <samccann> woot
15:03:29 <felixfontein> +1
15:03:31 <samccann> the other question I had - the 2.10 release note draft mentions some bugs/limitations that I don't think are anywhere else.
15:04:00 <acozine> merged
15:04:01 <samccann> I haven't paid attention to see if that's normal, or if we've lost something because we can't manually edit the porting guide/changelogs ?  afaik nothing in docs links to the release note email
15:04:38 <samccann> https://etherpad.opendev.org/p/ansible-2.10-announcement
15:04:42 <abadger1999> samccann: I don't think we've really had Known ugs before.
15:04:44 <acozine> samccann: ghanks
15:04:54 <acozine> abadger1999: +1 for "known ugs"
15:05:00 <samccann> heh
15:05:06 <abadger1999> heh :-)
15:05:10 <samccann> nearly did a spittake w my tea
15:05:32 <abadger1999> felixfontein said that we could get it into the porting guide now, but I never got finished with getting those written up in there.
15:06:21 <samccann> ah so we have a 'bigger issue' so to speak  - there's no place for known bugs etc in our docs?
15:06:23 <felixfontein> you mean 'known bugs'? we can 'manually' insert them into the changelog, but I don't think they are part of the porting guide
15:06:33 <felixfontein> (but we can change that
15:07:31 <samccann> so perhaps a manual 'known bugs and caveats' at the top of the changelog that duplicates some of the stuff from the release note section?
15:08:11 <abadger1999> felixfontein: ah, okay.  m bad.
15:08:18 <acozine> the installation "bug" we've documented in the installation section, right?
15:08:26 <felixfontein> in the defalut order, known_issues comes last in the changelog
15:08:40 <felixfontein> (w.r.t to the other sections taken from collection changelogs)
15:09:01 <felixfontein> (that's defined in the default config of antsibull-changelog)
15:09:16 <felixfontein> we can add known_bugs to the porting guide
15:09:34 <acozine> the other two are "collections from the Ansible package won't show up in ansible-galaxy without help" and "some fortios modules don't automatically redirect" - is that everything?
15:09:42 <acozine> I think the porting guide is probably the best place
15:09:51 <felixfontein> the question would be where - right now its section order is 1) breaking changes, 2) major changes, 3) removed collections, 4) removed features, 5) deprecated features
15:10:01 <acozine> aminvakil: hi!
15:10:09 <samccann> the installation is noted yes, but in 'traditional documentation' that would also be highlighted in a traditional release note as well as it's a sizable change in behavior
15:10:12 <aminvakil> aconzie: hello!
15:10:16 <aminvakil> hello everyone!
15:10:21 <felixfontein> hi aminvakil!
15:10:23 <acozine> #chair aminvakil
15:10:23 <zodbot> Current chairs: abadger1999 acozine aminvakil felixfontein gundalow samccann
15:10:29 <abadger1999> felixfontein: is this how I should do it? https://gist.github.com/abadger/e64bd1b7ea24f02bb40ae9a95323502f
15:10:32 <acozine> we're talking about the 2.10 release
15:11:31 <felixfontein> abadger1999: I think so (use double backticks though please :) )
15:11:37 <felixfontein> I'll try it now
15:11:39 <abadger1999> felixfontein: Roger that.
15:11:59 <acozine> felixfontein: ah, gotcha - I would expect to see known bugs in or above the breaking changes section, I think
15:12:09 <acozine> samccann: is that the traditional approach?
15:12:31 <abadger1999> #info Draft release email: https://etherpad.opendev.org/p/ansible-2.10-announcement
15:12:54 <abadger1999> I'll copy the three known bugs from the release announcement to the changelog.yaml now.
15:12:55 <felixfontein> acozine: I'll create a PR for that then
15:13:16 <acozine> the other thing we could do is create GitHub issues and link to them, though that won't cover the installation thing, since it's not a "bug" we can ever fix
15:13:25 <acozine> felixfontein: awesome, thanks
15:13:27 <samccann> i lost track of which is being changed, the porting guide or the changelog
15:13:38 <acozine> porting guide
15:13:49 <felixfontein> the changelog already contains known_issues, but not the porting guide
15:14:03 <samccann> k
15:14:07 <acozine> the info will also show up in the changelog
15:14:25 <samccann> +1
15:14:56 <felixfontein> abadger1999: it works *almost* as expected, except that release_date is not automatically inserted anymore. you have to do that manually.
15:15:06 <felixfontein> (not that we're showing it anywhere yet, but it would be good  if it is in there :) )
15:15:13 <abadger1999> felixfontein: Okay :-)
15:15:25 <acozine> heh, well, that sounds like a manageable surprise
15:15:44 <acozine> Tas-sos: hi!
15:16:58 <felixfontein> here's a PR which includes known_issues into the porting guide: https://github.com/ansible-community/antsibull/pull/192
15:17:28 <felixfontein> tested it locally, it works as expected (I've included a generated .rst excerpt in a comment)
15:17:52 <felixfontein> also both porting guide and changelog collapsed to one entry (2.10.0) as expected :)
15:18:39 <samccann> ok so with that PR, it will bring all the known issues from the changelog into the porting guide, right?
15:19:01 <samccann> So then are the release note bugs/caveats already in the changelog somewhere, or is that also another PR we need to create/merge?
15:19:04 <acozine> hooray! thanks felixfontein
15:19:22 <samccann> #info need to merge https://github.com/ansible-community/antsibull/pull/192 to bring `known_issues` from changelog into porting guide
15:19:25 <acozine> samccann: I think abadger1999 is working on that end of things
15:19:55 <samccann> #info also need PR (from abadger??) that will create a manual changelog fragment for the bugs/caveats listed in the draft release note
15:20:03 <samccann> we so need to write up this process for the future
15:20:37 <acozine> felixfontein: the PR is failing Codecov
15:20:37 <samccann> #action samccann to draft the 'release process for docs' to document these steps for the next release...
15:21:00 <felixfontein> acozine: I think it's safe to ignore that
15:21:06 <abadger1999> Right now it's okay to fail codecov.
15:21:09 <samccann> Will the PRs/fixes are going on... is there anything else we need to do/prep for the 2.10 docs portion of the release?
15:21:27 <abadger1999> Eventually we'll have enough time/people so that we can make sure code coverage always increases but we're not there yet.
15:21:31 <acozine> samccann: I think you've got most of the rest of it prepped
15:21:51 <felixfontein> (the change doesn't increase or decrease coverage, so I don't think it should even fail codecov)
15:22:11 <acozine> yeag it's weird
15:22:21 <acozine> it passes one test and fails the other (/patch)
15:22:30 <abadger1999> #action abadger1999 to add the three known bugs to the changelog/porting guide
15:22:56 <acozine> I'm fine with merging it, but I'll need to learn more about codecov for the future
15:23:52 <abadger1999> My guess is it's failing because it's a percentage of code covered type thing and the new change somehow pushes the percentage covered down.
15:24:31 <felixfontein> if it doesn't count lines but characters or words, that's true :)
15:24:57 <acozine> heh, words certainly can be problematic; long words doubly so
15:25:29 <felixfontein> abadger1999: mind if I merge?
15:25:46 <abadger1999> felixfontein: Please do :-)
15:26:39 <acozine> I think I beat you to it
15:26:49 <felixfontein> heh, you did :)
15:26:52 <samccann> merge races++
15:26:52 <felixfontein> sorry, was talking to a coworker
15:27:04 <acozine> my old project had a large number of rules
15:27:14 <acozine> and one of them was "never merge your own PRs"
15:28:12 <samccann> it's a good rule to try and follow
15:28:14 <acozine> so I got in the habit
15:28:24 <felixfontein> true :)
15:28:27 <acozine> yes, it saved our bacon a few times
15:28:28 <samccann> y'all don't even WANT to know the messes I'd create if I merged my own...
15:28:30 * samccann shivers
15:28:34 <felixfontein> doesn't work in all situations but in general it's good
15:28:50 <felixfontein> samccann: I know the messes I've created, so I have an idea ;)
15:29:25 <acozine> abadger1999: are you writing up the additional known_issues entries?
15:30:46 <abadger1999> https://github.com/ansible-community/ansible-build-data/pull/32
15:31:07 <abadger1999> I haven't checked that I have the yaml formatting correct yet.  But you can check the content now :-)
15:32:25 <felixfontein> weren't there some more modules which don't work?
15:32:33 <felixfontein> and some fortios plugins?
15:33:22 <abadger1999> I'm not quite sure... here's relrod's list: https://gist.github.com/relrod/712af986db8318b8c6933608fe5a27af
15:33:25 <felixfontein> abadger1999: there's also `netbox_interface`, `azure_rm_acs` on the modules side
15:33:28 <acozine> abadger1999: you okay with wordsmithing? or have we entered the "gotta get it out, stop fussing" stage?
15:33:45 <felixfontein> abadger1999: looks like the plugins are ok now, except the action plugin - but its accompanying module is already listed
15:34:27 <abadger1999> acozine: wordsmithing is welcome.  You can wordsmith the release announcement too if you want.
15:34:45 * abadger1999 adds netbox_interface and azure_rm_acs
15:38:33 <samccann> #action samccann discuss with release managers on how to streamline/improve the release caveats in the future
15:38:48 <samccann> (aka how to make this less hard going forward :-)
15:41:30 <abadger1999> Hmmm...
15:41:46 <abadger1999> netbox_interface seems to exist and there's nothing like azure_rm_acs.
15:42:27 <felixfontein> both did exist in 2.9
15:42:51 <felixfontein> azure_rm_acs seems to have got lost, and no idea why netbox_interface isn't redirected (and what the correct destination would be)
15:46:25 <abadger1999> Maybe we've found a bug in ansible's collection loader
15:46:32 <acozine> heh
15:47:58 <acozine> abadger1999: if you want soething simpler, I put a review on https://github.com/ansible-community/ansible-build-data/pull/32#pullrequestreview-493595746
15:48:44 <abadger1999> felixfontein: Ah... I think that plugin might be broken and that's why it's not showing up.
15:49:52 <abadger1999> Maybe not.
15:49:54 <abadger1999> Ugh.
15:50:04 * abadger1999 conflicted on what he should do here.
15:51:00 <acozine> what are the options?
15:54:16 <abadger1999> I can leave those out of the known issues.
15:54:35 <abadger1999> I can put them in but simply say they're not available in 2.10.0.
15:54:52 <felixfontein> something is *really* strange with netbox_interface
15:55:04 <abadger1999> I know, right? ;-)
15:56:44 <samccann> I'd put them in and say they are not available in 2.10.0.  That at least warns users that there's a problem there.
15:57:45 <abadger1999> okay, python3 -c 'import ansible_collections.netbox.netbox.plugins.modules.netbox_interface'  => ImportError
15:57:51 <abadger1999> I bet that's why.
15:58:47 <abadger1999> Question for next release: What level of issue/bug will we want in future porting guides?
15:59:15 <samccann> #info Question for next release: What level of issue/bug will we want in future porting guides?
15:59:26 <abadger1999> (netbox_interface seems to == bug that breaks one module) (azure_rm_acs.... removed without deprecation period)?
16:00:22 <felixfontein> it's a bug, but in netbox.netbox
16:00:28 <felixfontein> their meta/runtime.yml has a screwed-up redirect
16:00:30 <samccann> we're at the 1.5 hr mark
16:00:56 <samccann> for now, I'd say list them as not available/functional in the changelog fragment
16:02:21 <samccann> felixfontein - I had your PR/issue about 'redirect inventory scripte link's in the meeting agenda but it's been merged/closed... was there anything else to cover there?
16:02:42 <samccann> ansible/ansible#71732 vs. ansible/ansible#71731 and ansible/ansible#71730
16:02:45 <acozine> yeah, we need to decide how much responsibility we will take for collection mistakes
16:03:13 <abadger1999> Mmm... another thing I guess... who's responsible for adding these?  Feels like it should be the collection owners themselves.
16:03:30 <felixfontein> samccann: it's merged and fixed
16:03:31 <samccann> yeah that's why I created an action item to discuss later
16:03:39 <samccann> felixfontein - thanks!
16:03:54 <felixfontein> https://github.com/ansible/ansible/pull/71862 there's a backport of the stable-2.9 PR to stable-2.8
16:03:58 <samccann> should we do a quick open floor in case anyone has hung around that log?
16:04:04 <samccann> s/log/long
16:04:38 <acozine> the more I think about it, the more I think we should only include a generic statement about "some collections-based modules may not automatically redirect from their 2.9.x names, please file issues with the relevant collections"
16:04:48 <acozine> instead of listing everything individually
16:04:52 <acozine> at least in the porting guide
16:05:15 <acozine> the other two known issues are ansible-wide, so they're good to go
16:05:20 <acozine> samccann: sure
16:05:25 <samccann> there were comments over in community last night about wanting the fortinet modules listed instead of a more generic statement as I recall
16:05:33 <acozine> ah, okay
16:05:40 <samccann> from our own jill (to specify wasn't an end user asking for it)
16:06:15 <acozine> all right
16:06:15 <samccann> But yes, we need to discuss in the future how much responsibility the release team takes for things that are broken and not in the changelog/porting guide
16:06:17 <samccann> meanwhile
16:06:24 <samccann> #topic open floor
16:06:35 <acozine> you beat me to it ;-)
16:06:42 <felixfontein> I'm afk now until in a couple of hours or so
16:06:47 <samccann> anyone have something else to bring up? Favorite PR? Least favorite docs page?
16:06:49 <felixfontein> have a great morning/day/evening :)
16:06:53 <acozine> felixfontein: see you later, thanks again
16:06:54 <samccann> thanks felixfontein !!
16:06:56 <felixfontein> and good luck with 2.10.0!
16:07:34 <acozine> thanks!
16:07:45 <abadger1999> felixfontein: see you later!
16:08:01 <samccann> ok gonna close out this official meeting  and we can keep coordinating the release after that...
16:08:08 <acozine> samccann: sounds good
16:08:13 <samccann> #endmeeting