14:31:14 <samccann> #startmeeting Docs Working Group aka DaWGs
14:31:14 <zodbot> Meeting started Tue Sep 15 14:31:14 2020 UTC.
14:31:14 <zodbot> This meeting is logged and archived in a public location.
14:31:14 <zodbot> The chair is samccann. Information about MeetBot at http://wiki.debian.org/MeetBot.
14:31:14 <zodbot> Useful Commands: #action #agreed #halp #info #idea #link #topic.
14:31:14 <zodbot> The meeting name has been set to 'docs_working_group_aka_dawgs'
14:31:21 <samccann> #topic opening chatter
14:31:34 <samccann> so ... who's around to rock the docs!!
14:32:23 <samccann> acozin is out today.
14:33:04 <felixfontein> hi!
14:33:10 <felixfontein> (sorry, had to change room and computer)
14:33:17 <samccann> #chair abadger1999 felixfontein
14:33:17 <zodbot> Current chairs: abadger1999 felixfontein samccann
14:33:30 <felixfontein> morning abadger1999!
14:33:43 <samccann> gundalow cyberpear baptistemm ?
14:33:56 * gundalow waves
14:34:10 <gundalow> How's everybody doing?
14:34:15 * samccann tosses furniture
14:34:19 <samccann> #chair gundalow
14:34:19 <zodbot> Current chairs: abadger1999 felixfontein gundalow samccann
14:34:22 <abadger1999> Pretty well :-)
14:34:42 <samccann> All's quiet on the Eastern (us) front
14:35:00 <baptistemm> hey
14:35:10 <samccann> welcome baptistemm !
14:35:14 <samccann> #chair baptistemm
14:35:14 <zodbot> Current chairs: abadger1999 baptistemm felixfontein gundalow samccann
14:35:48 <samccann> #info agenda is at https://github.com/ansible/community/issues/521#issuecomment-688977308
14:36:02 <samccann> hmm... possibly a self-referential loop there :-)
14:36:22 <samccann> Anyway onto the first topic
14:36:39 <samccann> #topic release readiness for 2.10 for docs
14:36:51 <felixfontein> a good topic, since today's (supposed to be) 2.10.0rc1 day
14:37:07 <samccann> heh yep.  So 1st question - IS today rc1 day?
14:38:16 <samccann> abadger1999 ^^ ?
14:38:32 <abadger1999> Yep :-)
14:38:36 <samccann> woot woot!
14:38:41 <samccann> #info RC1 goes out today!
14:39:08 <samccann> so are we any further along on the bitflip notion for Ansible releases? or are we rockin it manual style for now?
14:39:24 <felixfontein> \o/
14:39:37 <abadger1999> We aren't.  So we should plan on manual style
14:40:14 <samccann> #info we will continue with the manual coordination of the release between the package and docs publishing etc
14:40:20 <abadger1999> We do have an advantage with the dot oh release that the bits shouldn't change from rc1 to final, though
14:40:32 <samccann> that would be good :-)
14:40:52 <abadger1999> Yeah :-)
14:40:59 <samccann> but we'd still have to redo the porting guide right? or will RC1 do the magic that collapses all the beta/alpha info into 2.10.0 ?
14:41:30 <samccann> erm and for the changelogs?
14:41:44 <abadger1999> samccann: i believe you are correct.  (Felixfontein, can you confirm?)
14:42:04 <felixfontein> the magic will happen for 2.10.0
14:42:23 <felixfontein> so rc1 (and rc2 etc. if they exist) will still have the many version entries
14:42:45 <samccann> #info should be no change between rc1 and final release, but we will need to regenerate porting guide/changelogs  to get the collapsed 2.10.0 versions (w/o the beta/alpha subsections it has today)
14:42:53 <samccann> ok good to know
14:43:12 <samccann> That brings us to...
14:43:18 <samccann> #topic redirects status
14:43:35 <abadger1999> Hmmmm, since we store those in the ansible/ansible repo, i wonder if it will be a problem for the bit flip strategy too
14:44:07 <samccann> I'm thinking we design/test bitflip fun for 2.10.1 (Ansible) ?
14:44:17 <abadger1999> Yeah, sounds good
14:44:18 <samccann> as in we have enough to stress about for 2.10.0 for now
14:44:24 <felixfontein> +1
14:44:35 <samccann> #info will get back to designing bitflip releases for Ansible with 2.10.1
14:44:51 * gundalow is happy to throw stuff in the "think about 2.10.0 bucket"
14:44:53 <samccann> it all worked out reasonably well for beta with coordinating here
14:45:03 <samccann> :-)
14:45:54 <samccann> on redirects, abadger1999 fixed that plugin issue yesterday. Do we have other known issues on the redirects?
14:46:16 <baptistemm> redirects on doc website ?
14:46:19 <samccann> yes
14:46:39 <felixfontein> on which (test) sites are they active right now?
14:47:11 <samccann> #info use this link to test redirects - https://docs.ansible.com/ansible/2.10/collections/index.html - manually edit url to 2.9 and back to 2.10 for any module or plugin and report errors on #ansible-docs
14:47:43 <abadger1999> samccann: Is it on docs.ansible.com now or just on docs.testing.ansible.com?
14:48:07 * abadger1999 should just test ;-)
14:48:16 <felixfontein> https://docs.ansible.com/ansible/2.9/collections/community/general/dzdo_become.html does not work
14:48:31 <felixfontein> ah lol
14:48:31 <samccann> just on test site for now. I don't think we are putting on docs.ansible.com until 2.10.0 ships
14:48:42 <samccann> DAG NAMMIT!
14:48:48 <samccann> ok now I see the confusion.  sorry :-)
14:48:58 <samccann> what's the command to remove an info?
14:49:03 <felixfontein> #undo
14:49:03 <zodbot> Removing item from minutes: <MeetBot.items.Link object at 0x7fcccfffb390>
14:49:37 <abadger1999> Hmmmm.... docs.testing.ansible.com is not responding... /me shells into the server to see if he can diagnose why
14:50:06 <felixfontein> abadger1999: if you try https://, that doesn't work
14:50:12 <felixfontein> ran into that trap as well...
14:50:16 <samccann> #info use this link to test redirects http://docs.testing.ansible.com/ansible/2.10/collections/index.html -manually edit url to 2.9 and back to 2.10 for any module or plugin and report errors on #ansible-docs
14:50:28 <abadger1999> ah
14:50:30 <abadger1999> okay :-)
14:50:48 <abadger1999> My fingers are forgetting that http:// exists ;-)
14:50:53 <samccann> heh
14:51:06 <felixfontein> mine too, especially since it isn't shown anymore most of the time (except by that unsecure icon)
14:51:10 <samccann> so meanwhile - how do we get more people banging on this to help us find errors?
14:51:29 <felixfontein> I guess deploy it to production :D
14:51:49 <samccann> i'm personally torn between asking reddit/devel mailing lists to help us out ... but then we are spreading the docs test site url far and wide
14:51:52 <gundalow> samccann: I'd generally suggest: reddit, bullhorn, Google Group, https://github.com/ansible-collections/overview/issues/45
14:51:53 <samccann> lol yep, that would do it
14:52:15 <samccann> gundalow - so you're okay with spreading the test url onto those places?
14:52:25 <samccann> it does have a 'this is a test site' banner on it now
14:52:46 <felixfontein> as long as the redirects do not destroy something that is currently working (i.e. redirect a valid page on 2.9 or 2.10 to an invalid page on 2.9 resp. 2.10), deploying to production and let people test it there is the best approach
14:52:50 <felixfontein> (IMO)
14:52:56 <gundalow> samccann: I think so. Feedback is important, and as you said, we need to get feedback from wider set of people
14:53:04 <samccann> ok
14:53:36 <samccann> #action samccann to post docs test site url to reddit/google group/ https://github.com/ansible-collections/overview/issues/45 to ask for wider help in testing the urls
14:53:50 <samccann> I don't know that bullhorn will get out fast enuf? I'll have to check its schedule
14:54:07 <samccann> felixfontein: - I'm reluctant to make that decision when acozine is out for the week.
14:54:24 <samccann> and yes, yes I do hide behind my Fearless Leader on important decisions like this :-)
14:54:32 <abadger1999> I think I'm with felixfontein but I understand your hesitance :-)
14:54:34 <felixfontein> samccann: I fully understand :)
14:54:59 * baptistemm fires wget --spider
14:55:08 <abadger1999> (and I don't think there's harm in publishing the testing site with the big banner)
14:55:16 <samccann> baptistemm - what will that do?
14:55:38 * samccann just curious
14:55:39 <felixfontein> can you run `find -type f` in the 2.9 and 2.10 dirs on the testing webserver and upload the result somewhere? then I can hack a script which does a HEAD to all URLs to see whether they have a 200 or 30x
14:56:13 * samccann blinks incomprehendingly
14:56:17 <felixfontein> if there's no (unexpected) 30x (there shouldn't be any IMO), it would be safe to deploy
14:56:23 <baptistemm> samccann: goes through all links it finds :)
14:56:43 <samccann> ah so felixfontein's question was directed at your wget ?
14:56:45 <felixfontein> baptistemm: but that doesn't really help to identify cases where valid pages are now redirected
14:57:01 <felixfontein> samccann: no, it was redirected at you, or anyone else who can do that on the webserver :)
14:57:11 <felixfontein> (resp. test webserver)
14:57:12 <abadger1999> felixfontein: I can.
14:57:17 <samccann> whew
14:57:22 <felixfontein> :)
14:57:28 <felixfontein> abadger1999: cool, thanks!
14:57:30 <baptistemm> ah okay, I got 404 so I thought this was the problem (sorry I've doing job at the same time)
14:58:12 <baptistemm> s/ve/m/
14:58:18 <felixfontein> baptistemm: some 404s are expected because some modules have been removed in 2.10, and some have been added
14:59:17 <samccann> would/should the list of 404s for removed/added modules match the list that should be in the porting guide? or is that asking too much for our docs accuracy there :-)
15:00:34 <felixfontein> samccann: not all collections put that info in there, and a lot of collections added **all** their modules/plugins as "new" ones
15:00:44 <samccann> ooch yeah ok
15:01:40 <samccann> okay any other testing redirects thoughts before we move on? Any other 'are we ready for this release' comments/questions? (regarding docs that is ;-)
15:02:45 <felixfontein> I guess we are as ready as we are, and it won't change much over the next week ;)
15:02:52 <samccann> lol so very very true!
15:02:57 <samccann> ok moving on
15:03:32 <abadger1999> felixfontein: https://toshio.fedorapeople.org/ansible/ansible-docs-listing.txt
15:04:05 <samccann> #topic new module field for orphaned
15:04:27 <samccann> andersson007_ added this to the agenda with some notes/questions - https://github.com/ansible/community/issues/521#issuecomment-692558831
15:04:36 <samccann> #link https://github.com/ansible/community/issues/521#issuecomment-692558831
15:05:18 <samccann> I think part of this is docs and probably part is a community discussion
15:05:23 <andersson007_> samccann: ok, thanks
15:05:51 <samccann> hey hang around if you can, but no worries if you can't
15:06:12 <felixfontein> oh, btw, about the redirections: could we make them temporary (at least for now)? if we find out that some are bad, it would be a LOT easier to change (since they don't get cached)
15:06:17 <felixfontein> abadger1999: thanks!
15:06:48 <samccann> erm... I don't know?
15:07:49 <abadger1999> felixfontein: Okay, I need to sort out what the apache keyword is but definitely could.
15:09:10 <samccann> #action abadger1999 - for redirects, will investigate the apatch keyword to make redirects temporary for now so they are not cached/easier to change if some are bad
15:09:10 <felixfontein> abadger1999: how do you do the redirects?
15:09:21 <abadger1999> Looks like if I just leave out "permanent" then it will do the correct thing.
15:09:41 <felixfontein> yep, that should work
15:09:42 <abadger1999> felixfontein: RedirectMatch permanent "^(/ansible/[^/]+)/plugins/become/doas.html" "$1/collections/community/general/doas_become.html"
15:09:57 <abadger1999> I  just need to remove permanent and it should be temporary
15:09:58 <felixfontein> leaving away `permanent` should make it temporary
15:10:01 <abadger1999> Cool.
15:10:20 <samccann> does the difference between permanent and... not permanent mean the server gets hit for every redirect? As in with permanent, the hits would be less because everyone's browser is caching it somewhere else?  ...just curious
15:11:15 <abadger1999> Yeah, the browser can cache the new url when it is permanent so then when you type in the old url, the browser can directly ask the server for the new url.
15:11:51 <samccann> ok thanks. just trying to understand if we are adding more load to the docs server while they are all still temporary.
15:12:20 <samccann> As in - should we rush to make them permanent a week/ a month/ after release?  Or - no big deal, make them permanent by 2.11 for example
15:13:04 <felixfontein> I would keep it temporary for a couple of weeks, and then switch it to permanent
15:13:30 <felixfontein> just to avoid being unable to quickly fix if some redirects turn out to be wrong
15:13:56 <abadger1999> search engines are affected too but that's probably not going to affect us much (as we
15:13:59 <samccann> a follow-on question - when 2.11 does come around, and let's assume we have loads of modules shifting to a different collection (say out of c.g/c.n) - will we create a new batch of redirects at that point?
15:14:18 <abadger1999> 're not moving pages which did exist... we're just giving people a second name to find new content)
15:15:01 <abadger1999> samccann: Yeah..... that's something to consider.  I think it's better to do so.  But it means updating the redirects with new content.
15:15:19 <abadger1999> And figuring out how we want to manage the matrix of possibilities.
15:15:22 <felixfontein> abadger1999: I'm currently running https://gist.github.com/felixfontein/c77bf799ea79873097726f03ab9fb224 - should have made it parallel, that would be *slightly* faster :)
15:15:42 <samccann> so what's the impact if we make say c.g redirects permanent, and then come 2.11, 50% of them have new redirects?
15:16:07 <abadger1999> samccann: in other words.... quite a bit of work is needed  to make that happen but it feels like it would be the best user experience.
15:16:20 <felixfontein> for 2.11 a lot more redirects would be needed
15:16:26 <felixfontein> (if a lot of modules are moved)
15:17:19 <samccann> Ah so a 2.9 <-> 2.10 redirect still has to be in place, but then we'd add 2.10<-> 2.11  (and 2.9, etc)
15:17:32 <felixfontein> when that happens more often, it might be more efficient to create stub pages with <meta> redirects instead of adding webserver redirects
15:17:37 <samccann> ok I think I get it.
15:17:57 <abadger1999> samccann: It should be okay... we'd have more than one redirect: 2.11/url_from_2_9/  => 2.11/url_as_it_is_in_2.11   and user hits 2.11/url_from_2_10 => 2.11/url_as_it_is_in_2.11
15:18:16 <felixfontein> the current redirects are version agnostic, they only know about <= 2.9 and >= 2.10, but from 2.11 on they would need to be more specific
15:18:32 <abadger1999> felixfontein: yep.
15:18:49 <samccann> ok problem for a different day then :-)
15:18:56 <abadger1999> the script that generates this will need to become a lot more intelligent if we do redirects for 2.9, 2.10, and 2.11.
15:19:15 <felixfontein> samccann: indeed ;)
15:19:36 <samccann> my nickel - we discuss the option of stub pages as felixfontein suggested.  But that's for later
15:19:38 <felixfontein> in any case, it won't hurt if the currect redirects are permanent, as long as this is fixed before the 2.11 docs are there
15:20:13 <felixfontein> we eventually need stub pages for redirects, aliases, tombstones etc. anyway
15:20:26 <felixfontein> but that's for later I guess
15:20:38 * samccann looks at that list...and hides under desk
15:21:00 <abadger1999> either stub pages or redirects for those.... we could do either 9aas long as the canonical page has information about all those alternate names)
15:21:05 <felixfontein> always see the bright side: you won't be out of work anytime soon ;)
15:21:11 <abadger1999> Hehe :-)
15:21:17 <samccann> #action samccann - add 2.11 redirects Deep Thoughts to dawgs agenda for post 2.10
15:21:22 <samccann> heh so true!
15:21:44 <samccann> so are we ready to discuss the WIP pr for orphaned modules etc?
15:22:12 <samccann> #link https://github.com/ansible/ansible/pull/71680
15:23:17 <abadger1999> i guess my biggest question would be whether that should be something inside of the module or something in a separate file.
15:23:47 <felixfontein> samccann: I think adjusting it to the format of the proposal would be good. though maybe the proposal needs more discussion first.
15:24:00 <felixfontein> abadger1999: you mean like BOTMETA?
15:24:03 <samccann> I'm personally a bit confused on the process here - it's implementing part of a proposal that is 3 years old...and I can't tell if the proposal was formally 'accepted'? And then there's a draft from gregdek for orphaned vs retired modules and again, how do we know if its approved etc?
15:24:14 <abadger1999> For community.general, it doesn't make a difference but for things that are in collections we don't control, maybe it's better to live outside of the module?
15:24:20 <abadger1999> felixfontein: yeah, like BOTMETA.
15:24:43 <felixfontein> samccann: it wasn't part of the proposal until I mentioned that proposal, and andersson007_ adjusted the PR accordingly :)
15:25:05 <samccann> hmm so if it lived outside of the module, then the Ansible team gets to decide if something in someone else's collection has been orphaned or not?
15:25:11 <felixfontein> abadger1999: would it live in the collection that contains the module?
15:25:13 <felixfontein> (or plugin)
15:25:29 <samccann> on the one hand, feels heavy-handed... on the other - if the collection is not being maintained, maybe we need said heavy hand
15:25:56 <abadger1999> samccann: yeah, that's exactly the pros and cons I'm thinking of.
15:26:00 <abadger1999> felixfontein: Outside of the collection.
15:26:28 <samccann> ok thinking out loud - can we envision an active collection that is NOT willing to mark one of their unmaintained modules as orphaned?
15:26:50 <samccann> I can envision an entire collection being 'orphaned', which I think was part of the comments somewhere on this.
15:26:59 <felixfontein> maybe we should distinguish between flagging a module/plugin, and flagging a whole collection
15:27:04 <abadger1999> perhaps if a collection is not naintained... we don't get into individual modules... we get into the collection as a whole.
15:27:10 <abadger1999> <nod> samccann yeah.
15:27:13 <samccann> so perhaps Ansible marks collections as orphaned, but plugin orphan happens within a collection itself?
15:27:22 <felixfontein> samccann: +1
15:27:57 <felixfontein> when something is orphaned inside a collection, there's a process (depending on the collection) to maintain it
15:28:02 <abadger1999> samccann: Perhaps, yeah.... for collections other than c.g... will collections mark modules and plugins as orphaned or will they just deprecate and remove?
15:28:17 <felixfontein> but if a collection is orphaned, things get a lot harder, especially if the collection is outside of Ansible's hands
15:28:59 <samccann> it feels like there's a whole lot of 'the business team needs to decide' on what these mean, when they apply and who applies them
15:29:28 <abadger1999> <nod> business team or "the set of current collection owners" or something like that.
15:29:30 <samccann> am I getting stuck in process here?
15:29:54 <felixfontein> yep. I guess the current feature (plugin/module level) will get mostly used in c.g/c.n
15:30:25 <samccann> is that what is driving this current PR felixfontein ?
15:30:46 <samccann> as in c.g etc have orphaned modules and we want a way to let users know about that now?
15:30:53 <felixfontein> samccann: I'm not sure, you need to ask andersson007_ for that, but from my perspective c.g/c.n will be the main users
15:31:01 <samccann> ok thanks
15:31:14 <abadger1999> It seems like we have a need "Give people the opportunity to become contributors to their favorite plugins when those plugins aren't being maintained anymore" but we don't know what the full audience [collection owners who will be organizing those new volunteers] will want.
15:32:08 <samccann> so to move this PR forward - seems we need at least 2 things:
15:32:22 <samccann> 1. review/discussion from the core team (aka put it on core agenda)
15:32:36 <samccann> 2. review/discussion from the community team (aka put it on community agenda)
15:33:27 <samccann> there's a 3rd aspect there for the business team (aka those handling partners etc)... but I don't know if they have a driving need here, or just need to be aware it's under discussion.  I can't personally envision someone marking a module as orphaned within such a collection..
15:34:22 <samccann> thoughts on ^^ ?
15:34:45 <felixfontein> sounds good
15:35:01 <abadger1999> <nod>  I suppose if business team encompassed ansible paid collection owners and the people working with partners, that would be a definite #3
15:35:09 <felixfontein> I guess part of 1/2 will also be bcoca's proposal, or at least a subset of it
15:35:20 <samccann> <nods to both>
15:35:39 <samccann> #action samccann to summarize our discussion as a comment in the PR
15:36:01 <samccann> ok we are 5 minutes over.  Gonna open the floor
15:36:06 <samccann> #topic Open Floor
15:36:28 <samccann> Anyone have anything they want to bring up? favorite pr/issue? etc? now's the time
15:36:46 <abadger1999> hmmm
15:36:49 <abadger1999> One other thing...
15:37:02 <abadger1999> I don't think orphan and the feature proposal should be conflated.
15:37:05 <felixfontein> I updated the list of collections without changelogs: https://gist.github.com/felixfontein/dc49e25d1bc324f8645d1345c1177552 in 2.10.1 another one will be off the list (netapp.elementsw), but not for 2.10.0
15:37:12 <abadger1999> s/feature/properties/
15:37:56 <abadger1999> Woo hoo, only 17 out of 71 seems like a good percentage for our first time.
15:38:18 <felixfontein> yep. especially since 1 out of these 17 has a changelog (just not one we can automatically integrate)
15:38:27 <samccann> yeah I'm thinking we see a need for orphan flag, let's get agreement on what it means, who marks it, and then the code (in the PR)
15:38:48 <samccann> woot thanks for that list felixfontein !!
15:39:00 <abadger1999> (the reason the orphan and feature proposal seem like they should be different is that the feature proposal is very free-form.  Whereas orphan/retierd/maintained is not.)
15:40:09 <felixfontein> abadger1999: one question about the feature/limitation proposal is how free-form it should be in the end, and how much is standardized
15:40:19 <samccann> we are also basically frozen now right? it being rc1 day.  So those 16 don't get a choice now to be included
15:40:47 <felixfontein> samccann: they could release a new patch version until later today (i.e. before abadger1999 builds 2.10.0rc1)
15:40:55 <felixfontein> but I guess they won't
15:41:01 <samccann> heh. sneaky
15:41:32 <samccann> meanwhile abadger1999 - ping me here when we are ready to do the docs porting guide PR tango. I'll need to find someone w/ merge rights in 2.10 to handle the backport
15:41:45 <samccann> meanwhile meanwhile... shall we end the official meeting?
15:42:21 <felixfontein> I guess so
15:42:29 <samccann> #endmeeting