16:00:30 <acozine> #startmeeting Docs Working Group (DaWGs) Supplemental meeting
16:00:30 <zodbot> Meeting started Thu Jan 28 16:00:30 2021 UTC.
16:00:30 <zodbot> This meeting is logged and archived in a public location.
16:00:30 <zodbot> The chair is acozine. Information about MeetBot at http://wiki.debian.org/MeetBot.
16:00:30 <zodbot> Useful Commands: #action #agreed #halp #info #idea #link #topic.
16:00:30 <zodbot> The meeting name has been set to 'docs_working_group_(dawgs)_supplemental_meeting'
16:00:34 <acozine> #topic opening chatter
16:00:39 <felixfontein> hey!
16:00:41 <acozine> #chair lmodemal abadger1999
16:00:41 <zodbot> Current chairs: abadger1999 acozine lmodemal
16:00:48 <acozine> hi felixfontein !
16:00:51 <acozine> #chair felixfontein
16:00:51 <zodbot> Current chairs: abadger1999 acozine felixfontein lmodemal
16:01:43 <acozine> who else is around? dericcrago dmsimard gundalow alongchamps briantist cyberpear madonius mrproper tadeboro tremble tributarian
16:01:53 * cyberpear waves
16:02:00 <acozine> anyone else want to discuss how we handle deprecations and re-routing in the docs?
16:02:06 <alongchamps> just lurking today, actually in some Ansible training :)
16:02:13 * dericcrago waves
16:02:14 <acozine> alongchamps: enjoy!
16:02:20 <acozine> #chair cyberpear dericcrago
16:02:20 <zodbot> Current chairs: abadger1999 acozine cyberpear dericcrago felixfontein lmodemal
16:02:59 <dmsimard> semi afk with dad ops but will respond :)
16:03:08 <acozine> #topic module docs routing & deprecations
16:03:16 <acozine> #info https://github.com/ansible-community/antsibull/pull/238
16:03:40 <felixfontein> this PR adds code which actually looks in meta/runtime.yml for collections (and ansible_builtin_runtime.yml for ansible-base/-core)
16:03:51 <acozine> dmsimard: sounds good, I'll make you furniture so you get pinged, but family comes first, so ignore us as needed
16:03:54 <acozine> #chair dmsimard
16:03:54 <zodbot> Current chairs: abadger1999 acozine cyberpear dericcrago dmsimard felixfontein lmodemal
16:04:02 <acozine> (and unchair yourself if you like)
16:04:03 <felixfontein> a) it adds stub pages for redirects
16:04:07 <felixfontein> b) it adds stub pages for tombstones
16:04:24 <felixfontein> c) it stops listing aliases of modules/plugins in the main plugin index
16:04:42 <felixfontein> (what it doesn't do right now is collecting these aliases so that a list of aliases is shown in the plugin docs itself)
16:04:49 <acozine> from a user perspective, how does this work? I'll give some example
16:04:53 <acozine> er, examples
16:05:15 <felixfontein> (/me is taking that time to switch rooms ;) )
16:06:11 <acozine> a stub page for a redirect means if I hit a 3.0 page for a module that existed in 2.10 but no longer exists in 3.0, I see a stub that says "this module no longer exists, go to <link>"?
16:06:20 <acozine> oh, wait, that would be a tombstone
16:06:37 <felixfontein> well, both
16:06:42 <acozine> okay, let me wrap my brain around this
16:06:55 <acozine> the old way was, deprecated modules were still listed in the collection index
16:07:10 <felixfontein> for example https://ansible.fontein.de/collections/community/general/docker_container_module.html is a redirect stub, since the module no longer exists in community.general
16:08:03 <felixfontein> and https://ansible.fontein.de/collections/community/general/docker_image_facts_module.html is a tombstone stub, since the module was actively removed from community.general (without a redirect)
16:08:30 <acozine> thanks
16:08:51 <acozine> what would happen to those pages if we didn't merge this PR?
16:09:20 <felixfontein> https://ansible.fontein.de/collections/community/crypto/acme_account_facts_module.html is a (deprecated) redirect inside a collection, and this redirected name is also no longer listed in https://docs.ansible.com/ansible/latest/collections/community/crypto/
16:09:38 <felixfontein> what would happen is that https://ansible.fontein.de/collections/community/general/docker_container_module.html and https://ansible.fontein.de/collections/community/general/docker_image_facts_module.html would be 404s
16:09:48 <felixfontein> and https://ansible.fontein.de/collections/community/crypto/acme_account_facts_module.html would be a copy of https://ansible.fontein.de/collections/community/crypto/acme_account_info_module.html
16:10:34 <felixfontein> (the latter is the case right now on the official docs site: see https://docs.ansible.com/ansible/latest/collections/community/crypto/acme_account_info_module.html and https://docs.ansible.com/ansible/latest/collections/community/crypto/acme_account_facts_module.html, both linked from https://docs.ansible.com/ansible/latest/collections/community/crypto/)
16:10:39 <acozine> or else we would put in a server-side redirect for the old page to the new one . . . which is less visible and less maintainable
16:11:28 <felixfontein> yes, but I think abadger1999 would have to extend/update his script for that
16:11:34 <felixfontein> and it won't help for tombstoned modules
16:11:38 <acozine> hm, the account_info page looks totally normal, what am I missing?
16:11:40 <felixfontein> (and tombstoned plugins in general)
16:11:50 <felixfontein> acozine: the account_info and account_facts pages are 100% identical
16:11:56 <felixfontein> on the current docs site
16:12:10 <felixfontein> because _facts is the deprecated name of _info
16:12:32 <acozine> ahhh, so we're currently building the docs for account_info and making it look like there's an actual module there, even though it's really just a symlink to account_facts?
16:12:43 <felixfontein> the other way around :)
16:12:48 <felixfontein> but yes
16:13:04 <felixfontein> it looks like there is a separate acme_account_facts, but there isn't - it's just a deprecated redirect to acme_account_info
16:13:29 <acozine> okay, basically we're pulling the docs for one module and building it to two different pages, one with the correct name, and one with the deprecated name, and the user has no way to tell which one she should be using
16:13:37 <felixfontein> with the PR a) acme_account_facts is no longer shown in the plugin list, and b) there is a stub page for the acme_account_facts docs which says that it is a deprecated redirect to acme_account_info
16:13:59 <felixfontein> acozine: the examples use the correct name ;) and the docs somewhere mention it as well I think
16:14:21 <felixfontein> (and you get a deprecation warning if you actually use the wrong one)
16:14:36 <acozine> yeah, we tried, but the docs still give a false sense of continuity
16:14:45 <felixfontein> yes
16:15:07 <felixfontein> that's why it's better to replace the wrong docs with a stub pointing to the correct new name, and (in this case) mentioning that this redirect is deprecated and will be removed eventually
16:15:29 <acozine> so this change seems sensible, low-maintenance, integrated with our existing docs infrastructure, and clear
16:15:33 <acozine> what are the downsides?
16:15:52 <abadger1999> I think having the aliases on the list pages has an important use case but they don't have to be separate entries in the list.  Use case: I have a playbook I inherited which uses community.general.rsync.  I do a text search on the list of all modules to find out about that.  I expect the text search to give me a link to the documentation.  Rather than having a separate entry it could be similar to :
16:15:52 <abadger1999> `community.general.synchronize (community.general.rsync, community.network.synchronize):  Copy a directory tree using rsync for efficiency`
16:16:21 <felixfontein> acozine: probably what abadger1999 said ^
16:16:40 <felixfontein> (though the ansible-2.9 docs have that same downside :) )
16:17:17 <felixfontein> but this is something that can be added/fixed to the PR (or as a subsequent PR)
16:17:24 <abadger1999> <nod> Yep.
16:17:29 <acozine> could we add that capability? of listing aliases so they are visible for CTRL-f searches but not listed as if they were "working modules"?
16:17:30 <abadger1999> I like the stub pages
16:17:53 <acozine> the only other downside I see is for SEO
16:17:58 <felixfontein> the redirect stub pages improved a lot based on feedback by gundalow :)
16:18:13 <acozine> as long as the page continues to exist, search engines will keep returning it
16:18:16 <acozine> but maybe that's a good thing
16:18:33 <felixfontein> acozine: we can definitely do that. the main question is where should the aliases be listed though. in the list of normal plugins (like now), or as an extra list?
16:18:38 <abadger1999> Do we want the redirect pages to nudge people towards using the actual name instead of the redirect name?
16:18:54 <acozine> stubs may help train users, and as abadger1999 says, it's nice for folks who inherit legacy playbooks to get some results when searching for old module names
16:19:11 <lmodemal> +1
16:19:47 <acozine> felixfontein: I like abadger1999's example, where the aliases are on the same line as the current plugin name
16:19:47 <felixfontein> abadger1999: what do you mean by downside for SEO? compared to HTTP redirects?
16:20:09 <acozine> yeah, HTTP redirects tell the search engines "this content now lives over THERE"
16:20:17 <acozine> stub pages don't
16:20:25 <felixfontein> ah. true.
16:20:31 <acozine> but stub pages are a lot easier to maintain
16:20:36 <acozine> and more visible
16:20:44 <felixfontein> does a HTML redirect help for that?
16:21:08 <acozine> I don't know
16:21:10 <acozine> maybe it does
16:21:43 <felixfontein> (not that we can simply add one, though, we'd probably need to trick sphinx into adding some for us)
16:22:00 * acozine looks again at the exampls
16:22:05 <acozine> grr, can't type today
16:22:32 <abadger1999> Thoe pages are templated, right?  sphinx does allow you to embed html.
16:22:44 <acozine> I'd probably change the wording on "redirect" stubs like https://ansible.fontein.de/collections/community/general/docker_container_module.html
16:22:57 <felixfontein> abadger1999: a HTML redirect needs to be in <head> though
16:23:07 <abadger1999> Ah. Hmmm...
16:23:18 <felixfontein> (and technically it's a refresh, and not very nice for users if the page suddenly goes somewhere else after x amount of time)
16:23:41 <felixfontein> maybe there's a way to indicate in <head> that "this should be a redirect to https://..."
16:23:55 <felixfontein> so that search engines can pick that up, while we can still show the stub to users
16:24:03 <felixfontein> but I've never looked into that part of HTML/SEO
16:24:25 <acozine> yeah, "this content lives THERE but we're keeping this page for legacy reasons" seems like an approach lots of people would want to use
16:25:29 <acozine> is this bit templated? `This redirect does not work with Ansible 2.9.`
16:25:40 * acozine looks at the code . . .
16:25:45 <felixfontein> acozine: yes it is
16:26:08 <felixfontein> for redirects that come from symlinks it says that it works with 2.9, and for redirects that come purely from meta/runtime.yml it says they won't work
16:26:17 <acozine> is there logic there for "does not work with <version-1>" or are the numbers hard-coded?
16:26:33 <felixfontein> 2.9 is hardcoded, since 2.9 is the only version of interest that does not support meta/runtime.yml :)
16:27:23 <felixfontein> (technically 2.8 could also be mentioned with the same drawback; I hope people stop using that one though and switch to 2.9)
16:27:52 <acozine> ah, so what "redirect" means here is "In the version you're looking at, you can use this_module name and it will call that_module"
16:28:09 <felixfontein> yes
16:28:22 <acozine> but in 2.9, it will still use this_module
16:28:45 <felixfontein> (which usually no longer exists and thus this will fail)
16:28:50 <felixfontein> (except if there's a symlink)
16:29:28 * acozine struggles with her incomplete narrative of The Lifecycle of a Module
16:30:11 <felixfontein> well, it also changed a lot for collections :)
16:30:48 <acozine> okay, for example, community.general.docker_container was only introduced in 2.10, and is deprecated in 3.0?
16:31:14 <felixfontein> it's not deprecated, but was moved to another collection (community.docker)
16:31:44 <acozine> so in 2.10 you'd use community.general.docker_container, in 3.0 you'd use community.docker.docker_container
16:32:01 <felixfontein> for Ansible 2.10 or Ansible 3 users it makes no difference, they can use the old name (until we remove it, if we ever do)
16:32:15 <felixfontein> in 3 you can also use community.general.docker_container, and it will work as before
16:32:33 <felixfontein> only if you try to use community.general.docker_container with community.general 2.0.0 with Ansible 2.9, then you get an error
16:33:01 <felixfontein> for Ansible 3, you *should* update your FQCN from community.general.docker_container to community.docker.docker_container though
16:33:10 <acozine> if you need that functionality and you're using 2.9, what would you use?
16:33:11 <felixfontein> it's not required, only recommended
16:33:14 <acozine> gotcha
16:33:28 <felixfontein> if you're actually using Ansible 2.9, you shouldn't look in the Ansible 2.10/3 docs ;)
16:33:32 <acozine> heh
16:33:34 <abadger1999> Do we want to subtly  push people from using the old name to using the new name?
16:33:35 <felixfontein> well if you're using 2.9, you need to change the FQCN
16:33:57 <acozine> yeah, I guess the reference to 2.9 seems more confusing than helpful to me
16:34:01 <abadger1999> It is a tad bit slower since ansible has to follow the redirects.... I don't know of  other drawbacks, though.
16:34:02 <felixfontein> if we have a redirect instead of a stub, they might not even notice that they ended up somewhere else
16:34:14 <acozine> heh, yep
16:34:16 <felixfontein> (for the docs page)
16:34:32 <acozine> abadger1999: slower to execute a playbook? slower to build the docs? both?
16:34:41 <felixfontein> acozine: slower to execute a playbook
16:34:41 <abadger1999> Slower to execute a playbook.
16:34:58 <felixfontein> though that aspect should be neglectible compared to the time it takes to actually run the module once it was found
16:35:06 <acozine> any performance hit on the docs build? (noticeable one, I mean)?
16:35:37 <felixfontein> the docs build will be a bit slower since the stub pages have to be built
16:35:42 <abadger1999> yep.  sending something over the wire is normally more expensive than anything else.
16:35:56 <felixfontein> also talking to the docker daemon is expensive, in the case of docker_container ;)
16:36:45 <felixfontein> on the other hand the stub pages are simple, so sphinx shouldn't take too much time building them
16:37:17 <abadger1999> yeah, I think the stub pages offer a large amount of value to end users for the amount of extra time in building them.
16:37:38 <abadger1999> *for the small amount of extra time
16:37:50 <felixfontein> for SEO, I think if we could include <link rel="canonical" href="https://url/to/redirect/destination"/> in <head> it would be great
16:38:02 <felixfontein> but I think it's ok if we cannot do it right now
16:38:08 <felixfontein> abadger1999: I agree
16:38:26 <felixfontein> especially the tombstones are a lot more useful than a 404 :)
16:38:27 <acozine> I have a lingering, nagging feeling that we rejected this approach before, but I cannot come up with any good reason for it now, and I see quite clearly the positive side of this PR
16:39:01 <acozine> it seems like good user experience
16:39:29 <felixfontein> we did the same for ansible 2.9: https://docs.ansible.com/ansible/2.9/modules/acme_account_facts_module.html
16:39:44 <felixfontein> (there were no tombstones though - at least I couldn't find any)
16:40:41 <acozine> well, I'm +1 on the approach
16:40:49 <acozine> I'll suggest some wordsmithing on the templates
16:40:54 <felixfontein> that would be great :)
16:41:18 <felixfontein> I guess abadger1999 also has comments on the code ;)
16:41:32 <acozine> good!
16:41:36 <abadger1999> Yep, I'll look at the code this week too.
16:41:42 <acozine> two heads are always better than one
16:41:49 <felixfontein> definitely!
16:42:09 <felixfontein> about listing aliases next to the plugin: is it ok to do it in an extra PR?
16:42:32 <felixfontein> I think that will keep this PR simpler
16:42:37 <acozine> yes, I think getting the base capability merged first is good
16:43:02 <acozine> then adding enhancements
16:43:13 <acozine> unless that complicates the code side?
16:43:41 <felixfontein> adding this enhancement requires to make some data structures more complicated there are not changed by the current PR, so I do not think so
16:43:44 <abadger1999> Yeah, I want it but it's fine to do afterwards.
16:43:55 <abadger1999> It makes it easier to review if they're two separate PRs :-)
16:43:57 <felixfontein> (or some extra data sturctures)
16:45:02 <acozine> as long as it's more like adding a porch rather than lifting the whole house on stilts to re-pour the foundation
16:45:23 * acozine has a crumbling garage foundation on her mind
16:45:41 <abadger1999> Aww :-(  I'm sorry to hear that
16:45:51 <felixfontein> doesn't sound great
16:46:06 <felixfontein> (and expensive)
16:46:09 <acozine> it's one of those things were it might be fine for another 20 years, or it might crumble to bits and fall down the hill
16:46:10 * abadger1999 bought a house with an addition built on a patio slab.... We had to tear down the addition eventually
16:46:23 <felixfontein> and foremost annoying :)
16:46:25 <acozine> s/were/where
16:46:53 <acozine> yeah, it's annoying
16:46:58 <acozine> but I digress . . .
16:47:31 <felixfontein> our neighbors were in the process of adding solar panels on their roof when the construction workers found out that the roof was rotten and could have given in any moment
16:47:39 <felixfontein> (now they have a new roof and solar panels...)
16:47:47 <lmodemal> oh wow
16:47:56 <felixfontein> just took summer+fall instead of just a few weeks in summer
16:48:04 <acozine> heh, well, that sounds like good timing
16:48:08 <felixfontein> yes
16:48:33 <felixfontein> pretty lucky, compared to what could have happened...
16:48:40 <acozine> yep
16:48:42 <acozine> so other than a code review and some wordsmithing, anything else we need to do for this PR?
16:48:44 <felixfontein> but then, maybe nothing would have happened for a long time...
16:48:49 <acozine> yeah, maybe . . .
16:49:04 <lmodemal> better safe than sorry
16:49:06 <felixfontein> acozine: I think not
16:49:09 <felixfontein> lmodemal: indeed!
16:49:10 <acozine> I've watched old barns fall down for years
16:49:24 <acozine> the trouble is, you don't get much warning when the final fall is coming
16:49:32 <lmodemal> scary
16:49:37 <felixfontein> and then you don't want to be too close
16:49:43 <acozine> it sags, and it sags, and it sags some more, and then one day it's a pile of sticks
16:50:05 <lmodemal> Hope no one has ever gotten hurt by those barns
16:50:28 <felixfontein> I'd be scared that kids or pets play in there when this happens
16:50:34 <acozine> they're usually on properties with nice new aluminum barns, but the farmer is too cheap or too lazy to tear the old one down
16:51:05 <lmodemal> ahh, okay. That's reassuring.
16:51:41 <acozine> no animals kept in there, though I guess pets and wildlife probably go in sometimes
16:52:07 <acozine> but we should close out the official meeting
16:52:14 <acozine> thanks felixfontein for the PR and for driving the discussion
16:52:26 <lmodemal> Good PR
16:52:32 <felixfontein> thanks everyone for your questions, feedback, and promises to review ;)
16:52:36 <felixfontein> thanks!
16:52:51 <acozine> and thanks abadger1999 cyberpear dericcrago dmsimard lmodemal for joining in
16:53:01 <lmodemal> Thanks everyone!
16:53:04 <acozine> #endmeeting