18:00:03 <felixfontein> #startmeeting Ansible Community Meeting
18:00:03 <zodbot> Meeting started Wed Jun 29 18:00:03 2022 UTC.
18:00:03 <zodbot> This meeting is logged and archived in a public location.
18:00:03 <zodbot> The chair is felixfontein. Information about MeetBot at https://fedoraproject.org/wiki/Zodbot#Meeting_Functions.
18:00:03 <zodbot> Useful Commands: #action #agreed #halp #info #idea #link #topic.
18:00:03 <zodbot> The meeting name has been set to 'ansible_community_meeting'
18:00:03 <felixfontein> #topic Agenda https://github.com/ansible/community/issues/645
18:00:03 <felixfontein> acozine andersson007_ baptistemm bcoca briantist cyberpear cybette dericcrago dmsimard felixfontein geerlingguy gundalow gwmngilfen ikhan_ jillr jtanner lmodemal misc nitzmahone resmo samccann tadeboro cidrblock thaumos zbr: ping!
18:00:07 <felixfontein> #info Agenda: https://github.com/ansible/community/issues/645 / Topics: https://github.com/ansible-community/community-topics
18:00:10 <felixfontein> #topic Updates
18:00:48 <samccann> o/
18:01:11 <DonNaro[m]> o/
18:01:21 <acozine> o/
18:01:31 <felixfontein> #cair samccann DonNaro[m] acozine
18:01:38 <felixfontein> #chair samccann DonNaro[m] acozine
18:01:38 <zodbot> Current chairs: DonNaro[m] acozine felixfontein samccann
18:01:41 <felixfontein> typing is hard :)
18:01:57 <acozine> heh
18:02:33 <acozine> im finishin lunch, so typing with onw hand
18:03:09 <felixfontein> I just finished dinner ;-)
18:03:55 <felixfontein> #info Ansible 5.10.0 got released
18:04:12 <felixfontein> so far this looks a bit like a copy of the docs meeting ;-)
18:04:14 * acozine wipes plate, types with both hands again
18:04:18 <acozine> heh
18:04:53 <acozine> sorry, BTW, for missing last week - the corona virus (or one of its friends) finally found me
18:05:39 <samccann> 5.10 is also EOL now :-) publishing the eol banner as we speak
18:05:47 <feyo[m]> o/ just gonna lurk today for real
18:06:06 <felixfontein> acozine: it's totally ok to not be around! anyway I hope you've fully recovered!
18:06:09 <felixfontein> #chair feyo[m]
18:06:09 <zodbot> Current chairs: DonNaro[m] acozine felixfontein feyo[m] samccann
18:06:28 <felixfontein> #info Ansible 5 is now End of Life
18:06:35 <felixfontein> samccann: good point :)
18:06:48 <acozine> felixfontein: thanks, I'm feeling much better
18:08:02 <felixfontein> that's great to hear!
18:09:31 <felixfontein> is there anything you folks want to discuss today?
18:09:59 <acozine> I don't have anything. It's summer, things are pretty quiet.
18:10:29 <samccann> oh gosh there was something I was going to bring up... thinking... thinking...
18:10:38 <felixfontein> I'm still waiting for more feedback on the licensing discussion (https://github.com/ansible-community/community-topics/issues/112), I'll probably have to more directly bug the folks I want feedback from :)
18:10:41 <samccann> oh now I remember
18:11:11 <samccann> I wanted to ask what steps we should start taking so we eventually get to the point where every collection has to run docs CI to verify docs/plugin docs
18:11:50 <samccann> so related to https://github.com/ansible-community/community-topics/issues/111
18:12:17 <samccann> but specifically getting folks to use the stuff briantist created and you are using in community.general now I think
18:12:27 <felixfontein> #topic Better CI for Ansible docs that are not part of ansible-core
18:12:30 <briantist> o/
18:12:33 <felixfontein> #info https://github.com/ansible-community/community-topics/issues/111
18:12:36 <felixfontein> #chair briantist
18:12:36 <zodbot> Current chairs: DonNaro[m] acozine briantist felixfontein feyo[m] samccann
18:13:08 <felixfontein> samccann: that stuff only tests docs coming from collections, but not the Ansible docs in ansible/ansible that aren't part of ansible-core
18:13:48 <samccann> yeah I specifically wanted to ask just about the collection stuff for now as that's a long-term project to get us from 1100 build warnings to 'something managable'
18:13:49 <mariolenz[m]> o/
18:13:55 <felixfontein> #chair mariolenz[m]
18:13:55 <zodbot> Current chairs: DonNaro[m] acozine briantist felixfontein feyo[m] mariolenz[m] samccann
18:14:27 <felixfontein> for all GH based collections that are actively developed on GH, using briantist's reusable workflow is probably the best thing to do
18:14:32 <samccann> so I guess I should start with - do we agree that collections 'at some future point' MUST NOT add docs build warnings
18:14:47 <felixfontein> but then there are a few collections that either aren't developed on GH, or that only get one commit per release on GH
18:15:01 <remindbot[m]> @cybette:ansible.im cyb-clock chimes every 15 minutes during the community meeting
18:15:29 <samccann> #info only GH-based collections actively developed on GH can use the reusable docs CI workflow.
18:15:52 <felixfontein> I'm wondering whether it could happen that new warnings are unavoidable
18:15:57 <samccann> so let's start with that batch then - how do we get to the point where the build warnings can be zero?
18:16:16 <felixfontein> if that cannot happen, I fully agree that they MUST NOT add new ones from some point in the future on
18:16:16 <bcoca> felixfontein: as long as you dont make it a rule for inclusion, they will be
18:16:19 <acozine> samccann: I would support that restriction, and yes, starting with the easiest use cases makes sense
18:16:27 <samccann> felixfontein: I bet it's possible, yeah. there's got to be some chicken/egg problems that pop up
18:17:00 <bcoca> a) make rule, b): enforce rule c) cleanup legacy rule violations
18:17:20 <felixfontein> bcoca: I mean that there might be edge-cases where it is impossible to avoid a new warning, even if everyone tries very very hard
18:17:21 <bcoca> ^ if you dont follow the order , might as well not make rule cause new violations will creep in
18:17:28 <samccann> But I guess it depends on whether they are unavoidable. I guess if c.g added a new module at the same time c.n did and they wanted to cross-reference each other, that's a chicken/egg that couldn't be resolved
18:17:37 <bcoca> felixfontein: why all rules have 'exception' aka 'ignores'
18:18:19 <samccann> so maybe the first step(s) are:
18:18:20 <samccann> 1 - open issues against collections with build warnings to get them fixed
18:18:31 <bcoca> its just that we had a lot of these kind of chagnes in core, and never succeeded till we followed that pattern
18:18:34 <felixfontein> managing such ignores is non-trivial since the components that most likely will add warnings come from different repos, and any commit to one of these repos can add or remove warnings
18:19:13 <felixfontein> samccann: that's a good thing, especially when there are instructions on how to fix them and how to detect them :)
18:19:17 <samccann> bcoca: hmm interesting.  so we woudl then start with the rule - your collection cannot add build warnings..
18:19:25 <bcoca> yes, interdependant disparate repos make this a lot more 'fun'
18:19:49 <bcoca> samccann: yes, but it really starts when you enforce it, otherwise they'll keep adding
18:20:24 <samccann> well I'm thinking we can have some kind of manual 'exception' rule or agreement - we review 'unresolvable' build warnings and if we agree, we allow it with a remediation plan .. like 'these will be resolved when xx happens'
18:20:40 <bcoca> once enforced (you ensure no new ones creep in) you can start process of cleaning up, otherwise its like trying to pump out water from basement while water main is still wide open
18:20:40 <briantist> we might be focusing a bit too much on edge cases, a bit too early imo, when improving most of the issues and keeping them in a good state is pretty doable
18:20:58 <bcoca> its just basic plubming, first you cut off water, then you fix teh pipes, tehn you clean basement
18:21:39 <samccann> so there are two ways new warnings come - changes to an existing collection, and new collections.
18:21:51 <samccann> I can review new collections and start nagging about build warnings as i see them.
18:22:18 <mariolenz[m]> <samccann> "yeah I specifically wanted to..." <- Is it possible for me to see those warnings, do you have a link?
18:22:19 <samccann> but there's already over 1k
18:22:38 <samccann> mariolenz: they pop out when you do a local build. I can put it up on a pastebin I think.
18:23:38 <felixfontein> I saw we have a new collection inclusion candidate, we could do a test docs build there and see whether it results in warnings :)
18:24:21 <samccann> yeah that's what I'm trying to do, but I need help ;-) maybe after the meeting I'll ask on the docs channel
18:24:30 <samccann> meanwhile https://pastebin.com/5WHGyRDX is a recent docs build with all the warnings
18:25:10 <samccann> and looks like it got truncated but you get the drift
18:26:11 <samccann> so it sounds like maybe the first step is to open issues against all those collections with warnings, with their specific dump of warnings, and how to test vi briantist's stuff to validate their fixes.
18:26:40 <samccann> then see how fast (or slow) the warnings start dropping down. But what do we do for collections that just ignore it all?
18:27:25 <briantist> if their collection is on GitHub, we can ask them to implement the docs workflows, even if we don't require it, we can offer the carrot of "this will help the inclusion reviewers get through the process faster", if nothing else
18:27:47 <mariolenz[m]> apropos, what should we do about collection that don't react on issues / prs from the steering committee? I've opened https://github.com/CiscoDevNet/ansible-aci/pull/298 two weeks ago to fix https://github.com/CiscoDevNet/ansible-aci/issues/278 (opened nearly two months ago) but nobody from cisco seems to care.
18:27:50 <briantist> it would save the time of building their docs locally (as a reviewer), and would put them in a good place whether they are included or not
18:29:04 <samccann> briantist: what's the beset way to get that out to collection owners? I think it might already have been in the bullhorn, so is it better to open an issue in each collection. 'Add CI to validate docs' with a description/pointer on how to do it.. and then copy that issue in every collection?
18:29:22 <samccann> s/beset/best/g
18:30:00 <remindbot[m]> @cybette:ansible.im cyb-clock chimes every 15 minutes during the community meeting
18:30:12 <briantist> actually not sure if I've put it in the bullhorn yet, but it can be announced again. We could open an issue, or even open a PR
18:30:13 <acozine> it might be useful to create a page somewhere with "fixes for common docs errors"
18:30:21 <acozine> that you could point collection owners to
18:30:32 <felixfontein> mariolenz[m]: directly pinging the maintainers might help
18:30:48 <felixfontein> mariolenz[m]: also I would add some docs validation to that PR, otherwise they can easily break the docs and not notice
18:31:19 <briantist> by PR, I meant a PR to implement the docs build, not one to fix their docs issue :)
18:31:44 <acozine> samccann: because a lot of the errors in the pastebin are repeated many, many times, and the maintainers may not know much (if anything) about sphinx
18:32:48 <felixfontein> briantist: the problem with adding workflows to other repos is that they only run in the repo once merged, so basically adding such a workflow first breaks CI, and then they need to unbreak it (and hopefully not by disabling the workflow)
18:32:56 <acozine> so a cheatsheet might help them, and might also motivate them to fix their errors more quickly and more cheerfully
18:33:00 <briantist> yes that's true
18:33:27 <samccann> acozine: very true. I'll add that to the list
18:33:37 <felixfontein> I can also add some code to antsibull-docs that escapes the backticks that some folks put into their module/plugin docs. that way we'll have some less warnings
18:33:40 <DonNaro[m]> samccann: I feel like it might also be worth capturing some of this in the contributor's guide, esp the section around "verifying your docu PR". it might even be possible to hook that into PRs as a polite reminder.
18:34:07 <DonNaro[m]> acozine: cheatsheet is a prob a better idea than contrib guide in fairness
18:34:28 <samccann> Don Naro: true. The existing verifying your doc PR is specific to manual rst files in ansible/ansible repo.
18:38:01 <samccann> ok cool, thanks! At least I have a starting point now. sorry to hog most of the meeting w/ this ;-)
18:39:07 * felixfontein just created six PRs adding briantist's docs PR workflow to collections
18:39:20 <acozine> Don Naro: linking to this material from the contrib guide is a great idea, no matter what the page gets called
18:39:21 <briantist> 🤑
18:39:53 <acozine> w00t!
18:40:06 <briantist> felixfontein: you can ping me on those too, so I can subscribe and look to help out in case there are any issues or questions
18:40:57 <samccann> yeah can you ping me on at least one so I can have a look and maybe point to them for other collection owners to use as an example of how to do it?
18:42:03 <felixfontein> I'll also ping you in the follow-up PRs which will be more interesting, since it's only then that the workflow will actually run ;)
18:42:31 <briantist> right :)
18:44:04 <mariolenz[m]> not to put too fine a point on it, but could / should we have a ci that checks that the documentation is ok for new ansible community releases?
18:44:36 <acozine> I would argue strongly that we should
18:44:45 <acozine> without documentation, software is much harder to use
18:45:00 <remindbot[m]> @cybette:ansible.im cyb-clock chimes every 15 minutes during the community meeting
18:45:11 <acozine> but mariolenz it sounds like you have another perspective?
18:45:11 <samccann> depends on the definition of 'ok'
18:45:46 <felixfontein> I'm not sure how such a test should work
18:45:46 <samccann> So yes, we should have an RC version of Ansible 7 when the time comes, but the devel docs ARE the upcoming release docs and are available nightly.
18:46:09 <felixfontein> in the sense of: how to determine whether it passes or fails?
18:46:10 <samccann> afaik there isn't a CI test that could show for example, that community.general module docs are all missing right now. That's a manual check.
18:46:35 <mariolenz[m]> acozine: i would also argue that we should, but how can we implement this?
18:47:20 <samccann> but having 1.1K build warnings right now means it's impossible to tell when something new pops up. I suppose I could manually diff the warning output...
18:47:58 <acozine> mariolenz: that's what briantist 's work is helping us do, by running tests in collections
18:48:24 <briantist> little different acozine , because that stuff can only detect stuff from the POV of the individual collection
18:48:35 <briantist> but not the whole set of docs at once
18:48:50 <briantist> which can have some issues that only occurs in that context
18:49:11 <briantist> but I do hope it will help for the bulk of issues that originate in individual collections
18:50:23 <samccann> question for the hive mind - is there 'something' we could add to a jenkins job that takes the build results and puts them out publicly?
18:51:12 <samccann> i'd have to look and see if there's any secret sauce in the console output of the docs jenkins nightly builds, but that's one way to make it public what's happening every night.  Of course more helpful when we get those warnings down from 1.1k :-)
18:51:18 <briantist> I suppose since it's just rendered static HTML, you could put them up to any place that could host that. A dedicated GitHub repo with GH pages would be public and easy
18:51:34 <briantist> oh I see, you mean the output not the rendered docs
18:51:40 <briantist> well.. same answer though ;)
18:51:44 <samccann> so the html pages are already available.. the devel docs
18:52:03 <mariolenz[m]> btw, should we add "breaks documentation" as a removal criteria for collectionsor do we already have this yet?
18:52:20 <samccann> we don't have that yet, no mariolenz
18:52:42 <samccann> long term, I'd like to get to that point once the CI tests are implemented across most collections  (where possible)
18:53:43 <samccann> but  to be honest, ansible hasn't ever had perfect doc builds, other than when acozine and i worked hard to get them to zero. Even then, problems snuck in and we'd have to play wacamole to get it back to zero.
18:54:26 <samccann> ansible/ansible CI tests don't find the sphinx build warnings per PR. They find a whole LOT of other things for sure, but not the batch of warnings we're talking about here.
18:54:27 <felixfontein> mariolenz[m]: I'm for that! are you interested in composing something or that? :)
18:56:28 <acozine> We can give collection maintainers a break while they work to eliminate existing errors. If we can get a good CI system in place, then I'd be happy to say "breaking the docs is grounds for removal"
18:56:53 <mariolenz[m]> felixfontein: We would need a test for this before we could make this a requirement, wouldn't we ;-)
18:57:31 <felixfontein> mariolenz[m]: definitely! but having something like 'we told you it breaks docs, and you ignored us too long, thus we remove your collection' is nice to have ;)
18:57:39 <DonNaro[m]> samccann: just thinking about your jenkins question and maybe GH actions is a better route: https://github.com/marketplace/actions/sphinx-build
18:57:40 <DonNaro[m]> maybe we could combine that with github pages for public build?
18:58:59 <DonNaro[m]> there are also some very promising looking GH actions to lint RST
18:59:04 <samccann> Don Naro: okay maybe between the two of us we can create something that works? I know we can't add more 'depth' to existing ansible/ansible CI if it's going to lengthen the CI test times.
18:59:30 <DonNaro[m]> count me in
18:59:30 <samccann> Don Naro: existing ansible/ansible CI does use rstcheck.
19:00:56 <felixfontein> `antsibull-docs lint-collection-docs` also runs rstcheck on the extra docsite RST files
19:02:11 * gotmax[m] realizes he forgot about this meeting :(
19:02:37 <felixfontein> #chair gotmax[m]
19:02:37 <zodbot> Current chairs: DonNaro[m] acozine briantist felixfontein feyo[m] gotmax[m] mariolenz[m] samccann
19:02:43 <felixfontein> unfortunately it's time to close it!
19:02:46 <felixfontein> any last words?
19:03:12 <gotmax[m]> Yeah, I know
19:03:38 <gotmax[m]> I can answer questions about the SPDX change if anyone has any
19:03:40 <samccann> thanks for all the help!
19:04:16 <acozine> thanks, folks, and Happy Independence Day to those in the US!
19:04:42 <felixfontein> thanks everyone!
19:04:45 <felixfontein> #endmeeting