14:31:37 <acozine> #startmeeting Docs Working Group aka DaWGs
14:31:37 <zodbot> Meeting started Tue Jul 14 14:31:37 2020 UTC.
14:31:37 <zodbot> This meeting is logged and archived in a public location.
14:31:37 <zodbot> The chair is acozine. Information about MeetBot at http://wiki.debian.org/MeetBot.
14:31:37 <zodbot> Useful Commands: #action #agreed #halp #info #idea #link #topic.
14:31:37 <zodbot> The meeting name has been set to 'docs_working_group_aka_dawgs'
14:31:47 <acozine> #topic opening chatter
14:31:49 <acozine> who's around?
14:32:10 <samccann> memememe!
14:32:21 <felixfontein> me :)
14:32:24 <samccann> which looks more like meme meme but anyway
14:32:29 <felixfontein> :)
14:32:37 <acozine> Mr. Barker is on holiday (I won't use his online moniker because I don't want to ping him)
14:32:44 <acozine> #chair felixfontein samccann
14:32:44 <zodbot> Current chairs: acozine felixfontein samccann
14:32:48 <felixfontein> I hope he can relax :)
14:33:16 <acozine> yeah
14:34:31 <acozine> anybody else? abadger1999 andersson007_ baptistemm briantist cbudz cyberpear geerlingguy Jmainguy madonius persysted Pilou?
14:34:48 <Jmainguy> sure ill pay attention =)
14:34:57 <geerlingguy> I'm currently hanging out over at DrupalCon Global, so I'm quite distracted
14:35:08 <acozine> Jmainguy: awesome!
14:35:16 <acozine> geerlingguy: okay, we won't make you furniture today
14:35:16 <cyberpear> o/
14:35:21 <acozine> #chair Jmainguy cyberpear
14:35:21 <zodbot> Current chairs: Jmainguy acozine cyberpear felixfontein samccann
14:35:23 <geerlingguy> haha, thank you
14:35:52 <samccann> ooo DrupalCon
14:36:53 <felixfontein> is https://github.com/ansible/docsite/ a private repo?
14:37:07 <felixfontein> (it looks like it is, because I get a 404)
14:37:11 <acozine> felixfontein: yes, though I'm not sure why
14:37:32 <felixfontein> maybe it contains some webserver internals or credentials
14:37:40 <acozine> it contains the code for the "colored rectangles" landing page and the apache config
14:37:44 <acozine> yeah, could be
14:37:48 <acozine> it's not very exciting
14:38:16 <acozine> are you looking for info on the redirects?
14:38:47 <felixfontein> just wanted to see what's the first agenda entry about, because it says nothing else than ansible/docsite#25 which I can't see :)
14:38:50 <acozine> today's agenda begins with https://github.com/ansible/community/issues/521#issuecomment-656690621
14:38:56 <acozine> ah . . .
14:39:12 <samccann> sorry, added that quickly last week and forgot it wasn't going to be visible
14:39:20 <felixfontein> no problem :) I guess it's about redirects then?
14:39:21 <acozine> here's the PR summary:
14:39:49 <acozine> https://www.irccloud.com/pastebin/rf8N9AQx/docsite%20repo%20PR%2025
14:40:03 <acozine> oops, I forgot to . . .
14:40:11 <acozine> #topic redirects updates
14:40:52 <acozine> in Ansible 2.4 and earlier, module docs lived directly at the top of the docs URL tree
14:40:59 <zbr|ruck> that docs index repo being private came as an issue earlier, maybe we can fix it now
14:41:11 <zbr|ruck> i really doubt there are any corporate secrets there
14:41:50 <felixfontein> I wouldn't make something public without carefully checking it first
14:42:13 <acozine> zbr|ruck: probably not, I'll look through it and also find out who else would need to sign off on making it public
14:42:33 <zbr> acozine: thanks!
14:42:40 <acozine> #chair zbr
14:42:40 <zodbot> Current chairs: Jmainguy acozine cyberpear felixfontein samccann zbr
14:43:14 <cyberpear> I still find it useful st
14:43:23 <acozine> meanwhile, though, the question is whether we still need to redirect the "old pattern" module URLs
14:43:30 <acozine> cyberpear: still find what useful?
14:43:42 <cyberpear> at times to look at docs as early as 2.2
14:43:52 <cyberpear> sorry phone typing
14:43:54 <acozine> we're not removing the older docs
14:44:04 <acozine> we would only be removing the pattern redirects
14:44:30 <acozine> right now if you hit a 2.4-style pattern on either `latest` or `devel` you get redirected
14:44:53 <cyberpear> ok, that's probably fine by now
14:45:00 <felixfontein> acozine: are these redirects complicated, or hurting something?
14:45:16 <acozine> so if you hit docs.ansible.com/ansible/latest/command_module.html you end up at docs.ansible.com/latest/modules/command_module.html
14:45:33 <acozine> felixfontein: they complicate the collection docs, the way they are written now
14:45:45 <felixfontein> acozine: true :)
14:45:55 <acozine> the rule basically inserts "modules/" into any URL that ends with `_module.html`
14:45:55 <andersson007_> hi everyone! can't be here. Feel free to decide something about https://github.com/ansible/community/issues/521#issuecomment-656833594 without me.
14:46:11 <acozine> andersson007_: will do, thanks!
14:46:16 <felixfontein> acozine: but I guess they would be independent, since there should be a second set of redirects from the new-style module URLS to the collection module URLs
14:46:34 <felixfontein> so if you use an old-style URL, you'll first be redirected to the newer URLs, and then to the collection
14:46:34 <acozine> andersson007_: hope you're having fun with whatever you're doing!
14:46:53 <samccann> #info the current redirects are targeted on urls with `latest` or `devel` that use the old 2.4-style url pattern.  This complicates the new collection-based module urls.
14:46:59 <andersson007_> acozine: definitely:)
14:47:09 <acozine> felixfontein: that's one option, we could double-redirect
14:47:15 <samccann> #info the rule basically inserts "modules/" into any URL that ends with `_module.html
14:48:03 <acozine> I'm not . . . enthusiastic about maintaining thousands of redirects, and especially once we have multiple redirect rules, the effects can be unpredictable
14:48:14 <samccann> for me it boils down to - do we need to jump through hoops for these scenarios anymore? We aren't removing 2.4 and if you've bookmarked a 2.4 url it still will work.
14:48:16 <acozine> it took us a while to figure out why the collections docs were all returning 404s
14:48:30 <felixfontein> hmm, I'm assuming this is currently essentially one redirect for oldstyle -> newstyle? (where newstyle is getting old now ;) )
14:48:42 * acozine looks for the regex
14:48:50 <samccann> The only t hing that will stop working is if you bookmarked a url with `latest` or `devel` in it, thinking it was pointing to 2.4. That would become a 404
14:49:17 <acozine> `RedirectMatch permanent "^/ansible/(devel|latest)/(?!modules)(.+_module).html" "/ansible/$1/modules/$2.html"`
14:50:26 <felixfontein> shouldn't this better be `RedirectMatch permanent "^/ansible/(devel|latest)/([^/]+_module).html" "/ansible/$1/modules/$2.html"`?
14:51:03 <acozine> felixfontein: I think that gets into a redirect loop
14:51:15 <felixfontein> otherwise it matches random things in random subdirectories, as long as they don't start with `modules` at the root
14:51:48 <felixfontein> acozine: it shouldn't, since it should only match URLs that aren't in subdirectories of /ansible/devel/ or /ansible/latest/
14:52:05 <acozine> felixfontein: ah, okay
14:52:09 <acozine> regex is not my strong suit
14:52:35 * acozine must stop using American idiomatic speech
14:52:38 <felixfontein> [^/] matches everything but a slash
14:52:43 <acozine> I'm not very good at creating regexes
14:52:45 <Jmainguy> =)
14:53:31 <acozine> felixfontein: generally speaking, you think it's worth maintaining the redirects?
14:53:32 <felixfontein> I don't mind idiomatic speech most of the time
14:53:39 <Jmainguy> regex is hard to write and read for most people, is there any way to do the redirect without a complicated regex, or make it easier to read?
14:54:17 <felixfontein> acozine: at least in the simpler form, I think it would be good to keep it - 2.4 is not that long ago (yet) that URLs from that time can be still around
14:54:29 <felixfontein> simpler and more strict
14:54:36 <acozine> Jmainguy: that's a good question, i don't know
14:54:55 <felixfontein> Jmainguy: is `RedirectMatch permanent "^/ansible/(devel|latest)/([^/]+_module).html" "/ansible/$1/modules/$2.html"` simple enough?
14:55:16 <felixfontein> ah, btw, the . needs escaping
14:55:54 <felixfontein> `RedirectMatch permanent "^/ansible/(devel|latest)/([^/]+_module)\.html" "/ansible/$1/modules/$2.html"`
14:56:00 <Jmainguy> I am a regex nub, so I will end up taking your word for it here. Just throwing out, if you disapeared, is this current format the only format we can proceed with, or is there another way that is easier to maintain
14:56:13 <felixfontein> or `RedirectMatch permanent "^/ansible/(devel|latest)/([^/]+_module)\.html$" "/ansible/$1/modules/$2.html"` even
14:56:29 <Jmainguy> if we must use regex, then I will take your word for how simple the one you decide on
14:57:06 <felixfontein> the original uses a negative lookahead, I consider that more complicated
14:57:10 <felixfontein> (at least in this case)
14:57:16 <acozine> felixfontein: that regex means "any URL that begins with `/ansible/` and has either `devel` or `latest` next , but then has only one slash between that and something that ends with `_module.html` should be redirected to that same thing but add `/modules` before the last part of the URL"
14:57:19 <Jmainguy> felixfontein++
14:57:27 <felixfontein> and the original one can match random paths in subdirectories, as long as they are close enough
14:57:30 <acozine> felixfontein: is that right?
14:57:42 <felixfontein> acozine: exactly
14:57:56 <baptistemm> I'm here
14:58:03 <acozine> baptistemm: welcome!
14:58:06 <acozine> #chair baptistemm
14:58:06 <zodbot> Current chairs: Jmainguy acozine baptistemm cyberpear felixfontein samccann zbr
14:59:00 <felixfontein> the original one redirects https://docs.ansible.com/ansible/devel/hello/what/are/you/_module/html to http://docs.ansible.com/ansible/devel/modules/hello/what/are/you/_module.html
14:59:38 <acozine> yeah, it assumes that anything ending in `_module` is a module doc with that pattern
14:59:46 <felixfontein> (you can also add random stuff at the end of the URL, and are redirected to the same place)
14:59:47 <acozine> and that has been the case, but it might not be the case forever
15:00:11 <acozine> felixfontein: thanks for the update to the regex
15:00:38 <felixfontein> it doesn't even check for ending, as long as there's `_module`, a random character, and then `html` in there, and there isn't `modules` after /ansible/devel/ resp. /ansible/latest/, it matches
15:01:25 <felixfontein> it would even match `/ansible/devel/dev_guide/developing_module/html-is-a-language.html` :)
15:01:33 <acozine> POLL: redirecting old URLs - +1 means "I think it's worth an investment of time to maintain redirects for old module docs URLs" / -1 means "I think we should drop redirects for old module docs URLs"
15:01:41 <cyberpear> considering the possible older links lurking out there, probably good to maintain the redirects, but good to clean it up to be more strict.
15:01:46 <cyberpear> +1
15:02:00 <felixfontein> +1 if the redirect is more strict and doesn't redirect random stuff ;)
15:02:38 <acozine> before we move on, though, I'd like to do a quick poll on the one-step-back question
15:03:03 <baptistemm> +1
15:03:10 <acozine> er, I don't know why that message of mine posted out of order
15:03:17 <samccann> -1  - I think there is a 'cost' to all our redirects and we'll be adding a ton more to get the new collection redirects to work
15:04:08 <acozine> zbr: Jmainguy opinions?
15:04:45 <Jmainguy> computers are fast, im ok with cost =)
15:05:11 <abadger1999> I'd keep it unless it causes problems, then ditch it without qualms
15:05:12 <Jmainguy> less redirects and regex the better though
15:05:26 <acozine> I'm not the best person to be maintaining this stuff, and since I currently have no way to share that pain, I'm -1
15:05:27 <felixfontein> #chair abadger1999
15:05:27 <zodbot> Current chairs: Jmainguy abadger1999 acozine baptistemm cyberpear felixfontein samccann zbr
15:05:30 <Jmainguy> its a mental cost to maintain
15:05:43 <Jmainguy> acozine++
15:05:47 <acozine> but if we can make the docsite repo public, then I'm at 0
15:05:50 <zbr> i would make some redirects but not aim to cover all, a trade-off.
15:06:00 <Jmainguy> zbr++
15:06:30 <acozine> zbr: for the transition to collections, then, what redirects would you support?
15:06:41 <samccann> zbr++  which is why I think dropping redirects for 2.4 is a good point to make that tradeoff
15:06:42 <zbr> also, a very good source of info is google site tools, as they can measure which incoming links you have.
15:07:15 <felixfontein> having a list of explicit redirects is a lot more complicated and harder to maintain than a strict regex IMO
15:07:31 <Jmainguy> felixfontein++
15:08:03 <felixfontein> IMO I'd have either one regex redirect (but definitely not the existing one), or no 2.4-style redirect at all
15:08:06 <abadger1999> I'm fine with dropping the 2.4 redirects now, too
15:08:45 <acozine> it does depend a lot on what we choose for the 2.9 to collections redirects
15:09:11 <acozine> if we redirect all 2.9-style module docs URLs to the main collections landing page, then we can just redirect the 2.4-style URLs there too
15:09:19 <acozine> no sense in having an "intermediate stop"
15:09:21 <felixfontein> shoudln't it be independent of the 2.9 style redirects?
15:09:27 <acozine> it can be, yes
15:09:35 <acozine> but think about this scenario
15:09:54 <acozine> I hit `/ansible/latest/some_module.html`
15:10:13 <acozine> the 2.4 redirect sends me to `/ansible/latest/modules/some_module.html`
15:10:33 <acozine> the 2.9 redirect then sends me to `/ansible/latest/collections/index.html`
15:10:58 <acozine> if that's where I end up, why not just send me there with the first regex?
15:11:20 <felixfontein> I would assume that the 2.9 redirect is more sophisticated and does not simply send people to the list of included collections
15:11:45 <acozine> I think we have a few options for the 2.9 redirects
15:12:17 <abadger1999> (note we haven't figured out how to regex modules/foo_module.html => collections/namespace/collection/foo_module.html )
15:12:20 <felixfontein> I think anything that doesn't at least redirect to the correct collection is not really helping
15:12:32 <felixfontein> abadger1999: I don't think that's possible with regex
15:12:45 <abadger1999> Yeah, that's our conclusion too
15:12:49 <felixfontein> abadger1999: I guess the best solution would be to have a script that converts ansible_base_runtime.yml into a long list of redirects
15:12:52 <acozine> felixfontein: agreed on both counts
15:14:16 <felixfontein> assuming this is a long list of static redirects (i.e. no regex), I would assume (or hope?) that apache should handle it very efficiently
15:14:27 <acozine> would the script need to be embedded in the pipeline and connected to a particular version of the PyPI `ansible` package?
15:15:09 <felixfontein> acozine: I thought ansible_base_runtime.yml is frozen now, so I guess it only needs to be run once
15:15:26 <felixfontein> I'm not sure what exactly frozen means though, if it is frozen for 2.10, or forever
15:15:32 <samccann> or run once for each release of ansible?
15:15:32 <felixfontein> (I thought core team would prefer forever)
15:15:55 <samccann> as in the future, we need to capture when things move out of community.general etc :-)
15:15:57 <acozine> felixfontein: we've asked about performance, and it is apparently not a concern until you reach tens or hundreds of thousands of redirects
15:16:52 <abadger1999> felixfontein: last I asked, the core team prefers forever but I heard that other teams were wanting to update it for every release.
15:16:54 <felixfontein> abadger1999: do you know more about what "frozen" means for ansible_base_runtime.yml?
15:17:01 <felixfontein> ah
15:17:10 <abadger1999> So there will be a "discussion" around it for 2.11, I'm sure.
15:17:32 <cyberpear> if modules move inter- collection it might be good to have redirects for those, too
15:18:03 <cyberpear> like firewalld having moved to ansible.posix from c.g
15:18:05 <felixfontein> cyberpear: but these could be "stub page redirects", i.e. the docs pipeline generates an entry for every runtime.yml redirect entry
15:18:19 <cyberpear> ok, good enough
15:18:34 <felixfontein> that would be good anyway, also for tombstone stub pages
15:19:01 <abadger1999> cyberpear: Yeah.... so we'd need to regenerate the redirects from time to time (every new ansible tarball would keep things updated)  we would probably have to have separate redirects for every branch.
15:19:27 <felixfontein> it will only be a problem if the redirect is removed at some point, but I guess once we're past the pre-2.10 content moving frenzy, inter-collection redirects should stay a lot longer
15:20:31 <felixfontein> abadger1999: if inter-collection redirects are done with stub pages, and only redirects from ansible_builtin_runtime.yml are done via Apache, this should not be complicated
15:21:15 <felixfontein> if it is unclear what I mean with stub pages, something like this: https://docs.ansible.com/ansible/latest/modules/acme_account_facts_module.html
15:22:12 <abadger1999> felixfontein: <nod> It complicates the docs build script a bit but takes advantage of the fact that the docs build already has to process all of that stuff.
15:22:22 <felixfontein> I think this is especially useful for inter-collection redirects, since it actively informs people that content got moved (and things need to be updated in their playbooks/roles)
15:23:37 <abadger1999> felixfontein: AFAIK, deprecation and moving is separate in runtime.yml.  Will we want to do stub pages for both?
15:24:10 <abadger1999> Maybe we need to draw up a list of all the combinations and say what we desire for each one.
15:24:26 <felixfontein> abadger1999: I think so. deprecation and redirect can happen for the same module/plugin: https://github.com/ansible-collections/community.general/blob/main/meta/runtime.yml#L61-L65
15:24:44 <acozine> I'd appreciate a full review of our existing redirects as well - is anyone willing to look at them?
15:24:54 <felixfontein> this is how tombstoning looks: https://github.com/ansible-collections/community.general/blob/main/meta/runtime.yml#L676-L679
15:25:22 <samccann> #info consider stub pages such as https://docs.ansible.com/ansible/latest/modules/acme_account_facts_module.html for when modules move between collections. This gives the user the info that they need to change things
15:25:23 <felixfontein> I think there will be redirect, redirect+deprecation, deprecation, and tombstoning (other combinations do not make sense IMO)
15:25:45 <abadger1999> redirect-only inside the same collection (aka, permanaent alias).  redirect-only to a different collection.  deprecation with no redirect.  deprecation and redirect inide the same collection.  deprecation and redirect to a different collection.
15:25:47 <felixfontein> thought deprecation without redirect doesn't need a stub page, since the module/plugin itself is still there
15:26:26 <abadger1999> ^ I'm going to add that to a wiki page for easy editing.  If you can think of another permutation, mention it now or add it to the wiki page later.
15:26:33 <felixfontein> deprecation with no redirect is already handled now, since that information is already available in the regular module docs
15:26:40 <felixfontein> abadger1999: sounds good!
15:28:32 <acozine> do we need anything else on redirects / regexes / stubs for module docs?
15:29:16 <acozine> I will find out whether we can make that repo public - I'd really appreciate more eyes on the redirects.
15:29:52 <acozine> what's the IRC command I need for "acozine agreed to do this, let's hold her to it in the minutes"?
15:30:41 <acozine> #agreed acozine to investigate whether the docsite repo needs to remain a private repo or not
15:30:45 <samccann> action
15:30:47 <felixfontein> I think it's #action
15:31:10 <acozine> #action acozine to investigate whether the docsite repo needs to remain private or not
15:31:12 <acozine> thansk
15:31:21 <acozine> all right, can folks stay a short while?
15:31:22 <abadger1999> https://github.com/ansible/community/wiki/Docs:Redirects
15:31:27 <felixfontein> hmm, we spend one hour with redirects... wow :)
15:31:32 <acozine> felixfontein: yep
15:31:44 <samccann> #info details on the types of redirects we need to consider - https://github.com/ansible/community/wiki/Docs:Redirects
15:32:20 <acozine> it's a hot topic
15:32:46 <acozine> okay, we have some next steps identified
15:33:03 <acozine> #topic standardizing boolean values
15:33:23 <acozine> https://github.com/ansible/community/issues/521#issuecomment-656833594
15:34:00 <acozine> Mr. Klychkov (again, not pinging him with his nick) has offered to fix these if we come to a consensus
15:34:03 <samccann> #link https://github.com/ansible/community/issues/521#issuecomment-656833594
15:34:29 <acozine> I like using `yes/no` for Booleans everywhere
15:34:35 <acozine> it feels clean and consistent
15:35:20 <felixfontein> it's also fine for me. there might be some options where true/false fit a lot better though (just from a language point of view). and especially programmers sometimes prefer true/false over yes/no
15:35:29 <baptistemm> at least we need a consistent solution
15:35:34 <felixfontein> yep
15:35:49 <baptistemm> felixfontein: I'm rather having a dev pov with true / false
15:36:04 <felixfontein> the main reason to say no to that is to avoid having to review a PR with 10000s of these changes :D
15:36:16 <samccann> yeah everything I see coming from a developer is true/false
15:36:35 <felixfontein> true/false are also the Jinja2 constant names
15:36:48 <baptistemm> true
15:36:50 <baptistemm> :)
15:36:52 <samccann> and as felixfontein mentioned, this depends on the wording of the parameter as well
15:37:21 <samccann> my personal feeling - if we force yes/no, we will be fighting/correcting this for the rest of our ansible careeers
15:37:30 <felixfontein> I guess we should do a poll among more users (and devs) before deciding to stick to one of true/false and yes/no
15:37:32 <samccann> with perhaps better spelling of career
15:37:54 <acozine> samccann: I suspect that no matter what we choose, we will be fighting/correcting the other choice for the rest of our ansible careers
15:38:13 <samccann> i can honestly say I have no recollection of ever seeing a yes/no boolean
15:38:13 <baptistemm> I don't see brining a lot of value on the work that it brings
15:38:24 <felixfontein> samccann: there are a lot :)
15:38:28 <samccann> now I deal primarily with one  group of network developers so that could be why
15:38:39 <felixfontein> yep, that could well be
15:39:10 <samccann> did anyone grep 2.9 and see if one is preferred over the other? (if that's a possible grep )
15:39:54 <acozine> samccann: I think we changed the docs pipeline so it transforms whatever the dev inputs (true/false 1/0 etc.) into yes/no
15:40:07 <acozine> this was maybe 1.5 -2 years ago
15:41:10 <felixfontein> $ grep -RE '\b(yes|no)\b' | wc -l
15:41:10 <felixfontein> 8782
15:41:10 <felixfontein> $ grep -RE '\b(true|false)\b' | wc -l
15:41:10 <felixfontein> 15466
15:41:32 <felixfontein> (current stable-2.9, in lib/ansible/modules/)
15:41:47 <acozine> hm, it was longer ago than I thought: https://github.com/ansible/ansible/pull/30062
15:41:48 <samccann> so not quite double use true/false
15:43:55 <samccann> what's the next step here?
15:44:12 <acozine> hm, we're inconsistent even on that page - https://github.com/ansible/ansible/pull/53273/files
15:46:21 <acozine> it sounds like there are two questions: 1. does it make sense to enforce consistency in the boolean values we display? and 2. if we enforce consistency in boolean values, which pair of values do we want to use?
15:46:49 <acozine> what I'm hearing from this group is 1.: yes and 2.: no consensus
15:46:54 <samccann> what's the impact of this on collections docs being in galaxy etc?
15:47:26 <samccann> (if any).  So if I look at a module in Galaxy/AH and it says true/false, will it say yes/no if I look at it on docs.ansible.com?
15:47:28 <felixfontein> acozine: that was also my impression (and is actually what I feel too ;) )
15:47:32 <abadger1999> Is this display or what we embed?
15:47:44 <felixfontein> abadger1999: I think embed. we already display yes/no
15:47:49 <felixfontein> (or so I thought)
15:48:19 <abadger1999> <nod> That was my understanding too.
15:48:46 <acozine> I think we display yes/no in module docs output, though to samccann's point, I think that happens in the Sphinx pipeine, so it might not apply to Galaxy/AH/other
15:49:19 <felixfontein> ansible-doc shows True/False btw :)
15:49:31 <acozine> but I think there are other places in the docs that still use true/false
15:49:53 <acozine> felixfontein: consistently? or does it reflect the values in the YAML?
15:50:00 <samccann> so we already have a problem then - where docs.ansible.com changes what the developer has and that change doesn't show up anywhere else
15:50:11 <felixfontein> acozine: I think this is the way Python converts these values to strings
15:51:25 <felixfontein> the code uses `str()` to make a default value a string (with hardcoded '(null)' when there is no default)
15:52:35 <abadger1999> samccann: I think it might be that docs.ansible.com changes it to yes/no *and* ansible-doc changes it to true/false.
15:52:54 <abadger1999> I would need to test the latter, though.
15:53:08 <acozine> samccann: it sounds like we have three variations: there's what's written in the YAML docstrings (varies), there's what ansible-doc returns (true/false), and there's what docs.ansible.com returns (yes/no)
15:53:27 <felixfontein> ansible-doc returns True/False, not true/false
15:53:48 <felixfontein> (except in `sample` in RETURNDOCS)
15:54:18 <acozine> ah, right, there's also the Great capitalization Debate
15:54:20 <abadger1999> yes, ansible-doc is converting
15:54:33 <samccann> @acozine  do we know what AH displays? that could be a 4th divergence
15:54:40 <abadger1999> (confirmed the above)
15:54:44 <samccann> or really, I guess matches one of the existing 3 (I hope)
15:55:03 <acozine> I think AH just displays what ansible-doc returns in its JSON
15:55:47 <samccann> AH is showing yes/no for a couple I've found
15:55:48 <felixfontein> (I'm takling about ansible-doc text output, AH probably uses JSON output)
15:55:52 <samccann> but need to see what's in the source
15:56:11 <felixfontein> samccann: some people actually put `'yes'` there, instead of `yes`
15:56:16 <felixfontein> (which IMO is wrong)
15:56:41 <acozine> felixfontein: we had a lot of PRs fixing that (removing quotes from boolean values) about 18 months ago
15:56:45 <samccann> so if I were to info this it would be 'everything possible is happening everywhere'
15:56:52 <acozine> yep
15:56:55 <acozine> wild west
15:58:02 <acozine> for me, consistency would be very nice, but the effort seems quite large compared to the gain right now
15:58:37 <felixfontein> I'm already happy if we get rid of strings instead of booleans in the source :)
15:58:42 <acozine> if we can reach a consensus and Mr. Klychkov is happy to do the work, I think it would be great
15:58:46 <felixfontein> (I'm not sure if validate-modules flags that currently)
15:59:06 <acozine> but we still don't have collections-based module docs ready to go
15:59:12 <acozine> so that has to be my first priority
15:59:18 <samccann> #info ansible.com convertst boolean to yes/now, ansible-doc to true/false - not sure what AH does. And of course the docstrings can be either
15:59:51 <samccann> #info consistency may be difficult to achieve
16:00:07 <cyberpear> I use yes/no in all my roles since it's usually an option the user can answer with yes/no whether they want it
16:00:11 <samccann> the question for me is - should OUR displays all do the same thing? Right now at least two are different
16:00:38 <samccann> seems to me if we are converting what the developer has in the yaml, all our outputs should do the same conversion, but today they aren't
16:00:50 <felixfontein> I agree on that
16:01:47 <acozine> samccann: yes, I think we should be consistent everywhere . . .
16:02:19 <acozine> can we reach consensus on what is the best output option?
16:02:34 <samccann> #agreed we should be consistent in our outputs at least. If we convert to one style (yes/no or true/false) this needs to apply to AH, ansible-doc and docs.ansible.com
16:03:54 <acozine> what is the best way to reach a consensus?
16:03:57 <cyberpear> other ecosystems such as SELinux use on/off for their bool, and those pages might make sense to keep as is... though since YAML parses the bool, you might be in a situation where you have to pick one for display since they all parse to the same thing
16:04:48 <acozine> cyberpear: yeah, I think we will just have to pick one and say "the Ansible ecosystem uses <choice>"
16:05:47 <acozine> because other related ecosystems may be internally consistent, but each one uses a different boolean pair
16:06:05 <felixfontein> out of curiosity: does ansible-lint or yamllint have an opinion on this?
16:06:21 <acozine> felixfontein: good question
16:06:31 <cyberpear> as much as I prefer yes/no, if we really want to future proof, the "new" YAML spec only has true/false. (ansible uses the old spec and will never change, due to hard compatibility break)
16:06:43 <samccann> I believe the y do acozine
16:06:50 <zbr> on what?
16:07:07 <samccann> now whether they have the same opinion I dunno  (on boolean being yes/no or true/false
16:07:24 <zbr> regarding booleans, yes we do. "strict and future proof", adhere to YAML 1.2
16:08:03 <samccann> dunno if this is the rule zbr - https://yamllint.readthedocs.io/en/stable/rules.html#module-yamllint.rules.truthy ??
16:08:04 <zbr> that is what ansible-lint and molecule recommend. only one way to write a boolean.
16:08:19 <zbr> is not ansible-lint role to check YAML, that is yamllint
16:08:35 <acozine> zbr: and that way is to use true/false, lower case?
16:08:40 <felixfontein> and yamllint can be configured
16:08:43 <samccann> as so yaml-lint has that rule, and ansible-lint has its own
16:09:12 <zbr> at this moment ansible-lint does not call yamllintm, it assumes you will do it.
16:09:24 <zbr> we use it, but for internal linting.
16:09:41 <felixfontein> isn't galaxy also using it?
16:09:52 <felixfontein> (or was using it at some point?)
16:09:53 <zbr> i do not know
16:10:36 <zbr> usually I seen their use in parallel because almost for sure, you will also have other yaml files that are not managed by ansible.
16:10:58 <zbr> but i am open to suggestions
16:11:18 <zbr> if someone wants a feature to lint yaml from inside ansible-lint, i would not fight it.
16:12:38 <zbr> but considering that i proposed to use yamllint on ansible code and I was rejected, as they did not see a need to have YAML 1.2 compliant examples.
16:12:56 <zbr> maybe now is the time to be more future-proof.
16:13:05 <samccann> yeah that comes to mind as well (the rejection of yamllint)
16:13:25 <felixfontein> ansible-test is using yamllint
16:13:50 <zbr> i think that the docs team is in a very good position to propose such changes, especially as they are backwards compatible.
16:14:11 <zbr> still all the docs use yes/no almost exclusively
16:14:59 <acozine> the HTML docs pipeline transforms any boolean into yes/no
16:15:28 <zbr> so it would be easier to fix :D
16:16:44 <zbr> TBH, I am not aware of any project using ansible-lint that does not also use yamllint.
16:17:25 <felixfontein> we're already 45 minutes overtime btw
16:17:29 <acozine> yeah
16:17:35 <acozine> also I'm in a second meeting
16:17:39 <acozine> ugh
16:17:49 <acozine> and we had a long agenda
16:18:15 <acozine> I'm not sure what our next steps are for the boolean enforcement question
16:18:23 <acozine> Ask a wider audience for opinions?
16:18:32 <felixfontein> maybe getting awareness and opinions from other teams?
16:18:41 <acozine> felixfontein: sounds good
16:18:53 <acozine> maybe an issue?
16:19:00 <acozine> or a proposal?
16:19:22 <felixfontein> maybe a proposal would be a good idea
16:19:27 <felixfontein> we should use them more often anyway :)
16:19:46 <acozine> #action create a proposal for creating consistency in the boolean values
16:20:27 <acozine> I need to pay attention to Meeting 2
16:20:45 <samccann> I can do a quick open floor and close it out if you want to focus on #2
16:20:51 <acozine> samccann: thanks
16:20:55 <samccann> #Open Floor
16:21:03 <felixfontein> I've one quick question about the ACD changelog :)
16:21:06 <acozine> #topic open floor
16:21:06 <felixfontein> #topic open floor
16:21:08 <samccann> In case anyone has been diligently waiting to voice something
16:21:15 <felixfontein> acozine: jinx!
16:21:22 <samccann> HAHAH
16:21:24 <acozine> heh
16:21:37 <samccann> let's see if anyone else has a tidbit before we go back to changelogs
16:21:44 <samccann> Anyone have something else to bring up?
16:21:45 <acozine> if covid ever ends, I owe felixfontein a beverage
16:22:07 <felixfontein> I've been playing with the ACD changelog a bit, and tried out another grouping: instead of having one section per collection (that has changes), first group by change type, and then by collection
16:22:21 <felixfontein> I've tried this out: https://gist.github.com/felixfontein/7d5efcc70c8a25c218d9e8082f5ee92f#file-changelog-v2-10-style-2-rst
16:22:33 <felixfontein> the old version: https://gist.github.com/felixfontein/7d5efcc70c8a25c218d9e8082f5ee92f#file-changelog-v2-10-style-1-rst
16:22:37 <samccann> #topic changelog output
16:22:46 <felixfontein> (sorry, RST links in gists don't really work :/)
16:23:20 <felixfontein> the v2.10.0a2 entry is probably the most insightful one
16:24:23 <samccann> heh
16:24:36 <samccann> I like the new way.
16:24:55 <felixfontein> also all 'new plugins' and 'new modules' are now collected in one place
16:25:07 <felixfontein> (instead of being spread out)
16:25:22 <samccann> yep
16:25:37 <samccann> I'm good with it
16:25:52 <felixfontein> unfortunately a lot of collections put **all** their modules as "new" ones into the changelog, which makes that section pretty useless for 2.10.0
16:25:57 <samccann> #info changelog output now groups by change type  (minor, major, etc) and then lists by collection
16:26:17 <samccann> yeah can't help that really
16:26:20 <felixfontein> I mainly want to know which style you prefer, and if you have other suggestions/ideas to make it even better
16:26:39 <felixfontein> for the ones that already released with a changelog and them mentioned, it's too late anyway
16:26:41 <samccann> I'll ping acozine after the meeting to get a closer look, but yep
16:26:55 <felixfontein> well, I could add a blocklist to kick out everything that we know was redirected, but I'd like to avoid that
16:27:36 <samccann> yeah.
16:27:43 <samccann> so anything else before we close out the meeting?
16:27:49 <felixfontein> from my side, no
16:27:58 <samccann> going once...
16:28:02 <felixfontein> actually I'm heading for the kitchen now ;)
16:28:06 <samccann> lol
16:28:11 <samccann> ok thanks felixfontein
16:28:18 <samccann> ending now
16:28:21 <samccann> #endmeeting