15:01:22 <acozine> #startmeeting Documentation Working Group aka DaWGs
15:01:22 <zodbot> Meeting started Tue Aug 24 15:01:22 2021 UTC.
15:01:22 <zodbot> This meeting is logged and archived in a public location.
15:01:22 <zodbot> The chair is acozine. Information about MeetBot at http://wiki.debian.org/MeetBot.
15:01:22 <zodbot> Useful Commands: #action #agreed #halp #info #idea #link #topic.
15:01:22 <zodbot> The meeting name has been set to 'documentation_working_group_aka_dawgs'
15:01:27 <briantist> o/
15:01:29 <acozine> #topic opening chatter
15:01:32 <abadger1999> morning
15:01:37 <acozine> #chair briantist abadger1999
15:01:37 <zodbot> Current chairs: abadger1999 acozine briantist
15:01:42 <acozine> morning/afternoon/evening
15:01:55 <acozine> I see felix is getting some healthy outdoor exercise
15:01:57 * gundalow waves
15:01:59 <acozine> who else is around?
15:02:02 <acozine> #chair gundalow
15:02:02 <zodbot> Current chairs: abadger1999 acozine briantist gundalow
15:02:08 * samccann waves late
15:02:21 <acozine> two whole minutes late!
15:02:23 <lmodemal[m]> I'm lurking today
15:02:31 <acozine> what is the world coming to?
15:02:39 <acozine> lmodemal[m]: do you want to be furniture?
15:02:41 <acozine> #chair samccann
15:02:42 <zodbot> Current chairs: abadger1999 acozine briantist gundalow samccann
15:02:43 <samccann> ooo ur on matrix lmodemal[m] ? you'll have to teach me later
15:03:01 <lmodemal[m]> No furniture today :/
15:03:11 <acozine> sounds good lmodemal[m]
15:03:29 <lmodemal[m]> Yup, it was a simple setup samccann
15:03:39 <lmodemal[m]> Thanks acozine
15:03:57 * dericcrago waves
15:04:00 <acozine> dmsimard: dericcrago cyberpear mrproper[m] tadeboro Xaroth you folks chatting docs today?
15:04:04 <acozine> #chair dericcrago
15:04:04 <zodbot> Current chairs: abadger1999 acozine briantist dericcrago gundalow samccann
15:05:18 <acozine> official agenda begins with https://github.com/ansible/community/issues/579#issuecomment-900480779
15:05:34 <tadeboro> I am in read-only mode today because dadops.
15:06:02 <acozine> tadeboro: sounds good, thanks for reading
15:06:46 <samccann> heh
15:06:54 <briantist> one question about this topic, it mentions "plugins" but it looks to me like it only applies to actions/tasks/modules, is that right?
15:07:13 <acozine> we are having thunderstorms here, and our network monitor is purple all over, so apologies if I start dropping packets, slowing down,  etc.
15:07:53 <acozine> briantist: are you talking about the attributes stuff?
15:08:09 <briantist> yeah
15:08:23 <acozine> cool, let's start there today
15:08:36 <acozine> #topic module/plugin attributes
15:09:02 <acozine> background: started with https://github.com/ansible/ansible/pull/73707
15:09:05 <samccann> felix may not be here, nor abadger... should we wait a bit before covering that?
15:09:28 <samccann> oh wait, abadger is here... nvm ;-)
15:09:30 <abadger1999> briantist: I am not certain but for the schema felix is adding it to a point where all plugins can use it.  My guess is that all plugins could use it but so far, only modules/action plugins do.
15:09:47 <acozine> expanded with https://github.com/ansible/ansible/pull/74331
15:10:11 <samccann> #info background: started with https://github.com/ansible/ansible/pull/73707
15:10:23 <samccann> #info expanded with https://github.com/ansible/ansible/pull/74331
15:10:50 <briantist> ok, I saw that PR too, but I'm mostly asking because I have a hard time seeing how most (maybe all) of those attribs would apply to a non-action plugin
15:11:01 <briantist> which is potentially fine, just looking to understand it
15:11:25 <abadger1999> briantist: <nod>  My guess there would be that there will be an entirely different set of attributes for other kinds of plugins.
15:11:32 <briantist> I see
15:11:44 <abadger1999> But i am not on the core team so I am not certain.
15:11:54 <abadger1999> (It's just my sense of how it could be used)
15:12:46 <acozine> yeah, I suspect it's mostly modules now, but it feels like the kind of functionality that could be expanded and elaborated upon in other contexts
15:12:57 <tadeboro> I got the feeling that attributes are some additional semi-standardized pieces of metadata that is most useful on modules right now.
15:13:19 <acozine> I can already hear a voice in my head saying, "Hey, could we use `attributes` for that?"
15:13:31 <samccann> heh
15:14:47 <acozine> output is currently broken, see https://github.com/ansible/ansible/issues/75164
15:14:47 <abadger1999> <nod> "Mark which lookup plugins can be used in with_* vs ones which just return a single value from external sources"    "Replace the exising marking for stdout callback plugins with an attribute"
15:15:49 <samccann> # docs output for modules that include these attributes is currently broken - https://github.com/ansible/ansible/issues/75164
15:16:07 <acozine> attributes could provide a lot of useful information
15:16:11 <abadger1999> <nod> I think that felixfontein's schema PR is pretty close.  But we do need to figure out how to add this information to the module pages too.
15:16:18 <acozine> yep, exactly
15:16:25 <abadger1999> list vs table?
15:16:50 <samccann> #info felixfontein has a schema PR to help with this but we need to decide how we want to add this info to the module pages too.
15:17:06 <abadger1999> have the description on each module page or just the name and have that link to a page with a description of all attributes?
15:17:22 <abadger1999> #info Schema PR: https://github.com/ansible-community/antsibull/pull/301
15:17:29 <samccann> thanks!
15:17:55 <samccann> so would the 'average' ansible user need a description? or would they understand 'check_mode' etc?
15:18:03 <felixfontein> o/
15:18:06 <acozine> if we look at https://docs.ansible.com/ansible/latest/collections/ansible/builtin/import_playbook_module.html#ansible-collections-ansible-builtin-import-playbook-module
15:18:10 <acozine> hey felixfontein
15:18:13 <acozine> #chair felixfontein
15:18:13 <zodbot> Current chairs: abadger1999 acozine briantist dericcrago felixfontein gundalow samccann
15:18:18 <felixfontein> sorry for being late
15:18:20 <acozine> how was your bike ride?
15:18:34 <acozine> no problem, welcome!
15:18:40 <felixfontein> good :) I had to wait a bit longer at the end though, otherwise I would have already been online for 10 minutes ;)
15:18:56 <samccann> cool fun!
15:19:41 <felixfontein> abadger1999: regarding the PR, probably the default status should be 'unknown' and not 'none'
15:20:02 <felixfontein> (if we have a default value for ''standardized attributes)
15:20:55 <tadeboro> I sometimes like to think that I am an advanced ansible user and I would still like to see at least a short description. Without it, things like turbo mean almost nothing.
15:21:15 <samccann> felixfontein - so if a module includes say two attributes, then the rest would be listed as unknown?  I'm assuming modules that don't include any attributes don't list anything at all?
15:21:21 <acozine> agreed about making the default status `unknown` - `none` can mean so many things
15:21:25 <abadger1999> felixfontein: Hmmm...
15:21:42 <felixfontein> samccann: it depends on whether a docs fragment the module uses already defines values or not
15:21:45 * acozine hears distant cat howl of distress, BRB
15:21:52 <abadger1999> felixfontein: Okay, why do you think that?
15:21:53 <samccann> heh woopsie on the cat
15:22:01 <felixfontein> the docs fragment bcoca added has default values for all attributes, and if someone extends it, they explicitly say which things they support
15:22:17 <felixfontein> but if they don't extend that fragment, setting everything not specified to 'none' is not a good idea
15:22:28 <samccann> ok based on tadeboro's comment, then I think the attribute, setting, and description are what we want.
15:22:48 <felixfontein> because then every plugin which doesn't extend that doc fragment (which is basically everything except a handful) supports no check mode, no diff mode, ... according to the generated docs
15:22:53 <felixfontein> which is wrong in many cases :)
15:23:25 * acozine is back at keyboard
15:23:34 <abadger1999> ah.
15:23:48 <felixfontein> I wonder whether we should only show the standardized attributes that have been explicitly specified, and show them with our own description (to make sure there's always the same description, and that nobody changes it to some other random text)
15:24:28 <felixfontein> for example, right now someone could abuse the diff_mode attribute to mean something completely different
15:24:57 <samccann> +1 for same description in the docs
15:25:04 <felixfontein> also for all collections that support ansible-core < 2.12, they cannot use that docs fragment, so they have to have their own descriptions everywhere, which will result in a large amount of different texts for the same attributes
15:25:23 <samccann> and I'd also not want these showing up unless they are set. A long list of uknown/none could get annoying
15:25:29 <abadger1999> felixfontein: One thought about check_mode.... if check_mode is unknown... would we want to link to have the module documentation show check_mode?
15:26:00 <acozine> felixfontein: can we generate an error that would at least make the publication pipeline break noisily?
15:26:31 <felixfontein> abadger1999: I'm not sure. not showing check mode will confuse some users; showing it as 'unknown' will confuse others (and make the docs of all plugins confusing that don't use attributes yet)
15:26:50 <abadger1999> We could think of it as opt-in-to-new-feature (ie, check_mode would have to be documented inside the description until they added the attribute) but in that case, we might as well default to none?
15:26:56 <felixfontein> acozine: that would mean that if someone fixes a typo in the standard docs fragment, or something like that, that suddenly 1000s of plugins report errors
15:27:04 <samccann> just tossin it out there - could we backport just the docs fragment all the way to say 2.9 so solve that specific collection problem?
15:27:52 <felixfontein> samccann: that would definitely help (it would have to be `options: {}` for all older versions to not raise an error), but it would ensure that the plugins only work with versions of these that include this docs fragment
15:28:20 <acozine> felixfontein: true, I was thinking of the scenario where we only allow standard attributes - what happens when someone adds a new one? would we wait for a user to report the docs breakage (which is what happened before)?
15:28:31 <felixfontein> which would mean that c.g suddenly needs ansible >=2.9.25,<2.10, or >=2.10.15,<2.11, or >=2.11.9
15:28:35 <felixfontein> (picked some random numbers :) )
15:28:37 <abadger1999> felixfontein: Could another collection provide that doc_fragment?
15:28:57 <abadger1999> something new and small like ansible.compat212
15:29:11 <felixfontein> abadger1999: that could be done, but adding a dependency is a breaking change, so it requires new major versions. and it is a dependency, and most collections try to avoid these :)
15:29:39 <abadger1999> and the ansible package could carry it until ansible-core-2.12 is the oldest version of core that is still supported.
15:29:42 <abadger1999> <nod>
15:30:27 <samccann> #info all collections that support ansible-core < 2.12  cannot use the common  atrributes docs fragment, so they have to have their own descriptions everywhere, which will result in a large amount of different texts for the same attributes. Not easy to solve this.
15:30:38 <felixfontein> abadger1999: it would have to carry it a lot longer, namely until all collections in it dropped that dependency
15:31:35 <felixfontein> (I guess it will have gotten new compatibility stuff that everyone uses by that point, so it will never get dropped :) )
15:31:57 <samccann> ok so if we backport the fragment, then a whole bunch of collections then have to specify very specific versions of 2.9, 2.10, etc that they are compatible with.  If we add a tiny collection, then a whole bunch of collections have a new dependency they don't like.
15:32:18 <abadger1999> felixfontein: <nod>-ish.... We could tell people to switch away from it by X release or their collection will be dropped from the ansible package.
15:32:19 <felixfontein> yes...
15:32:35 <samccann> #info if we backport the fragment, then a whole bunch of collections then have to specify very specific versions of 2.9, 2.10, etc that they are compatible with.  If we add a tiny collection, then a whole bunch of collections have a new dependency they don't like.
15:32:58 <abadger1999> felixfontein: I was thinking the collection would only have compat things that showed up in 2.12.  If other things show up in ansible-core-2.15, then that would be a different collection
15:33:08 <samccann> ok so for this mini collection, it's only needed by collections that opt in to use the attributes? or does everyone need it?
15:33:24 <abadger1999> only those that opt in to use the attributes.
15:33:28 <felixfontein> abadger1999: some collections might not want to drop 2.9 compatibility for a looong time
15:33:39 <abadger1999> <nod> This is true.
15:33:45 <felixfontein> there are still people who don't want to put their stuff into a collection because they want to support 2.7 or something like that
15:34:17 <samccann> ok but there is always going to be a cost for staying compatible with 2.9.. and one of those costs could be either don't use the new fancy stuff (attributes) or add a compat collection dependency
15:35:10 <felixfontein> which probably means that attributes will be even less adopted :)
15:36:02 <acozine> couldn't it work the other way? instead of "our collection requires >=2.9.15" could they do "Ansible 2.9 required my.collection <2.0, >=1.23"?
15:36:40 <abadger1999> felixfontein: It shouldn't be uch work to maintain an ansible.compat212 collection so it's probably mostly a question of whether we want to push people off of 2.12 and earlier at some point. (So maybe steering committee would vote on when to drop that collection from the ansible tarball and force collections to port or be removed)
15:36:45 <felixfontein> if there would be a possibility to declare all standard attributes which doesn't use docs fragments, that would probably be the best solution
15:36:47 <briantist> not that this adds anything to the discussion but it is quite annoying that 2.9 is an "LTS" release that for many reasons is hard to drop support for (because so many people still need it), but it doesn't get backports of important things /rant
15:38:08 <samccann> https://www.irccloud.com/pastebin/w5SvVDOx/
15:38:16 <acozine> briantist: are you thinking of specific things that haven't been backported to 2.9?
15:38:21 <samccann> heh that's what I get for being longwinded
15:38:47 <samccann> felixfontein: how would #4 work above?
15:38:51 <felixfontein> brb canging train
15:39:16 <acozine> bicycles AND trains, my goodness
15:39:23 <abadger1999> I think 4 would probably need code adjustments inside of ansible-core
15:39:25 <samccann> cyb-clock-clone sez we are 40 min into the meeting and the current  topic
15:40:00 <briantist> acozine: it's probably best not to derail further, sorry 😅
15:40:08 <acozine> briantist: heh, gotcha
15:47:57 <samccann> heheh
15:56:40 <abadger1999> Congratulations acozine !
15:56:40 <acozine> mmm, cake!
15:56:40 <felixfontein> abadger1999: having a ansible.compatibility collection (that can be used for other compatibility things as well) might also be a good idea, it could also provide some more features that right now are only available in newer Ansible versions - it might create new challenges with versioning though
15:56:40 <abadger1999> felixfontein: <nod>
15:56:40 <felixfontein> ok I'm at my destination very soon, so I'll be off for a couple of hours
15:56:41 <acozine> we're nearing the end of the hour
15:56:41 <felixfontein> (and my connectivity sucks right now anyway ;) )
15:56:41 <acozine> heh
15:56:41 <felixfontein> thanks everyone and until later!
15:56:41 <acozine> felixfontein: it's probably better than mine right now
15:56:41 <acozine> bye felixfontein
15:56:41 <acozine> and thanks!
15:56:41 <samccann> #action samccann add deciding how the attributes should look like in the docs to next week's agenda
15:56:41 <acozine> heh
15:56:41 <felixfontein> acozine: I'm sometimes losing connection for 10-20 seconds inbetween, and mosh is showing a lot of underscores the whole time
15:56:41 <samccann> by felixfontein !!
15:56:41 <acozine> #topic open floor
15:56:41 <tadeboro> Congrats, acozine!
15:56:41 <acozine> thanks!
15:56:41 <abadger1999> bye felixfontein !
15:56:41 <samccann> I have one small thing/request for the open floor, but will wait to see of others have something first
15:56:41 <briantist> I'll throw out another call for any collection maintainers who are interested in having an automated docs build on PRs to let me know, so we can work together directly
15:56:41 <briantist> it'll help pull out which elements of what I'm doing can be shared more widely, be added to the collection template, etc.
15:57:00 <acozine> someone in the dim and distant past apparently set the search engine to prioritize "all text" instead of "page titles"
15:57:04 * gwmngilfen-work arrives v.late
15:57:09 <abadger1999> Yay!
15:57:19 <acozine> which is kind of like saying "no prioritization at all"
15:57:24 <samccann> yep
15:59:17 <tadeboro> "If everything is urgent, nothings is" kind of deal ;)
15:59:32 <acozine> exactly
16:00:10 <acozine> we've also done some work on improving the titles since the dim and distant past; with luck the two changes will reinforce each other
16:01:17 <samccann> yeah that's why I figure we may need some specific examples of what's not working to see if it's the search engine, or how we have to docs structured etc
16:01:55 <acozine> samccann: do you want a social media blitz?
16:02:04 <acozine> I bet gundalow could make that happen
16:02:12 <samccann> well hoping folks here could start playing first
16:02:15 <acozine> heh
16:02:18 <acozine> sounds good
16:02:23 <acozine> woopsie, two minutes over
16:02:29 <samccann> I can always post in reddit etc, but figure let's get some friendly feedback first ;-)
16:02:47 <gundalow> Happy to help
16:03:01 <acozine> heh
16:03:12 <gwmngilfen-work> acozine: Carol Chen is your person for such a blitz :P
16:04:04 <acozine> I take samccann's point about maybe letting friendly viewpoints help us for a while, before we open ourselves up to the full onslaught
16:04:25 <acozine> all right, keep your eyes on this space for more about `attributes`
16:04:31 <acozine> chat welcome any time
16:04:44 <acozine> thanks abadger1999 briantist dericcrago felixfontein gundalow gwmngilfen-work samccann tadeboro
16:04:49 <acozine> see you next week!
16:04:53 <briantist> thanks!
16:04:59 <acozine> #endmeeting