15:00:34 <acozine> #startmeeting Documentation Working Group aka DaWGs
15:00:34 <zodbot> Meeting started Tue May 18 15:00:34 2021 UTC.
15:00:34 <zodbot> This meeting is logged and archived in a public location.
15:00:34 <zodbot> The chair is acozine. Information about MeetBot at http://wiki.debian.org/MeetBot.
15:00:34 <zodbot> Useful Commands: #action #agreed #halp #info #idea #link #topic.
15:00:34 <zodbot> The meeting name has been set to 'documentation_working_group_aka_dawgs'
15:00:43 <acozine> #topic opening chatter
15:00:46 <acozine> who's around?
15:01:15 <acozine> official agenda begins with https://github.com/ansible/community/issues/579#issuecomment-838959047 and continues with the comment below
15:01:26 <lmodemal> Hello!
15:01:30 <acozine> #chair lmodemal
15:01:30 <zodbot> Current chairs: acozine lmodemal
15:01:34 <acozine> hi lmodemal!
15:01:34 <tadeboro> o/
15:01:37 <acozine> #chair tadeboro
15:01:37 <zodbot> Current chairs: acozine lmodemal tadeboro
15:01:42 <acozine> welcome tadeboro
15:01:59 <acozine> abadger1999: is on carpool duty; he may join us later
15:02:37 <samccann> o/
15:02:38 <lmodemal> carpool duty, whooooo! Fun w/the kiddos :)
15:02:47 <acozine> bcoca: dericcrago dmsimard gundalow aminvakil briantist cyberpear felixfontein jmn kindlehl madonius tremble you folks talking docs today?
15:03:01 <acozine> if i didn't list your name, but you are reading the chat, here's how our meetings work:
15:03:06 <acozine> everyone is welcome
15:03:34 * dericcrago waves
15:03:38 <acozine> you can be a "chair" (also known as "becoming furniture") if you wave
15:03:57 <acozine> becoming furniture lets you vote (if we have anything to vote on)
15:04:00 <acozine> #chair dericcrago
15:04:00 <zodbot> Current chairs: acozine dericcrago lmodemal tadeboro
15:05:01 <acozine> we usually cover 1-3 main topics per meeting
15:05:17 <felixfontein> oh hi!
15:05:21 <acozine> and always have an "open floor" at the end where anyone and everyone can bring up topics
15:05:24 <acozine> #chair felixfontein
15:05:24 <zodbot> Current chairs: acozine dericcrago felixfontein lmodemal tadeboro
15:05:28 <felixfontein> completely forgot it's tuesday afternoon's docs meeting!
15:05:32 <acozine> hi felixfontein!
15:05:51 <felixfontein> hi acozine and all others :)
15:05:52 * acozine sings 'Summertime, and the livin' is easy . . . "
15:06:47 <gundalow> acozine: In another meeting
15:06:49 <acozine> we've got a big agenda today
15:06:54 <acozine> gundalow: we'll miss you
15:06:56 * samccann wonders what special tea acozine is drinking this am
15:06:59 <acozine> heh
15:07:17 <acozine> it's some kind of blend today . . . to match our blend of topics :-)
15:07:48 <acozine> okay, taking things out of order
15:08:15 <acozine> #topic version-specific links in docs and PR 74245
15:08:21 <felixfontein> ah, that one...
15:08:42 <acozine> #info see https://github.com/ansible/ansible/issues/74688 for a quick summary of some aspects of this issue
15:10:21 <acozine> to recap: PR 74245 made command-line output of `ansible-doc` version-sensitive - in other words, links to the docs point to the docs for the version of Ansible you have installed - but it broke some other aspects of the docs ecosystem
15:10:55 <felixfontein> it basically broke the docsite
15:11:05 <felixfontein> (or, well, a small part of it :) )
15:11:35 <samccann> yeah so I think if we focus on the underlying question - is it better to leave the PRs merged on devel because it fixes more than it breaks? or is it better to revert both because it BREAKS more than it fixes?
15:12:15 <bcoca> acozine: 74245 did not berak docsite, that code ONLY aplpies to tty output
15:12:27 <bcoca> docsite was alredy broken for diff reasons
15:13:12 <acozine> bcoca: you are correct, the thing that broke the docsite is formatting the links in modules and other content to work with the way the PR implements the version sensitivity
15:13:17 <samccann> bcoca - this is why I want to focus on what it breaks and what it fixes and decide which is better.
15:13:35 <samccann> acozine - sorry I can't really parse that sentence
15:13:37 <felixfontein> bcoca: the modifications to the module docs broke the docsite
15:13:40 <bcoca> samccann it fixes 2.11 links in tty since the ansible/2.11 docsite got deleted
15:14:21 <bcoca> felixfontein: docsite was broken due to it being relative link, that was awlays the case
15:14:32 <abadger1999> It added new breakage to the docsite because the relative link specification is wrong
15:14:34 <acozine> with the PR in place, any link in module docs either works with the docsite, or works with `ansible-doc`, but not both
15:14:43 <felixfontein> bcoca: the link was made relative in your PR: https://github.com/ansible/ansible/pull/74245/files#diff-acdcd084ce50e20e291a2117f0052a4d50f2a14fff36fde389185d0af683f914R34
15:14:53 <samccann> acozine: and without the PR?
15:14:58 <bcoca> acozine: but that pr does not change module links
15:15:23 <bcoca> M is untouched, ONLY affects L() and then only relative that dont start by . or..
15:15:30 <bcoca> and again, just for tty output
15:15:52 <acozine> bcoca: what about https://github.com/ansible/ansible/pull/74245/files?file-filters%5B%5D=.py#diff-acdcd084ce50e20e291a2117f0052a4d50f2a14fff36fde389185d0af683f914L34?
15:15:58 <abadger1999> Relative links work correctly when specified correctly in the plugin docs
15:16:45 <felixfontein> now there are two different interpretations of 'relative link'. the one used in the web, which is also used by antsibull-doc, and the one used by ansible-doc
15:16:46 <bcoca> acozine: that was the optional part, that change the specific link from being 'wrongish' to being relative so it would cary with the specific version
15:16:54 <abadger1999> (Excluding . and .. prefixes is yet another reason this pr is wrong)
15:17:17 <samccann> okay both diff links above talk about three specific links in three modules that are now broken
15:17:30 <samccann> what about the other 4k modules? What is now broken and what is now fixed?
15:17:41 <bcoca> tehre are more now broken,  but mostly errors in 2.11 that link to docsite
15:18:17 <bcoca> samccann: from my check most modules used M and not L for relative links, only L relative i found was 'dig' and its ../plugins/list.html, which is also broken, but nothing to do with this change
15:18:37 <acozine> I like the idea of giving users version-specific doc links, both at the command line and on the docsite; I'd like to find a way to implement it that works in both situations, and works for versions of `Ansible` not just for versions of `ansible-core`, especially since a lot of these links are in collections now
15:18:58 <bcoca> acozine:  you jhave more than 2 situations, that is what i was trying to explain last week
15:19:05 <felixfontein> M() cannot have relative links
15:19:21 <felixfontein> (if someone puts relative links in there, it's a wrong use)
15:19:21 <bcoca> felixfontein: for tty, that function just removes em
15:19:44 <felixfontein> bcoca: M() is not handled by your PR
15:19:48 <bcoca> please stop merging the tty output with how the site is constructed
15:19:51 <samccann> it would help me a lot if we have specific details on what is BROKEN today with the PR in place, and what is BROKEN if we revert the PR.  Focusing just on devel for now as I think that is where both PRs are merged
15:19:56 <bcoca> felixfontein: its in the same code, see 3 lines above
15:20:12 <bcoca> ttyify removes 'unusabel' items linke M for tty
15:20:31 <felixfontein> yes, but M() has nothing to do with relative links
15:20:32 <bcoca> samccann: what is broken is in 2.11 that does NOT have the pr
15:20:46 <samccann> then let's ignore that for just right now bcoca
15:20:51 <bcoca> already put example in the ticket above, probably ALL error output that includes a link is broken
15:21:07 <bcoca> in devel, afaik nothing is broken to what ansible-doc generates
15:21:08 <samccann> I want to know specifically what is broken in devel with the PR in place, besides those three examples in the modules listed above
15:21:46 <bcoca> afaik there is only 1 change that woudl affect site and that was making teh set_Fact link relative
15:21:49 <abadger1999> All relative links in collections are broken in devel
15:21:54 <bcoca> not sure where other 2 modules come from
15:21:57 <samccann> Error output broken is not nice... but not as critical say as 404s on the docsite or 404s from an ansible-doc output (stuff thousands of users depend on daily)
15:22:16 <bcoca> abadger1999: can you show example and how that PR creates the issue?
15:22:23 <samccann> abadger1999 - but weren't all relative links in collections already broken?
15:22:53 <samccann> or was it only a subset and now all are broken?
15:23:18 <acozine> Broken today: link in the `cacheable` param docs of `set_fact` in `devel` https://docs.ansible.com/ansible/devel/collections/ansible/builtin/set_fact_module.html
15:23:36 <bcoca> my pr would only affect tty output AND the set_fact module changed from 'incorrect /latest/ ' to relative , no other modules should be impacted by that PR for the website
15:24:36 <bcoca> samccann: ansible-doc does NOT maniplulate links for --json output, so it delivers whatever is there
15:24:44 <bcoca> it does do so for screen output
15:26:14 <abadger1999> samccann: Sort of.  Now they're broken in two ways.  (1) There's two different relative link formats so collections can't work with both ansible-doc and docsite. (2) The previously, ansible-doc output brokenness that was obvious (a file path).  Now it's non-obvious (a proper URL that is a 404)
15:26:43 <bcoca> abadger1999:  not  with merged pr
15:27:05 <bcoca> the 404 is happening in 2.11 since ansible/2.11 was removed, devel points at ansible-core/<version> now
15:27:09 <bcoca> so those 'work'
15:27:29 <felixfontein> bcoca: you are talking about very specific 404s. there could be other 404s caused by your PR.
15:27:32 <bcoca> once ansible/2.11 was removed, previouslly working urls started to 404
15:27:35 <abadger1999> bcoca: Yes, with merged PR2
15:27:38 <acozine> As of today, the PR has not been backported, so links in the `latest` collections docs are still in whatever condition they were in before . . . we don't publish all collections in `devel` so we're not showing links there yet
15:27:40 <felixfontein> for example if U(other_plugin.html) was used
15:27:40 <samccann> so prior to the PR - ansible-doc output worked, but pointed to latest?  with the PR ansible-doc output works for the version, but is now broken
15:27:51 <felixfontein> (to link to other plugin in same collection)
15:27:52 <bcoca> felixfontein:  i checked against full install, could not find any, please show me one
15:27:57 <abadger1999> With only pr1 merged, all of anible-doc relative links in 2.11 are broken.
15:28:04 <bcoca> samccann: no
15:28:10 <samccann> sorry is now broken for docsite?
15:28:11 <abadger1999> With pr2 merged, all of ansible-doc relative links in collections are broken
15:28:13 <felixfontein> bcoca: I wrote 'could' because I didn't check whether there is any :)
15:28:15 <bcoca> samccann: ansible-doc output pointed to ansible/<version>
15:28:38 <bcoca> but ansible/2.11 was removed, so PR now makes it  point to ansible-core/<version> as docs team requested
15:29:02 <bcoca> abadger1999: the PR is not merged, test it and you'll see the links are fixed
15:29:03 <acozine> bcoca: prior to the PR being merged, ansible-doc pointed to `ansible/<version>`?
15:29:20 <bcoca> acozine: for the history of the function, that was always the case
15:29:24 <bcoca> since 2.3 iirc
15:29:34 <samccann> cyb-clock-simulator sez we are 30 min into this meeting and this topic
15:29:37 <bcoca> using /devel/ as an exception for devel
15:29:51 <abadger1999> commit 35281e54d95ce3fec6590fdd99d0a54317dddc5a
15:29:51 <abadger1999> Author: Brian Coca <bcoca@users.noreply.github.com>
15:29:52 <abadger1999> Date:   Thu May 13 15:20:32 2021 -0400
15:29:52 <abadger1999> fix config to match doc split (#74665)
15:30:34 <acozine> Goals for version-sensitive documentation links:
15:30:57 <acozine> 1. links on the docsite should point "within" the version the user is looking at
15:31:14 <samccann> so if we had to vote right now on revert or not revert, I couldn't vote. I still don't know the size of the problem. All I see right now is a couple of broken links in devel based on the two new PRs, and some problems that show up in the future (2.12) or in /last
15:31:17 <bcoca> acozine: that is independant from ansible-doc changes for tty
15:31:25 <samccann> sorry meant to delete that noise post
15:31:37 <abadger1999> acozine: Prior to the PR being merged, ansible-doc would have pointed to `user_guide/playbooks_variables.html#variable-precedence-where-should-i-put-a-variable` (ie: the raw path specified in a `U()` macro.
15:31:48 <samccann> let me ask my question differently - what is broken TODAY in devel... and what is broken TODAY in /latest?
15:32:26 <samccann> (assuming devel has both PRs and latest has neither)
15:32:34 <felixfontein> IMO the idea of treating relative URLs that don't start with `.` as relative to ansible(-core) docsite is not a good idea. I would have preferred an explicit prefix like `ansible://`
15:33:26 <bcoca> felixfontein: never said it was, that was just a fix for recently introduced issue with split, not complete fix, not final lcode, we have 4 or 5 cases to consider, this was 1 case adn now is needed to fix 404s in tty output
15:33:48 <acozine> samccann: today in devel we have two confirmed broken links in the module docs
15:34:07 <acozine> the two that were changed in the PR (one in `set_fact` and one in `user`)
15:34:22 <samccann> yeah so we could back just that out.  What else is broken in devel?
15:34:29 <abadger1999> relative links are in collections (as viewed by ansible-doc) are broken today in devel.  For instance, the amazon.aws plugins would not be able to reference the scenario guides that acozine split out here https://github.com/ansible-collections/amazon.aws/pull/362/files in a way that works with ansible-doc
15:34:44 <bcoca> abadger1999: yes, but tehy are also broken in all previous versions
15:34:52 <bcoca> that is independant of the PR that fixes tty output
15:34:58 <samccann> abadger1999  - that split hasn't happened so is not broken TODAY
15:35:06 <acozine> samccann: if we back out only those changes, not the whole PR, then those links will be broken in the tty (command-line) output
15:35:16 <abadger1999> samccann: <nod> But it means that we cannot split out the scenario guidea.
15:35:17 <bcoca> samccann: its broken for 2.11 since that site is gone
15:35:38 <samccann> acozine - why if we put back the hardcoded url would it be broken in tty?
15:35:41 <felixfontein> that site was never supposed to be there, since Ansible 2.11 does not exist
15:35:47 <samccann> it would be the wrong url again, but not broken
15:35:48 <bcoca> samccann: wont be broken, just 'wrongish'
15:36:01 <abadger1999> Yeah, those links will be correct.
15:36:33 <abadger1999> They just could be wrong if the latest version doesn't contain information pertinent to the version the user is running.
15:37:13 <acozine> it will be broken in the old way . . . this is what I meant in https://github.com/ansible/ansible/issues/74688#issuecomment-841516060
15:37:53 <acozine> we would once again be pointing (hard-coded) to `latest`
15:37:55 <samccann> ok I'll stop using the term broken.  We have a couple of 404s in the docsite today for devel.
15:38:35 <samccann> We have a LOT of 404s today in tty for 2.11 because it doesn't have the PRs backported... is that a correct statement?
15:38:47 <bcoca> those i can live with for a while , but i think it smore important to fix the current 404s for 2.11 console output
15:38:51 <bcoca> that is 'production'
15:39:00 <bcoca> yes
15:39:28 <abadger1999> samccann: Incorrect, I think
15:39:33 <bcoca> im fine with reverting the set_fact/user links to 'latest' for now, i just used tehm as example and because other PR was alreayd making same modification
15:39:48 <abadger1999> I don't think the PRs fix any 404s in ansible-doc-2.11
15:40:07 <bcoca> abadger1999: see ticket, i give example with interpreter discovery, w/o and with pr\
15:40:10 <acozine> is the tty output 404ing in 2.11, or just pointing to `latest` instead of to 2.11/4?
15:40:17 <bcoca> acozine: 404
15:40:32 <bcoca> since it goes to ansible/2.11 .. ansible tiself cannot know if it is 'latest'
15:40:37 <samccann> abadger1999 can you elaborate?
15:40:38 <bcoca> latest is only website concept
15:41:23 <abadger1999> samccann: What do you mean by tty?
15:41:45 <abadger1999> if by tty you mean ansible-doc, I stand by what I said.
15:41:57 <samccann> abadger1999 - was using bcocas term for handling what happens as a user if I type `ansible-doc` in 2.11
15:42:00 <abadger1999> bcoca's example is in an error message, not in ansible-doc's rendering
15:42:52 <samccann> so if I type `ansible-doc` in 2.11, will it return a url that is a 404 wherever someone has L() in the module docs?
15:43:14 <samccann> (as in I'm running 2.11 core)
15:43:25 <acozine> bcoca: true, `latest` is a docsite convention, and this problem is related to the docsite . . . the command-line output points to the docsite
15:43:49 <abadger1999> samccann: ah.  ansible-doc in 2.11 doesn't understand relative links at all so it will print the raw relative path.
15:43:50 <bcoca> samccann: no, for error system, we have errors that return urls, again see ticket for the url from the python interpreter discovery
15:44:16 <bcoca> abadger1999: yes it does , we've been using them for many versions, otherwise our errors would be pointing to incorrect versions
15:44:29 <acozine> so while hardcoding links to point to `latest` is incorrect, it comes close to being correct, and it avoids 404s
15:44:38 <abadger1999> bcoca: Your statement does not contradict what I said.
15:44:42 <samccann> bcoca - for now, error messages are small potatoes.. the size of peas, compared to the number of times a user types `ansible-doc`. I want to focus on what most users might experience
15:44:49 <bcoca> acozine: except when the page does not exist in latest
15:45:11 <acozine> true, and i saw examples of that
15:45:28 <acozine> but all the examples I've seen have ALSO not existed in 3/2.11/4
15:45:44 <bcoca> samccann:  right now they wont get a usable lihnk from relative links  outside devel, in devel they only get usable when relative to anbilse-core
15:46:00 <samccann> #info ansible-doc in 2.11 doesn't understand L() relative links at all so will return a relative path that is 404 for a user
15:46:07 <acozine> https://docs.ansible.com/ansible/become.html will not work in any version
15:47:11 <bcoca> for devel we still need to fix more cases, only ansible-core relative links work, but for 2.11 we need to fix main case, which is error links
15:47:40 <acozine> bcoca: ah, do you have a list of these error links?
15:47:42 <bcoca> afaik we dont seem to have many relative links
15:47:58 <bcoca> acozine: i gave one exmaple, iirc become is another and there shoudl be more, dont have em memorized
15:49:02 <bcoca> the `seealso` section has been broken since introduced, not sure that ever worked so going to ignore that for now
15:49:20 <samccann> #info there are a scattering of error messages within module python code that have hard-coded urls to latest. Some of these have been changes to use relative links base on these PRs
15:49:23 <bcoca> https://docs.ansible.com/ansbile/2.11/user_guide/become.html
15:49:35 <acozine> it would be very helpful to collect all the links we need to fix, and all the scenarios where the solution needs to work, in a single issue
15:50:03 <bcoca> samccann: no, most should be using version relative code
15:50:13 <samccann> #undo
15:50:15 <acozine> bcoca: there is no Ansible 2.11 any more
15:50:24 <samccann> erm.. did my undo work?
15:50:27 <bcoca> acozine: i know, that is why it started 404ing
15:50:38 <bcoca> till last tuesday those worked
15:50:54 <bcoca> and that does NOT have my code, that is because of site split and no updates to ansible-core
15:51:03 <bcoca> my pr updates ansible-core 2.11 to fix this
15:51:15 <abadger1999> samccann: It did not... you and I are not chaired
15:51:19 <acozine> we need a way to use the Ansible version, not the ansible-core version, in relative links
15:51:21 <acozine> oh, dammit
15:51:21 <bcoca> we can remove the set_fact/user stuff if you want, though those would work fine for tty, not sure for site
15:51:24 <samccann> carp
15:51:26 <acozine> #chair abadger1999 samccann
15:51:26 <zodbot> Current chairs: abadger1999 acozine dericcrago felixfontein lmodemal samccann tadeboro
15:51:30 * samccann cries river of tears
15:51:32 <acozine> #chair bcoca
15:51:32 <zodbot> Current chairs: abadger1999 acozine bcoca dericcrago felixfontein lmodemal samccann tadeboro
15:51:42 <abadger1999> #undo
15:51:42 <zodbot> Removing item from minutes: <MeetBot.items.Link object at 0x7f25aa1c9590>
15:51:46 <bcoca> acozine: yes, but again, we have many cases to handle, im just trying to fix current 2.11
15:51:56 <samccann> #info ansible-doc in 2.11 doesn't understand L() relative links at all so will return a relative path that is 404 for a user
15:52:07 <bcoca> devel has a 'start' of the solution with ansible-core generated messages being ansible-core relative
15:52:32 <samccann> #info we have a scattering of errorr messages within module python code that uses the relative link function. This is broken in 2.11 since ansible/2.11 does not exist anymore.
15:52:37 <abadger1999> samccann: Well... it is a filesystem path, rather than a URL so it probably won't even get to the 404 stage ;-)
15:53:01 <samccann> abadger I mean a user can't click it or copy it to anything usefule
15:53:01 <bcoca> see the dig page
15:53:10 <acozine> have we never used `latest` in the error message URLs?
15:53:23 <samccann> cyb-clock-simulator sez we are 53 min into this meeting on this one topic
15:53:27 <acozine> sigh
15:53:38 <bcoca> acozine: we did, till we saw some versions then pointed to 404s that is why in 2.3 we started moving to 'version relative links' for errors
15:53:54 <samccann> what do we want to accomplish at this point? I don't feel like we have agreed to revert both PRs. .nor have we agreed to backport both PRs. We are stuck
15:54:06 <bcoca> lthat way we made sure the content was a) existed and b) was correct for that version
15:54:51 <samccann> should we perhaps action item collecting what is broken today in devel vs latest, and what will break in the future (2.12, when we move scenario guides) to help us decide? That punts it all out another week
15:55:22 <samccann> (what is broken in ansible-doc, what is broken in docsite.. what is broken anywhere else that uses ansible-doc --json if anything??)
15:56:10 <bcoca> samccann: ansible-doc --json does not change the data, so whatever is broken in tha toutput is broken at source
15:56:11 <samccann> i think we agree what is in devel today is not complete. I think we disagree on the coding approach and how it should be handled.
15:56:26 <acozine> I think it's more important to fix Ansible 4 than to fix 2.11, since we want to drive traffic to the `/ansible/` section of the website
15:56:27 <samccann> next steps?
15:56:45 <bcoca> samccann: i agree its not complete, i dont think we disagree on approach cause i have not heard one, i only heard about 1 extra case and no implementation
15:56:51 <samccann> acozine elaborate - you are talking only the docsite? or ansible-docs output as well?
15:56:58 <bcoca> im also stating we have more than 1 extra case to handle
15:57:21 <acozine> samccann: both
15:57:31 <bcoca> and not just asnible-doc console, docs.ansible.com, but also galaxy and ah display
15:58:13 <samccann> acozine - I'm sorry I'm just not parsing what you are saying. Ansible 4 and 2.11 are tied together (as in ansible 4 uses 2.11 in both the docsite and ansible-doc output)
15:58:20 <bcoca> and my point that we cannot just have relative links, we need indicator 'relative to what', what target does the link have, docsite? colleciotn docs? other collection?
15:58:34 <samccann> #agreed we want any links to go to /ansible/ not /ansible-core/
15:58:38 <abadger1999> I think we can revert the first PR entirely and leave the second PR.  That should fix the error messages and not touch ansible-doc or the module relative links (both of which are broken).  A future patch to ansible-doc will not be able to use get_versioned_doclink, then (as get_versioned_doclink will only be useful to the error messaes inside of ansible-core.)   Note that it does contravene what the docs team asked for which
15:58:38 <abadger1999> was that we should push people to the more complete documentation whenever possible but I think that's fine for error messages.
15:58:39 <samccann> is that correct? ^^
15:58:51 <bcoca> samccann: no, ansible 4 is tied to ansible-core 2.11, but ansible-core 2.11 is NOT tied to ansible4
15:58:55 <acozine> samccann: yes, and the current fix relies on creating links to /ansible-core/2.11
15:59:39 <samccann> bcoca agreed but from a docsite (and thus any urls) - we drive traffic to /ansible/ not /ansible-core/. That was a product mgmt decision
16:00:06 <acozine> abadger1999: I like that idea, we can backport (when the stable branches are open for backports again) the second PR to fix the error message portion
16:00:11 <bcoca> samccann: i know, not saying to change the docsite, but i have to consider those not using ansible4 or using overlays for ansible-doc output
16:00:45 <samccann> abadger or acozine can you summarize/info what you are agreeing on?
16:00:58 <acozine> and then make a list of everything that is broken (or at least, doesn't work the way it really should) so we can test as we fix
16:01:00 <samccann> bcoca - what are 'overlays for ansible-doc output' ?
16:01:16 <bcoca> samccann: ansible4 but newer version of collection included in a4
16:01:24 <bcoca> or no ansible4 but collection that is part of ansible4
16:01:49 <bcoca> and 'desitnation' matters, a colleciton can be pointiong to 'main docs' or its own docs
16:01:58 <samccann> bcoca ah so if I have ansibl4 nstalled, but a new collection or an updated collection, `ansible-doc` will work?
16:02:05 <bcoca> so assuming its all ansible/4 relative is not right output for all cases
16:02:24 <samccann> meaning it will give me the module docs for the new or updated collection?
16:02:32 <bcoca> samccann:  it 'works' now, just shows incomplete urls for relative links (except in devel for ansible-core)
16:02:40 <bcoca> yes
16:02:50 <bcoca> if ansible uses it, ansible-doc will show associated docs
16:02:57 <bcoca> since they use same 'plugin/collection finder'
16:03:06 <acozine> #info if we revert PR 74245 and leave PR 74665, then backport 74665, that should fix the error message output
16:03:22 <acozine> samccann: summary ^^^
16:03:47 <samccann> thanks acozine
16:03:47 <bcoca> that will leave relative links broken across board in devel
16:04:03 <abadger1999> Proposing: Revert changes to ansible-doc (code is incorrectnaive since it doesn't handle collections) and modules (code is incorrect as it does not use the existing format for relative links) ( c1879a5011cbc8dacc5be44d55940cf0a05deecd ). Backport the change to config as that will address error messages issued by ansible.  New changes to fix ansible-doc output will need to use a different function for determining version as the
16:04:03 <abadger1999> error messages and documentation have different requirements.
16:04:40 <bcoca> reverting that will make it incorrect for docs too
16:05:00 <bcoca> wont 404 for set_fact/user, but other relative links will break again
16:05:14 <acozine> bcoca: example?
16:05:20 <samccann> we should keep in mind from the user perspective, devel has very few users. I can dig up stats, but I want to say < 10% of all docsite hits ever go to devel docs.
16:05:20 <abadger1999> The change to backport is 35281e54d95ce3fec6590fdd99d0a54317dddc5a
16:05:51 <samccann> my point being - we can leave devel broken for a time if need be while we find the appropriate solution that works for all
16:06:30 <bcoca> samccann: devel has partial fix, reverting that does nothing to move forward, adding more cases on top is the way to go, i see no point in the revert
16:06:55 <bcoca> is it final fix, no, never meant it to be, but it is something to build on
16:07:07 <bcoca> covers 'case #1', now we need 2-5
16:07:27 <bcoca> but if we spend all the time saying 'it only covers #1' .. when are we getting to fixing 2-5?
16:07:42 <abadger1999> The first PR is just broken.  Period.
16:07:58 <samccann> bcoca I'm agnostic on reverting, just saying either decision (revert or keep ) has minimal impact on most users while it's happening in devel
16:08:03 <bcoca> abadger1999: no, it isnt. Exclamation mark
16:08:07 <felixfontein> since also AH and antsibull-doc need to implement the same thing, any solution needs to be discussed and agreed by all three parties first
16:08:31 <samccann> good point felixfontein
16:08:42 <bcoca> felixfontein: yes and no, we need to find compatible solutions, but they cannot be same solution
16:08:49 <abadger1999> Unfortunately the programmer who made it has refused to hear any of the issues that we've pointede out with it so I don't think there's any chance that it will get fixed properly.  Reverting it seems to be the only choice.
16:08:59 <bcoca> docssite, ah and galaxy have 'context' of being in the site itself, while the CLI does not
16:09:08 <samccann> #info since also AH and antsibull-doc need to implement the  compatible solutions, any solution needs to be discussed and agreed by all three parties first
16:09:34 <acozine> bcoca: if PR 74245 turns out to be the right fix in the end, we will reimplement it and change the channel topic to say `BCOCA WAS RIGHT` for at least a month
16:09:38 <bcoca> abadger1999:  been more than willing to discuss a way forward, have yet to hear one proposal of how that looks that would work for cli
16:09:41 <acozine> but for today . . .
16:09:51 <acozine> it's time to vote
16:10:21 <felixfontein> I'm proposing `ansible://` for things that are converted to versioned ansible docsite links
16:10:35 <bcoca> well, if we are goign to be patronizing ... do whatever, i'll try to fix the fallout, like the arbitrary deletion of ansible/2.11
16:10:52 <acozine> VOTE: backport 74665, revert 74245, create an issue that details what is broken, then proceed to fix(es)
16:11:01 <abadger1999> felixfontein: and `ansible-core://` as well?
16:11:01 <bcoca> felixfontein: see, that makes sense, a token that shows what desitnation is intended
16:11:24 <acozine> bcoca: I'm sorry if you didn't know that we were not going to publish docs to `/ansible/2.11`
16:11:30 <acozine> it was not meant to be a secret
16:11:45 <bcoca> felixfontein: previouslly i had suggested a , core/ansible/collection) parameter to L()
16:11:51 <acozine> it is driven by changes to the product
16:11:56 <felixfontein> abadger1999: that's something that needs to be discussed, and depends on whether everything should link to /ansible/ or not (from what I read above that seems to be a goal of product management)
16:12:12 <bcoca> acozine: docs WERE published, ansible=core 2.11 went out pointing at them, docs were removed w/o notice so that is what broke 2.11
16:12:16 <samccann> can we actually vote to see if we have consensus to revert?
16:12:26 <acozine> vote on proposal above
16:12:27 <acozine> #chair
16:12:27 <zodbot> Current chairs: abadger1999 acozine bcoca dericcrago felixfontein lmodemal samccann tadeboro
16:12:35 <abadger1999> felixfontein: <nod> I was pondering the same distinction.
16:12:42 <bcoca> acozine: its fine, but a) notice woudl have been nice b) time to fix 2.11 to adjust would also have avoided this whole thing
16:12:49 <abadger1999> +1  revert 74245
16:13:08 <felixfontein> I'm +0 on reverting since I'm fine with a follow-up fix, as long as it is not backported until it's properly fixed. but I'm +1 on backporting 74665
16:13:19 <samccann> bcoca - 2.11 when out because of a broken automated jenkins build that we had no indication was triggered by a beta release
16:13:23 <acozine> bcoca: yes, docs were published to `/ansible/2.11` but that was unintentional, and honestly, I didn't realize that it would break those error messages
16:13:27 <abadger1999> Can it be confirmed that 73245only affects the error messages, not the documentation (ansile-doc or docsite) ?
16:13:53 <tadeboro> +0 (did try to follow along, but failed miserably).
16:14:12 <lmodemal> abstain
16:14:17 <bcoca> samccann, acozine i understand taht, but that still does not remove b) .. and then when discovered, the removal of 'what was working' even accidentally created an issue, while keeping it until a fix coudl be made would have been seamles to users
16:14:45 <samccann> 0 on reverting because I can't tell yet HOW MANY things are broken in devel with and without the PR
16:15:07 <acozine> +1 to reverting 74245, +1 to backporting 74665
16:15:42 <acozine> I can talk to the product people about temporarily reinstating `/ansible/2.11` docs until we get a full fix
16:15:54 <acozine> we can't add it to the version-switcher, though
16:16:14 <felixfontein> how about making it a redirect?
16:16:27 <bcoca> either of those work, as long as user does not get 404
16:16:34 <samccann> -1 to adding 2.11 back. +1 to some other quick fix like the redirect idea
16:16:50 <acozine> redirecting `/ansible/2.11/*` to `/ansible/4/*`?
16:16:57 <samccann> we are 15 minutes over
16:17:04 <acozine> sorry folks
16:17:04 <bcoca> samccann: feel free to revert, devel is devel, can be reapplied tomorrow again
16:17:21 <felixfontein> acozine: or just to /ansible/latest/ for now
16:18:05 * abadger1999 notes that ansible-4 comes out..... today!
16:18:11 <acozine> only if we put up an enormous banner somewhere that i will see every day that says "disable that mass redirect before Ansible 5"
16:18:39 <acozine> I could totally see myself forgetting, and 2.11 users being "modernized" until the end of time
16:18:46 <acozine> okay
16:18:54 <acozine> I think we've reached a kind of consensus
16:19:13 <acozine> there are 4 parts
16:19:15 <bcoca> then probably less confusing to restore /2.11 at least till fix is shepped
16:19:57 <acozine> 1. restore 2.11 temporarily
16:20:06 <acozine> 2. revert 74245
16:20:26 <acozine> 3. backport 74665 when we can, test to see if we can remove /ansible/2.11 site then
16:21:12 <acozine> 4. document all the aspects of this hornets' nest of How to Provide Version-Sensitive Links and Not 404s, so we can figure out how to fix them all
16:21:12 <bcoca> you'll probalby want to keep aroudn a few versions since people dont upgrade right away
16:21:57 <acozine> we can watch the traffic stats
16:22:18 <samccann> can you either info or action each of those so we remember in the meeting minutes acozine
16:22:21 <acozine> and put a redirect in if need be
16:22:29 <abadger1999> 1. -1; .2 +1; 3 +1; 4. seems good to me.
16:22:46 <acozine> heh, I should wait for any objections . . . .
16:22:52 * acozine whistles
16:22:57 * acozine hums
16:23:01 <samccann> yeah I'm till -` on restoring 2.11 docs
16:23:06 <felixfontein> I would have a redirect for 2.11 instead of restoring it
16:23:07 <samccann> the rest I'm fine with
16:23:14 <acozine> okay
16:23:17 <felixfontein> i.e. also -1 on restoring 2.11 docs :)
16:23:21 <abadger1999> Note that  1 and 3 seem like they're both addressing the same problem that's why I vote -1 to 1 and +1 to 3.
16:23:36 <acozine> sigh
16:23:39 <acozine> okay, redirect it is
16:23:44 <bcoca> 1 is temporary fix till 3 is shipped
16:23:53 <acozine> but y'all have to help me remember to remove it
16:23:58 <bcoca> yes, they addres same issue but 1 can be done 'right now' while 3 will take time
16:24:10 <felixfontein> if it's a redirect, it doesn't really matter if it stays longer
16:24:30 <bcoca> felixfontein: it will eventually be incorrect
16:24:39 <samccann> acozine we can put a meeting invite for ourselves 'in the future' to say remove this redirect ;-)
16:24:53 <felixfontein> bcoca: eventually everything is incorrect, just wait long enough
16:25:02 <felixfontein> see the original become link :)
16:25:44 <bcoca> which started all this ...
16:25:52 <acozine> #agreed 1. add a redirect for 2.11 => latest as a temporary fix, 2. revert 74245, 3. backport 74665 to 2.11 when we can (remembering that it may take some time to propagate, since folks don't upgrade quickly), 4. create an issue that covers all the aspects of Version-Sensitive Docs Links before we try to fix it again
16:26:02 <acozine> okay
16:26:14 <bcoca> 4 isnt that the issure you refferenced above?
16:26:44 <bcoca> i gotta go, bbl
16:26:48 <acozine> bcoca: it's a start, but I suspect I haven't covered it all
16:26:52 <acozine> bcoca: thanks
16:27:01 <acozine> I'll take the redirect
16:27:09 <samccann> ok a quick open floor?
16:27:12 <acozine> yeah
16:27:15 <acozine> #topic open floor
16:27:22 <acozine> sorry, folks, that was a long one
16:27:30 <acozine> at this point anyone can bring up any topic
16:27:31 <acozine> questions
16:27:33 <acozine> comments
16:27:35 <acozine> ideas
16:27:37 <acozine> suggestions
16:27:39 <acozine> complaints
16:28:45 <acozine> the rest of our agenda, I'm sad to say, will be put off until next week
16:29:02 <samccann> we made progress on a sticky item so that's good
16:29:45 <acozine> true
16:29:59 <acozine> okay, hearing no open floor items
16:30:59 <acozine> thanks abadger1999 bcoca dericcrago felixfontein lmodemal samccann tadeboro
16:31:13 <acozine> #endmeeting