15:00:52 <samccann> #startmeeting Documentation Working Group aka DaWGs
15:00:52 <zodbot> Meeting started Tue Nov  1 15:00:52 2022 UTC.
15:00:52 <zodbot> This meeting is logged and archived in a public location.
15:00:52 <zodbot> The chair is samccann. Information about MeetBot at https://fedoraproject.org/wiki/Zodbot#Meeting_Functions.
15:00:52 <zodbot> Useful Commands: #action #agreed #halp #info #idea #link #topic.
15:00:52 <zodbot> The meeting name has been set to 'documentation_working_group_aka_dawgs'
15:01:02 <acozine> o/
15:01:02 <samccann> @room Meeting time! Who is here to talk the docs?
15:01:08 <samccann> #chair acozine
15:01:08 <zodbot> Current chairs: acozine samccann
15:01:18 <samccann> Raise your ascii hand (o/) to say hi or any other way you want to let us know you are here. And Welcome to any new folks!
15:01:22 <briantist> o/
15:01:28 <briantist> (but very distracted unfortunately)
15:01:33 <samccann> #chair briantist
15:01:33 <zodbot> Current chairs: acozine briantist samccann
15:01:52 <DonNaro[m]> o/
15:01:52 <samccann> we'll try not to poke you too often then :-)
15:01:58 <DonNaro[m]> hi
15:02:00 <samccann> #chair Don Naro
15:02:00 <zodbot> Current chairs: Don Naro acozine briantist samccann
15:02:02 <samccann> welcome welcome
15:02:40 <felixfontein> o/
15:02:56 <samccann> To any newcomers - again, welcome. We `chair` all attendees as a way of recognizing your time spent here. And it opens it up for people to add to the meeting minutes with commands like #info  or #link (to add a link)
15:03:02 <samccann> #chair felixfontein
15:03:02 <zodbot> Current chairs: Don Naro acozine briantist felixfontein samccann
15:03:46 <samccann> General run of the meeting - We go over action items, give docs updates.. maybe have a topic or two, and go over doctooling updates (all the fun stuff behind the scenes that get us docs.ansible.com!)
15:04:25 <samccann> Official agenda is https://github.com/ansible/community/issues/643#issuecomment-1290872984
15:04:41 <samccann> #topic Action Item updates
15:04:50 <samccann> #info Resolved -samcann to test https://github.com/ansible/ansible/pull/79071 and request backport to core 2.14
15:05:24 <samccann> (that got us to `antsibull-docs 1.7.1` for stable-2.14 and the last update for that branch... assuming nothing blows up)
15:05:25 * acozine BIAB, pouring fresh tea
15:05:38 <samccann> hhmmm fresh tea!  Better than my lukewarm decaf coffee
15:06:14 <samccann> #info  open  - samccann add a link to a separate intro to the agenda for welcome/here's what you need to know/ etc so newcomers can prepare.
15:06:22 <samccann> #info open - dnaro to create docs open office hrs for EMEA timezone and add to WG calendar
15:06:28 <felixfontein> samccann: does the ansible-core 2.14.0 docsite already exists?
15:06:31 <samccann> I think that's it for action item remindograms
15:06:47 <samccann> felixfontein: SSSSHHHHH!!!!!!!!
15:07:08 <samccann> shouldn't confess this in meeting minutes but at some point a month ago I must have pushed it to prod by mistake
15:07:17 <samccann> #topic Documentation updates
15:07:28 <samccann> #info ansible-core 2.14 rc2 staged at - http://docs.testing.ansible.com/ansible-core/2.14/
15:07:41 <samccann> So it's up todate on the test site as of a few minutes ago
15:07:46 <felixfontein> samccann: mainly asking to see whether there's a place where we can check out the results of that PR on stable-2.14 :)
15:08:12 <samccann> heh yeah use that url. I just pushed it to test before this meeting
15:08:55 <samccann> oh wait - that only has builtin collections. The build for Ansible 7 alpha is still running. Should be done before the end of this meeting
15:09:02 <samccann> #info Ansible 7 alpha 2 staged at http://docs.testing.ansible.com/ansible/7/index.html
15:09:18 <felixfontein> oh, I found a bug... https://docs.ansible.com/ansible-core/2.14/collections/ansible/builtin/git_module.html#parameter-force shows 'ansible-core 0.7', it should probably be 'Ansible 0.7'
15:09:25 <acozine> Are there specific things from the antsibull-docs upgrade we should check or be worried about?
15:10:07 <acozine> hm, that `ansible-core 0.7` thing is weird
15:10:08 <samccann> What is Ansible 0.7???
15:10:24 <acozine> Ancient history
15:10:25 <samccann> oooh ansible prior to 1?
15:10:41 <felixfontein> samccann: Ansible version 0.7 :) at least it's not on pypi...
15:10:52 <samccann> hmm... if we try another rev of antsibull-docs, Matt might reach through the ether and strangle me.
15:11:11 <acozine> we used to have a switch that suppressed those messages if they were older than a specific version
15:11:15 <samccann> Definitely won't happen before core releases next week. How important is this do folks think? (for stable-2.14 and ansible 7?)
15:11:22 <felixfontein> how bad is it if the docs build uses a slightly newer version than the docs sanity test?
15:11:30 <felixfontein> I mean, this change should not affect the outcome of that sanity test at all
15:11:47 <acozine> how hard is it to update the test?
15:11:56 <felixfontein> acozine: that's the strangle part ;)
15:12:08 <samccann> Well we've been out out of sync with the sanity test before (tho not on purpose.. that was just ignorance on our side)
15:12:20 <felixfontein> the annoying part is that the default CI container images need to be updated afterwards
15:12:28 <samccann> acozine: I don't honestly know if it's a 1 hr tast or a day=long grunt-fest
15:12:40 <samccann> s/tast/task/
15:13:21 <felixfontein> how about allowing newer x.y.Z versions if the antsibull-docs version in the tests is x.y.z? (i.e. newer bugfix releases in semantic versioning speak)
15:13:29 <felixfontein> *in the docs build
15:13:39 <samccann> I know matt had hoped that last regeneration of the CI container images would be his last in stable-2.14 (and it was done based on our request for antsibull-1.7.1)
15:14:05 <samccann> I can talk to matt about that (allowing dot releases to be out of sync w/ CI).
15:14:12 <felixfontein> that would allow us to fix such bugs without the need to create a new CI container image
15:14:52 <samccann> felixfontein: - was this bug introduced in 1.7.1 ?
15:14:57 <acozine> although in general being out of sync with testing makes me uneasy, this seems like a fairly small gap
15:14:57 <samccann> or did it already exist?
15:16:14 <felixfontein> samccann: it was introduced in 1.5.0 probably
15:16:46 <samccann> ok at least it wasn't a recent mistake so to speak.
15:16:56 <samccann> That said, I'd like to see how many of these are in the display.
15:17:14 <samccann> before we talk about getting CI and docs builds out of sync.
15:17:19 <felixfontein> basically https://github.com/ansible-community/antsibull-docs/pull/34/files#diff-0141d18b66e6538bb88c8183bf50786c6335d66be7389674e9d2434bd3a6593cR10-R11 ...
15:17:40 <acozine> if we restore that "suppress the oldest versions" thing, would that fix the display issue without having to fix the bug immediately?
15:17:53 <felixfontein> samccann: grep for `version_added: ['"]?0`
15:18:02 <acozine> because nobody cares that `force` was added in version 0.7
15:18:11 <samccann> ah it shows up at the top of the buildin module pages as well
15:18:22 <samccann> https://docs.ansible.com/ansible-core/2.14/collections/ansible/builtin/git_module.html#
15:18:41 <samccann> lemme try that again
15:19:12 <acozine> yeah, nobody cares that a module was added in 0.0.1
15:19:20 <felixfontein> there are 47 such versions in 2.13.5
15:19:21 <samccann> https://docs.ansible.com/ansible-core/devel/collections/ansible/builtin/add_host_module.html#ansible-collections-ansible-builtin-add-host-module
15:19:38 <samccann> so the problem already exists on probably every builtin module page
15:19:51 <acozine> yeah, those are the oldest ones
15:20:49 <felixfontein> 5 lookups, 1 connection plugin, 26 modules
15:20:51 <samccann> So I'd say we want two things:
15:20:51 <samccann> 1 - to make it so it says Ansible (unless it really is core aka 2.11 and later)
15:20:51 <samccann> 2 - remove the old old ones because it's just noise
15:21:15 <felixfontein> 1. is a bugfix, 2. is more like a feature :)
15:21:48 <samccann> #info we have a bug in antsibull-docs where it's mislabeling old stuff as `added in ansible-core 0.1 etc  - 5 lookups, 1 connection plugin and 26 modules
15:22:27 <samccann> yeah so I guess my thoughts - it's been there for some time, nobody noticed, is it worth 'fixing' in stable-2.14, or just fix in devel and add the new feature request?
15:22:54 <acozine> for 2., we had a solution built into the build
15:23:05 <acozine> I don't know when or how it disappeared
15:23:20 <samccann> somewhere around the collection move time I think
15:23:40 <samccann> but I could be wrong. I know they've been back for some time, but I have zero sense for how long ago they started showing up again
15:23:41 <felixfontein> acozine: probably for the collection move
15:23:45 <felixfontein> but shouldn't be that hard to re-add it
15:25:09 <samccann> ok so what does this mean - https://docs.ansible.com/ansible/latest/collections/ansible/builtin/git_module.html#parameter-force
15:25:31 <samccann> same module in latest and says 0.7 of ansible.builtin... that's also ..not really correct
15:25:49 <felixfontein> yeah, it's both not really helpful ;)
15:26:03 <samccann> though again, solved if we just stop showing anything older than x. But then we have to define what X is
15:26:08 <acozine> if we can suppress anything older than 2.10, I think that problem goes away
15:26:27 <samccann> the old one would block anything more than like... erm.. 5 releases old or something. But that's trickier for actual collections
15:26:29 <acozine> in the builtin collection
15:26:32 <felixfontein> I would probably set the cut-off to 2.x for x not too large, maybe 2.5?
15:26:54 <samccann> I think we were suppressing beyond 2.5 back when we had it working
15:27:14 <acozine> maybe it should match the versions in the version-switcher, suppressing anything that users can't easily find?
15:27:17 <felixfontein> also we maybe want a more dynamic cut-off version than a fixed one
15:27:37 <acozine> true
15:29:59 <samccann> so we used to update that suppression value every release. So more like an NEW-5 or something like that
15:30:58 <samccann> So I'm still inclined to say leave stable-2.14 as is because it's been this way for some time. And focus on a new feature/fix for devel. And we decide what values get suppressed (and if we want something similar for collections or not)
15:31:41 <acozine> that sounds good
15:31:48 <acozine> this probably bothers us more than it bothers users
15:32:02 <acozine> most users, anyway
15:32:10 <felixfontein> yes :)
15:32:34 <felixfontein> ok, so 1. a bugfix for `ansible-core 0.x`, 2. a new feature for supressing old ansible.builtin versions
15:32:42 <samccann> ok finally found it - TOO_OLD_TO_BE_NOTABLE = 2.4
15:32:46 <samccann> that's the last too old we had.
15:33:02 <samccann> because it stopped working in the collectin world (aka last supported was 2.9)
15:33:35 <samccann> and 3 - do we want something similar for collections? or too soon to be bothered with that yet?
15:34:09 <felixfontein> I guess it would be something that collections can configure themselves
15:34:25 <samccann> (for those following along, we've slipped into the doctools discussion and are getting rather deep into the weeds here. The gist of it is - we used to stop telling users something was added in a release when that release was very old).
15:34:44 <felixfontein> probably in https://github.com/ansible-collections/community.crypto/tree/main/docs/docsite ... maybe we need another file in there?
15:35:15 <samccann> random side question - I wonder when a particular collection version is 'no longer maintained' so to speak. I thought it was pretty much at the point when a new major version comes out?
15:35:29 <felixfontein> that depends a lot on the collection
15:35:46 <felixfontein> community.general, community.aws and amazon.aws for example support some of the older stable branches as well
15:35:58 <samccann> ah probably true. I'd imagine certified collections have some kind of policy for this already?
15:36:06 <felixfontein> same do community.crypto and community.docker... but likely not all collections do that
15:37:20 <samccann> well if we do decide to design a solution for collections, we should start with the certified collection folks to see if there's anything they are already doing to EOL older collections so to speak.
15:38:18 <acozine> sorry, folks, we are having an outage, I have to go
15:38:18 <samccann> #agreed we will keep `antsibull-docs` at 1.7.1 and fix/enhance how version added info is displayed in an update in `devel` only
15:38:24 <samccann> Does that sound accurate ^^ ?
15:38:30 <acozine> #unchair acozine
15:38:30 <zodbot> Current chairs: Don Naro briantist felixfontein samccann
15:38:32 <samccann> good luck!
15:38:47 <acozine> thanks!
15:38:56 <felixfontein> bye and good luck acozine!
15:39:13 <felixfontein> I'll still create a bugfix release (1.7.2) which fixes the 0.x versions
15:39:30 <felixfontein> whether this is used for the docs build or not is up to you
15:39:37 <samccann> yeah that sounds fine, thanks!
15:40:19 <samccann> #info felix will create a bugfix (1.7.2) for the `ansible-core 0.7` problem but we won't add to stable-2.14 unless there are complaints about it
15:40:31 <samccann> ^^ that way we can find the version that fixes it if we need to backport
15:40:54 <samccann> Anything else in doctools land before we get back to docs?
15:42:25 <felixfontein> not from my side
15:42:39 <samccann> coolness
15:42:50 <samccann> #topic Documentation updates
15:42:56 <samccann> #info Hactoberfest results - closed 36 issues, including boolean changes! Up from 26 issues last year.
15:43:16 <samccann> so was a busy time but worthwhile I think. Got some lowlying stuff fixed!
15:44:12 <samccann> #info archiving 2.3 docs ready for merging. Redirects (with most module redirects removed for pastebin size limits) at https://pastebin.com/Hs7dBVSu
15:44:24 <samccann> If anyone wants to take a look ^^
15:44:35 <samccann> it's truncated because the full set is too big, but will give you an idea of what's up.
15:44:51 <samccann> We'll likely merge the PR and publish it tomorrow so.. scream now if you see a problem! :-)
15:45:01 <samccann> The redirects are in place already on http://docs.testing.ansible.com/ansible/2.3/index.html. Were tested by hacking the url for docs.ansible.com/ansible/2.3/xxx into the testing url above.
15:45:31 <DonNaro[m]> testing by hacking is arguably the best testing
15:46:02 <felixfontein> :+1:
15:46:24 <samccann> #topic What's next?
15:46:36 <samccann> It's about that time of year to think about - what do we wanna do/focus on next in docs land
15:47:40 <DonNaro[m]> #info EMEA Office Hours survey. there's still only one response so far. what I'm thinking about doing is trying to ping the room on certain days to see who's around to talk docs, etc.
15:48:09 <DonNaro[m]> sorry I missed this earlier when you `info'ed` it samccann kind of distracted here with time change and kids in the house
15:48:22 <samccann> could also just ping and say 'open office time... bring your docs questions/ideas' and see if you get anything :-)
15:48:33 <samccann> hah. kids off this week?
15:48:39 <samccann> or just later in the day..doh!
15:49:13 <DonNaro[m]> yeah, that's kind of what I'm thinking about doing. pinging to see who's around on what days etc. but I'll do it next week when I'm not so distracted.
15:49:24 <DonNaro[m]> yeah, kids are off
15:49:34 <samccann> ok sounds good
15:50:01 <DonNaro[m]> not a whole lot else from me this week otherwise tbh
15:50:31 <samccann> So let's start thinking about what comes next for docs. I dunno if you were continuing with the user guide Don Naro ?
15:51:19 <DonNaro[m]> yes there's more to do there. tbh I'm kind of just thinking about the tooling side of things rather than the content.
15:53:34 <samccann> meanwhile, this is the issue we have to track highlevel docs stuffs - https://github.com/ansible-community/community-topics/issues/81
15:54:07 <samccann> #info our current list of docs priorities -https://github.com/ansible-community/community-topics/issues/81
15:55:34 <DonNaro[m]> I'd like to get more in the priorities about some of the publishing workflows as well. then opening all that up to the community.
15:55:39 <DonNaro[m]> also what about accessibility?
15:55:49 <DonNaro[m]> I realize I'm adding things to the list here
15:56:14 <samccann> yeah that list was created a year ago. Which is why I figure it's time to take another look at it etc
15:56:26 <samccann> so put your thoughts in the comments and we can revamp after week get feedback etc
15:58:06 <samccann> #topic Open Floor
15:58:24 <samccann> Anyone have anything docs-related they would like to talk about?
15:58:28 <samccann> now's the time!
15:59:29 <DonNaro[m]> I'd like to give a shout out to @jklech:matrix.org for his recent docs contributions! 🎉
15:59:52 <DonNaro[m]> not sure if he's around but I think it's worth celebrating
15:59:55 <samccann> woot!! yes thanks @jklech:matrix.org !!!
16:00:01 <samccann> yep for sure.
16:00:06 <jklech[m]> hi folks, and thanks
16:00:39 <jklech[m]> was pleasure working with you and contributing to Ansible upstream
16:02:27 <DonNaro[m]> I need to run but nice chatting
16:02:31 <DonNaro[m]> thanks samccann
16:03:19 <samccann> #endmeeting