14:33:28 <samccann> #startmeeting Docs Working Group aka DaWGs
14:33:28 <zodbot> Meeting started Tue Sep 29 14:33:28 2020 UTC.
14:33:28 <zodbot> This meeting is logged and archived in a public location.
14:33:28 <zodbot> The chair is samccann. Information about MeetBot at http://wiki.debian.org/MeetBot.
14:33:28 <zodbot> Useful Commands: #action #agreed #halp #info #idea #link #topic.
14:33:28 <zodbot> The meeting name has been set to 'docs_working_group_aka_dawgs'
14:33:39 <samccann> #topic opening chatter
14:33:46 <samccann> Ok who's around to talk docs today?
14:35:36 <samccann> felixfontein gundalow abadger1999 andersson007_ ?
14:36:20 <felixfontein> hi!
14:36:22 <felixfontein> I'm partially around
14:36:37 <samccann> #chair felixfontein
14:36:37 <zodbot> Current chairs: felixfontein samccann
14:36:48 <samccann> you get furniture anyway :-)  Could be a quiet day
14:37:07 <felixfontein> thanks ;)
14:37:50 <gundalow> Hi
14:37:58 <samccann> ooo more furniture!
14:38:04 <samccann> #chair gundalow
14:38:04 <zodbot> Current chairs: felixfontein gundalow samccann
14:38:07 * gundalow sits
14:38:18 <samccann> today's agenda - https://github.com/ansible/community/issues/521#issuecomment-696842671
14:38:52 <samccann> To start with...
14:39:01 <samccann> #topic The Case of the Disappearing Redirects
14:39:41 <samccann> So yesterday, when someone pointed out a post on reddit, we discovered that the redirects went missing (the http redirects). So you couldn't go from 2.10 module to 2.9 module - you'd get a 404
14:40:10 <andersson007_> Hi, i am on foot as usual at this time, do can’t take part in
14:40:12 <samccann> #info republished the redirects last night. Not sure why they disappeared to begin with (http redirects for docs module pages)
14:40:32 <samccann> ok thanks andersson008_
14:40:41 <samccann> woopsie! heh... andersson007_
14:41:21 <samccann> So I think abadger was going to create a cron job to keep an eye on things to see if this failure happens again.
14:42:12 <samccann> we republished the devel docs and that didn't trigger it. And the nightly build went off per usual last night (again just devel) and that didn't trigger it.
14:42:16 <felixfontein> did the .htaccess files vanish?
14:42:23 <samccann> I believe so, yes
14:42:29 <gundalow> If there are URL we can test I can add some basic testing
14:43:01 <gundalow> to uptimerobot.com
14:43:14 <samccann> This is the url that works for latest - https://docs.ansible.com/ansible/latest/collections/community/general/online_user_facts_module.html#ansible-collections-community-general-online-user-facts-module
14:44:01 <felixfontein> i.e. https://docs.ansible.com/ansible/2.9/collections/community/general/online_user_facts_module.html should be a redirect, not a 404
14:44:20 <samccann> This url - https://docs.ansible.com/ansible/2.9/collections/community/general/online_user_facts_module.html#ansible-collections-community-general-online-user-facts-module  should trigger a redirect to https://docs.ansible.com/ansible/2.9/modules/online_user_facts_module.html#ansible-collections-community-general-online-user-facts-module
14:44:26 <felixfontein> and https://docs.ansible.com/ansible/latest/modules/online_user_facts_module.html should be a redirect and not a 404 either
14:45:21 <samccann> gundalow - once you have a test in place, let me know and I'll trigger a republish for 2.10.  That's about  the only thing we didn't try last night
14:47:06 <samccann> unless someone has other ideas on how to troubleshoot/detect if this happens again?  I'll move on in the agenda
14:48:53 <samccann> #topic redirecting module index pages
14:49:11 <felixfontein> how long does the republish take? (and do you have timestamped logs for it?)
14:49:23 <gundalow> (OK, I've added monitoring to make sure https://docs.ansible.com/ansible/latest/collections/community/general/online_user_facts_module.html exists and contains some text)
14:49:30 * gundalow -> afk
14:49:42 <samccann> The republish for 2.10 takes about 1.5 hours
14:50:23 <samccann> but I'll wait for abadger1999 to be online before I do it, incase it is the trigger.
14:50:34 <samccann> #action samccann to republish 2.10
14:51:11 <felixfontein> :+1:
14:51:30 <samccann> on module index pages - we've gotten two requests:
14:52:11 <samccann> #info requests to redirect the old module index pages to the collection index page - https://github.com/ansible/ansible/issues/71927
14:52:31 <samccann> #info also some folks miss  the ability to search on the all module index page to find a suitable module
14:53:28 <samccann> it's that 2nd item that needs a bit of thought. Folks used to be able to search all modules page based on words/terms they are looking for, which might not be the module name but would be in the module short description.  I can't think that we have anything like that now
14:55:36 <samccann> I'm wondering if there is a way to recreate it that wouldn't make the docs build take forever?
14:55:42 <felixfontein> I also did that in the past
14:56:18 <felixfontein> I guess we could create a huge page which links all plugins from all collections, with FQCNs in them (or create one per plugin category)
14:56:34 <samccann> it would need FQCN and the short description, yeah.
14:57:10 <samccann> one per plugin category might be the way to go as it's closest to what we used to have.
14:57:13 <felixfontein> like a combination of all per-collection indexes
14:57:18 <abadger1999> Morning
14:57:20 <samccann> yep
14:57:27 <samccann> hey!  more furniture!!!
14:57:27 <felixfontein> morning abadger1999!
14:57:33 <samccann> #chair abadger1999
14:57:33 <zodbot> Current chairs: abadger1999 felixfontein gundalow samccann
14:58:50 <abadger1999> I think a republish of 2.10 probably will kill the redirects but since we hadn't done that before we didn't test it yesterday
14:59:11 <abadger1999> I can check the rsync options in Jenkins to confirm
14:59:20 <samccann> so you think that's the culprit?
15:00:56 <abadger1999> I think it probably will break the redirects but if we didn't do it last time then we have another culprit too
15:01:50 <samccann> ok we'll test after this meeting then
15:03:00 <samccann> abadger1999 what do you think about the idea of recreating the 'all module index' page ^^  ? Doable without a lengthy delay in the docs builds?
15:05:20 <abadger1999> It's not natural but i think we have all the data in memory at one time so we could do it without much additional cost
15:06:10 <samccann> #info all module/plugin pages could be created w/o lengthening the docs build much
15:06:31 <samccann> #samccann - open an issue to track the idea and collect feedback on whether we want to do it or not
15:06:39 <abadger1999> Where to put the page and what to put on it at probably the biggest questions I'll need answered
15:07:29 <samccann> yeah that's why I figure I'll open an issue (on antsibull?) to decide if we want to do it and what to put on it. I expect they'll be kind of ugly pages. That's a lot of text when you get the FQCN and short description going on it.
15:07:44 <felixfontein> I'd say next to the collection index, i.e. same directory
15:08:05 <abadger1999> For end users, the raw size of the page will get unwieldy but they're asking for it so....
15:08:25 <samccann> yeah maybe we'd call it 'searchable plugin index' or something. With a note on the top that this is to search crtl-F style  or something
15:08:34 <samccann> <nods>
15:09:04 <felixfontein> btw, https://docs.ansible.com/ansible/latest/collections/community/general/index.html no longer (compared to 2.9 docs) groups modules by subdirectories
15:09:51 <abadger1999> Note, there's an index feature built into sphinx but i don't know if it would work well for this or if we'll want to make our own thing by templating something in rst ourselves
15:09:51 <samccann> yes, we don't really have an option for modules by category so to speak anymore
15:10:48 <samccann> I know someone mentioned missing the by category once... but I only heard that one once, vs the 404 problem and the all module index - those have been repeated a couple of times each at least.
15:10:50 <felixfontein> the main categories are collections now :)
15:10:52 <abadger1999> We were thinking at some point there should be some sort of metadata to tag plugins.  Then we could construct lists based on those tags
15:11:07 <samccann> based on galaxy tags?
15:11:41 <abadger1999> But there's a lot of questions to answer before doing that.. where are tags stored?  Who curates the tags?
15:12:04 <samccann> yep
15:12:33 <felixfontein> collection maintainers curate them, I guess
15:12:35 <abadger1999> Are Galaxy tags per collection?  If so, they won't work for community general as each plugin could have a different category
15:12:40 <felixfontein> in c.g the tags are subdirectories right now :)
15:12:46 <felixfontein> (same for c.n)
15:13:00 <felixfontein> abadger1999: galaxy tags are per collection
15:13:13 <abadger1999> <nod>
15:13:15 <felixfontein> they are specified per collection in galaxy.yml
15:13:51 <samccann> I'm assuming those subdirectories aren't in the info that antsibull gets when pulling down the collection docs?
15:14:07 <felixfontein> #action felixfontein add docs links to galaxy.yml in c.g, c.n which point to https://docs.ansible.com/ansible/latest/collections/community/*/
15:14:23 <felixfontein> samccann: the subdirectories are there
15:14:47 <felixfontein> they are more painful to get from ansible-doc though, since you need to follow symlinks yourself
15:15:04 <felixfontein> (in case that didn't change yet)
15:15:05 <samccann> ah.
15:15:37 <samccann> #action samccann to check the web analytics for how many visitors to the all module index page vs the module-by-category pages
15:15:50 <felixfontein> antsibull-changelog has some logic for determining them: https://github.com/ansible-community/antsibull-changelog/blob/main/antsibull_changelog/plugins.py#L103-L121
15:15:55 <samccann> I'd like to see how popular the others are before we chase down that possible solution
15:16:53 <samccann> #info antsibull-changelog has some logic for determining subdirs which act as categories for c.g and c.n : https://github.com/ansible-community/antsibull-changelog/blob/main/antsibull_changelog/plugins.py#L103-L121
15:17:00 <samccann> just so we don't forget :-)
15:17:45 <samccann> should we move on in the agenda?
15:18:43 <abadger1999> Yep
15:20:02 <samccann> #topic bitflipping the release
15:20:15 <samccann> This could be a quick topic as I forgot  the last status :-)
15:22:00 <samccann> anything we can cover on this one, or should I just move on?
15:23:55 <samccann> ok will move on.
15:24:14 <samccann> #topic ansible-test: allow version_added tests for collections
15:24:27 <samccann> #info https://github.com/ansible/ansible/pull/69291
15:24:49 <felixfontein> huh, is that still on the agenda?
15:24:51 <samccann> felixfontein: this one was in the 'post 2.10' agenda and I forgot why.  Is it something we should discuss?
15:24:54 <samccann> HAHAH yep
15:25:16 <felixfontein> it is essentially waiting for mattclay to implement per-collection config files for ansible-test
15:25:54 <felixfontein> I have another PR for added_version (and removal versions) though: https://github.com/ansible/ansible/pull/71679
15:26:14 <felixfontein> and one for fixing some missing collection names for removal versions in the docs: https://github.com/ansible/ansible/pull/71735
15:27:08 <felixfontein> the former one makes sure that no patch releases are mentioned as version_added, and no minor/patch releases as removal versions
15:27:27 <felixfontein> i.e. it screams at people who violate semver and document their violation :)
15:27:41 <samccann> hmm... so I couldn't add a module in a patch release, it has to be a minor release?
15:27:55 <felixfontein> yes
15:27:56 <samccann> But Ansible itself can add it in a patch release (e.g. 2.10.1)?
15:28:32 <felixfontein> ansible isn't using semver (and is excluded from this). and ansible doesn't add features in patch releases either. (it removes in "minor" versions though.)
15:29:05 <samccann> ??  I'm pretty sure Ansible 2.10.1 will have new modules
15:29:17 <samccann> unless I'm confused (which is no surprise :-)
15:29:24 <felixfontein> ah I thought you meant ansible-base
15:29:30 <felixfontein> that won't get new features in patch releases
15:29:37 <felixfontein> ansible itself does, but only from collections
15:29:56 <samccann> ah so collections and ansible-base don't add new things in patches, but Ansible the package will
15:30:05 <samccann> (from the collections)
15:30:13 <felixfontein> yes. but as opposed to collections, neither ansible nor ansible-base uses semver
15:30:25 <samccann> not at all confusing. ;-)
15:30:47 <felixfontein> collections are supposed to be using semver, which disallows new features in patch releases, and disallows removals (or breaking changes in general) in minor and patch releases
15:30:49 <samccann> So on your three PRs, will you take them to the core meeting to get some movement on them?
15:31:04 <felixfontein> yep, I already put them on th eagenda
15:31:15 <samccann> yeah semver makes sense. My brain's been rewired to semver so I'm forgetting how the other two work ;-)
15:31:33 <samccann> cool!
15:31:38 <felixfontein> I hope ansible and ansible-base will eventually switch to semver
15:31:45 <samccann> fingers crossed!
15:32:05 <felixfontein> that would mean having 3.0.0 though, and it sounds like some people don't want that (yet) :)
15:32:13 <samccann> Gonna do a quick open floor since we're at the 1 hr mark
15:32:18 <samccann> heh
15:32:23 <samccann> #topic Open Floor
15:32:41 <samccann> anyone have anything they want to bring up? favorite PRs? docs issues? general docs comments?
15:34:12 <samccann> ok gonna close this one out then. Thanks everyone!
15:34:37 <felixfontein> thanks samccann for moderating the meeting!
15:34:41 <samccann> #endmeeting