15:08:32 <acozine> #startmeeting Docs Working Group aka DaWGs
15:08:32 <zodbot> Meeting started Tue May 25 15:08:32 2021 UTC.
15:08:32 <zodbot> This meeting is logged and archived in a public location.
15:08:32 <zodbot> The chair is acozine. Information about MeetBot at http://wiki.debian.org/MeetBot.
15:08:32 <zodbot> Useful Commands: #action #agreed #halp #info #idea #link #topic.
15:08:32 <zodbot> The meeting name has been set to 'docs_working_group_aka_dawgs'
15:08:39 <acozine> thanks, zodbot!
15:08:43 <felixfontein> yay :)
15:08:45 <acozine> #topic opening chatter
15:08:56 <acozine> #chair samccann gundalow felixfontein cyberpear
15:08:56 <zodbot> Current chairs: acozine cyberpear felixfontein gundalow samccann
15:09:07 <acozine> #chair lmodemal
15:09:07 <zodbot> Current chairs: acozine cyberpear felixfontein gundalow lmodemal samccann
15:09:19 <acozine> who else is around?
15:09:56 * dericcrago waves
15:09:56 <acozine> #info we now have an #ansible-docs channel on irc.libera.chat
15:09:59 <acozine> #chair dericcrago
15:09:59 <zodbot> Current chairs: acozine cyberpear dericcrago felixfontein gundalow lmodemal samccann
15:10:21 <acozine> pending the community decision tomorrow, I expect we will move to libera for next week's meeting
15:10:55 <acozine> if we do, I will post daily updates here, pointing folks to the new location
15:10:59 <samccann> #info pending the community decision tomorrow, we may move to libera for next week's meeting. We will post details here when that decision is made
15:11:11 <acozine> and will post a reminder at the start of next week's meeting in case anybody comes here instead
15:12:28 <samccann> cool.
15:12:40 * samccann scrambles to remember how to add a new network and register nick etc
15:12:57 <felixfontein> it's fortunately not that complicated
15:13:05 <samccann> yeah just gotta google the magic.
15:13:25 <felixfontein> https://libera.chat/guides/registration
15:13:43 <felixfontein> they fortunately have some guides :)
15:13:56 <acozine> woopsie, no agenda for today!
15:14:03 <acozine> we'll make it up on the fly
15:14:14 <samccann> doh!  that means I forgot to post minutes as well?
15:14:29 <acozine> maybe so, last week was a marathon meeting
15:15:07 <acozine> #topic Jinja2 upgrade issue
15:15:11 <acozine> this one's purely informational
15:15:39 <acozine> we had an outage last week on the 2.9 documentation
15:16:04 <acozine> the docs build "succeeded" but many of the modules failed to build
15:16:39 <acozine> this was related to changes in Jinja2, changes that happened to come out in the Jinja2 3.0 release
15:17:01 <samccann> ok I created a quick agenda - https://github.com/ansible/community/issues/579#issuecomment-847958129
15:17:13 <acozine> we republished the docs with an older build, and are fixing it "the right way" now
15:17:15 <samccann> (copy of the old one so may not be that helpful)
15:17:24 <acozine> thanks samccann
15:17:48 <acozine> having users report an outage we didn't even notice is . . . less than ideal
15:18:09 <felixfontein> hmm, looks like I never added the links I wanted to the agenda yesterday :)
15:18:14 <acozine> hm, I guess this isn't purely infromational
15:18:22 <acozine> because we have a proposal
15:18:28 * samccann whispers meeting minutes are also posted now from last week - all about that version specific url
15:18:38 <acozine> heh
15:18:43 <acozine> so here's the proposal:
15:19:26 <acozine> we have a quarterly process of reviewing/testing updates to all external docs-build dependencies (like jinja2 and sphinx)
15:19:51 <acozine> once a quarter we try to build the docs with no version restrictions on dependencies
15:20:03 <acozine> we find and fix as many issues as we can
15:20:36 <acozine> and then we put an upper bound on those dependencies in `docs/docsite/requirements.txt` so the build will run on known-good versions
15:20:40 <felixfontein> is this something you want to do in the future, or what you are already doing?
15:20:46 <acozine> then next quarter we do it again
15:20:52 <acozine> felixfontein: kind of a mix
15:21:32 <acozine> we've had some version restrictions in the past - sometimes in `docs/docsite/requirements.txt`, sometimes in the Jenkins build (which doesn't help anyone who's building docs locally)
15:21:44 <acozine> so this isn't a totally new approach
15:22:19 <acozine> but we've never scheduled reviews of dependency versions before . . . that should help us keep more up to date
15:22:37 <acozine> I think we can schedule them in DaWGS and call them . . .
15:22:38 <samccann> yeah it's a balance between moving forward, but not having surprise breaks and a scramble to fix them
15:22:43 <acozine> wait for it . . .
15:22:46 <acozine> DaWGs Unleashed
15:22:50 <samccann> AAHAHAHAHAHA
15:22:55 <lmodemal> lol
15:23:01 <felixfontein> I like that proposal
15:23:30 <felixfontein> it's probably also a good idea to rework the jenkins process to use a venv with exactly the same versions as specified in docs/docsite/requirements.txt, and nothing else
15:23:35 <felixfontein> that would make it more reproducable
15:23:38 <acozine> with your PR on the Sphinx issue felixfontein I think we can pin the versions of all our docs dependencies at the current latest
15:23:49 <samccann> felixfontein - yeah that's what we normally do
15:23:51 <acozine> yes, Toshio and I started working on that last Friday
15:23:57 <samccann> right now we have a hack in there to fix last week's problems
15:23:58 <felixfontein> awesome!
15:24:52 <samccann> do we info the proposal? or just vote and put an agreed on what we plan on doing
15:25:39 <acozine> one or the other, for sure
15:25:50 <acozine> we need to document our documentation's documentation
15:26:02 <acozine> sorry, I'm feeling a little punchy today
15:27:16 <acozine> #info proposed plan for preventing dependency surprises: pin dependencies to latest known good versions in `docs/docsite/requirements.txt`, schedule quarterly reviews in DaWGs where we "unleash" the versions and fix any issues that come up
15:27:23 <acozine> hm, did that info?
15:27:48 <felixfontein> it should
15:28:13 <samccann> #info and then pin to the new tested versions so we don't have a docs outage like we had last week
15:28:21 <samccann> time for a vote?
15:28:38 <acozine> please vote in favor of or against the proposal ^^^
15:28:39 <acozine> #chair
15:28:39 <zodbot> Current chairs: acozine cyberpear dericcrago felixfontein gundalow lmodemal samccann
15:28:42 <acozine> +1
15:28:43 <felixfontein> +1
15:29:10 <lmodemal> +1
15:29:47 <samccann> +1
15:29:50 <cyberpear> seems fine as long as it only affects docs generation and isn't shipped to users, but I generally prefer to specify a minimum version
15:30:40 <acozine> cyberpear: it would be shipped to users in the sense that they would have access to `docs/docsite/requirements.txt` and we document using that to create a local environment for building the docs
15:30:42 <samccann> cyberpear - good point. Should we also specify a minimum version? As I recall, there is some minimum version of antsibull that will no longer build the docs well
15:31:08 <samccann> or is that just getting too cautious?
15:31:13 <cyberpear> can we ship a lock file with the "known good" versions and leave requirements.txt to float w/ only known breakages?
15:32:43 <abadger1999> +1
15:32:58 <abadger1999> Oh.... the pins....
15:33:06 <acozine> what would that look like? we'd have `docs/docsite/requirements.txt` with no limits (or rare limits) and then `docs/docsite/versioned_requirements.txt` for times when we need a tried-and-tested set of versions?
15:33:13 <abadger1999> it's planned to be major versions?  Or patch versions or something in the middle?
15:33:45 <acozine> my thought was to set an upper bound on exactly the version we tested at the most recent quarterly test
15:33:56 * abadger1999 changes his vote to a tentative -1
15:33:58 <samccann> good question abadger1999 - if we are uber cautious, it would be patch version that we specifically tested with
15:34:50 <abadger1999> There's tradeoffs and the cost and benefit are both highest setting the upper bound to the last tested.
15:34:56 <abadger1999> So it's a tough call to make.
15:35:03 <acozine> so, assuming we have a good fix for the most recent Sphinx issue, we would specify Sphinx 4.0.2 until August
15:36:04 <acozine> the benefit is "no surprise problems", what is the cost?
15:37:56 <samccann> one cost that comes to mind - someone who builds multiple docsites and when they get to ansible, it forces them to a lower patch release than what they are on
15:37:56 <abadger1999> Pros and cons of using the last tested version: Pro: We know that the docs won't start mysteriously failing for a reason unrelated to any updates we make. Con: System packagers and other people building docs in a controlled environment could have difficulty building the docs because they could be standardizing on a newer version than we have pinned.
15:38:12 <cyberpear> the cost is build failures for distros building the docs in the packaging system when the distro has 4.0.3 but we've pinned 4.0.2
15:38:21 <samccann> #info Pros and cons of using the last tested version: Pro: We know that the docs won't start mysteriously failing for a reason unrelated to any updates we make. Con: System packagers and other people building docs in a controlled environment could have difficulty building the docs because they could be standardizing on a newer version than we have pinned.
15:38:41 <felixfontein> cyberpear: if you don't run the `pip install -r requirements.txt` step, it shouldn't fail?
15:38:42 <cyberpear> hence, I'd prefer to ship both a "lock file" with the exact versions and a floating file only limiting known-broken versions
15:38:44 <abadger1999> I think those are the benefits and costs of pinning any upper bound; but they're the most costly and benefit-y if we make the upper bound an exact version.
15:38:56 <samccann> maybe we upper bound it to the major.minor and see how that goes?
15:39:38 <samccann> i want to say one of the reasons 2.9 broke last week is because it had a different `requirements.txt` than devel
15:40:05 <acozine> cyberpear: ah, so the scenario you're thinking of is, I've got Ansible installed on Fedora as a package, the default version of sphinx on my version of Fedora is 4.0.3 but Ansible docs build wants 4.0.2
15:40:11 <samccann> if they were the same, the nightly build would either have failed, or devel would have problems in the docs and someone might have noticed before a release doc was updated?
15:40:15 <felixfontein> samccann: you mean stable-2.9 had a different requirements.txt file, or Jenkins had a different one?
15:40:29 <abadger1999> <nod> Yeah.  That lets some things potentially slip through (bugs in the upstream libraries that get triggered by our docs) but it gives the package maintainers enough flexibility that they won't trip over it most of the time.
15:40:36 <samccann> stable-2.9 did if I recall. acozine and abadger1999 did most of the investigating
15:41:22 <acozine> samccann: it was a problem only in 2.9 because of the changes made to the docs build when it was extracted to antsibull - the code there handles this specific scenario better
15:41:39 <samccann> this was that state of the requirements files - https://hackmd.io/y2eXd6t0SLCbHP5tVz4uWA#ansible-root-requirementstxt
15:42:03 <samccann> and yeah, 2.9 wasn't pinned for sphinx so it grabbed 4. .. amongst other problems.
15:42:32 <abadger1999> samccann: That's possible but it wasn't the case for the jinja2 issue I looked into.  2.10+ use antsibull to build the docsite and I normalized data before templating it there.  The normalization means we didn't trigger the bug that stable-2.9 had in jinja2.
15:42:47 <samccann> ah gotcha
15:43:12 <abadger1999> I think sphinx would have triggered if that was updated.... Let me look at whether devel was pinning a specific version of that but stable-2.9 wasn't
15:43:17 <acozine> I'm still trying to understand cyberpear's scenario
15:43:45 <samccann> abadger1999 yes devel, 2.11, 2.10 are all pinned for sphinx, 2.9 isn't
15:44:17 <acozine> is the pinned version a problem for package maintainers? for users? for both?
15:44:21 <samccann> cyb-clock-clone sez we are 44 minutes into the meeting and this topic
15:44:26 <cyberpear> my scenario is that I have only a newer version of a dep available to me (due to corporate security concerns  for example) and the build will fail if the dep is pinned to an exact earlier version
15:44:58 <samccann> so we could do < 4.0  but not < 4.0.1?
15:45:01 <abadger1999> samccann: Yeah, so you are correct that the sphinx issue wouldn't have triggered if the requirements.txt file was in sync.
15:46:10 <acozine> cyberpear: so as a user when you do `pip install docs/docsite/requirements.txt`, you'd get an error saying pip can't find a version that meets both Ansible's requirements and the distro requirements?
15:46:19 <acozine> and be unable to build the docs?
15:46:43 <cyberpear> acozine: essentially, yes
15:47:32 <cyberpear> my preference would be to leave the requirements.txt unpinned, but have a pinned version that the live docsite can use to avoid any breakage due to deps
15:47:55 <acozine> I'm fine with shipping two files and letting users go wild west if they want or need to, as long as I have some way to test upgrades before they break our automated builds
15:48:18 <samccann> ah so cyberpear is suggesting we pin only in jenkins so we never break docs.
15:48:31 <samccann> publishing docs ^^
15:48:40 <samccann> but let the source be unpinned.
15:48:47 <felixfontein> :+1:
15:49:06 <samccann> on the plus side, those of us working in the docs will sure notice when something goes south!
15:49:07 <acozine> I think cyberpear is suggesting we ship something like `docs/docsite/requirements.txt` with no pins, plus something like `docs/docsite/known-good-versions.txt` with pins
15:49:20 <samccann> on the negative side, we are left unable to test locally until we find said problem
15:49:22 <cyberpear> samccann: yes, but it's fine to also ship a pinned-requirements.txt for folks who have the flexibility of using the exact versions in case it breaks
15:49:26 <cyberpear> acozine++ yes, exactly that!
15:49:28 <acozine> then in Jenkins we use `known-good-versions` and let users decide which one they want to use
15:49:39 <samccann> ah interesting
15:49:52 <samccann> the pros are obvious, anyone see cons to this approach?
15:50:19 <acozine> that still keeps the process public (process of deciding/updating what the known good versions are) and it protects the docs build
15:50:33 <acozine> it also gives users pointers if they run into things that break
15:51:34 <abadger1999> I like it.
15:51:43 <acozine> +1 for this implementation
15:51:59 <samccann> Shall we propose so it shows up in the meeting minutes?
15:52:10 <samccann> or if it's not too late, undo the last proposal?
15:52:11 <acozine> thanks cyberpear for persisting and explaining
15:52:16 <acozine> heh
15:52:38 <cyberpear> 👍 thanks for not kicking me out :P
15:53:14 <acozine> this is why we like having diverse perspectives, it helps make the whole process better
15:53:27 <acozine> let's see, what exactly did we vote on?
15:54:30 <acozine> VOTE: revise previous proposal to implement a "two-file solution" so users can choose to install known-good versions or any version
15:54:33 <acozine> +1
15:54:37 <cyberpear> +1
15:54:49 <samccann> +1
15:54:55 <abadger1999> +1
15:55:06 <samccann> #info VOTE: revise previous proposal to implement a "two-file solution" so users can choose to install known-good versions or any version
15:55:07 <felixfontein> +1
15:55:15 <lmodemal> +1
15:55:34 <acozine> dang, between parliamentary rules and zodbot, this meeting thing is complicated!
15:55:36 <acozine> thanks samccann
15:55:47 <acozine> #chair
15:55:47 <zodbot> Current chairs: acozine cyberpear dericcrago felixfontein gundalow lmodemal samccann
15:55:54 <acozine> anybody else want to vote?
15:56:24 <acozine> okay, hearing none . . . .
15:57:29 <acozine> #agreed we will include both an unpinned `requirements.txt` file and a pinned `known-good-versions.txt` (exact name of the second file TBD) in `docs/docsite` for visibility and flexibility, then use the pinned file in Jenkins to avoid surprises
15:57:56 <acozine> and once again a "quick topic" has turned out to be less quick than I expected . . . for good reasons!
15:58:06 <felixfontein> :)
15:58:18 <acozine> #topic collection docs stuff
15:58:19 <felixfontein> happens a lot also in the community meetings ;)
15:58:22 <acozine> heh, yep
15:58:28 <acozine> so breadcrumbs I think are done
15:58:46 <samccann> cyb-clock-clone says we have 2 minutes left in the meeting
15:59:13 <acozine> see https://docs.ansible.com/ansible/latest/collections/community/mysql/index.html#plugins-in-community-mysql for an example
15:59:17 <felixfontein> since breadcrumbs are active again, I'd agree
15:59:24 <abadger1999> :-)
15:59:39 <acozine> the build is stable, too, so I think that's one big checkmark for the DaWGs
15:59:52 <acozine> what about collections-based "extra" docs?
16:00:03 <acozine> are we ready to merge https://github.com/ansible-community/antsibull/pull/255?
16:00:06 <felixfontein> from my POV, it's ready :)
16:00:14 <felixfontein> but I guess abadger1999 has to comment on that :)
16:00:25 <abadger1999> I reviewed it yesterday and felixfontein updated everything.  It's ready to merge.
16:00:41 <acozine> abadger1999: what about https://github.com/ansible-community/antsibull/pull/255#issuecomment-847199266?
16:01:00 <felixfontein> acozine: https://github.com/ansible-community/antsibull/pull/255#issuecomment-847259826
16:01:09 <acozine> that's the only comment I see that isn't marked resolved
16:01:14 <abadger1999> felixfontein: If you want to squash and merge it yourself, I'd be happy with that.... we may want to keep some of hte intermediate states (like the save-to-memory vs read-twice behaviour) so I didn't want to squash it via the github interface.
16:01:24 <samccann> need to drop for another meeting.. I'll try to keep one eye here as well
16:01:27 <acozine> ah, that was just a GitHub thing then
16:01:30 <acozine> felixfontein: thanks
16:01:54 <felixfontein> abadger1999: the commits in the PR will stay, so I'm fine with just squashing everything
16:01:56 <acozine> thanks samccann
16:02:04 <felixfontein> abadger1999: but if you prefer I can squash it into smaller parts
16:02:10 <abadger1999> Yeah, that was an overall comment that I didn't associate with a line number so github displays it differently.
16:02:41 <abadger1999> felixfontein: I would prefer smaller parts if you're okay taking the time to do that.
16:03:02 <abadger1999> That way all the information is in git without having to consult github.
16:03:24 <acozine> I'm +1 to merge, we've talked about this one for a long time and made some improvements
16:03:27 <acozine> time to put it to work
16:03:41 <felixfontein> abadger1999: ok, I'll work on that later today. which states would you like to keep?
16:05:01 <abadger1999> felixfontein: I think that keeping the content in memory vs reading twice is the only thing I'd like to preserve in history.
16:05:46 <abadger1999> I don't foresee us needing to revisit any of the other things later.
16:05:52 <felixfontein> abadger1999: ok, I'll split it up then
16:06:00 <abadger1999> (If you see something else, you can feel free to keep it, though :-)
16:06:04 <abadger1999> Thanks :-)
16:06:14 <acozine> \o/
16:06:15 <abadger1999> Feel free to merge afterwards; you don't need to wait on me again :-)
16:07:10 <acozine> #info breadcrumbs work is done, breadcrumbs are live on the site, and the build is creating them reliably
16:07:40 <acozine> #info collections "extra docs" will be added this week
16:07:51 <acozine> #agreed https://github.com/ansible-community/antsibull/pull/255 is ready to merge
16:07:57 <felixfontein> :)
16:08:07 <acozine> okay, quick open floor
16:08:16 <acozine> then I need to join another meeting in progress
16:08:22 <acozine> #topic open floor
16:08:39 <acozine> all questions, comments, suggestions, ideas, critiques welcome
16:09:05 <felixfontein> FYI: I've started working on automatic role documentation extraction in https://github.com/ansible-community/antsibull/pull/272
16:09:21 <felixfontein> (the PR currently includes 255, once 255 is merged and this is rebased I'll un-WIP it)
16:09:35 <acozine> cool
16:09:57 <felixfontein> there's at least one collection in Ansible which would benefit from this (namely sensu.sensu_go): https://ansible.fontein.de/collections/sensu/sensu_go/index.html#role-index
16:10:33 <acozine> nice~
16:10:44 <acozine> er, that was meant to be a !
16:11:45 <acozine> onward and upward
16:12:27 <felixfontein> :)
16:13:01 <acozine> I don't think we will ever include roles-only collections in Ansible, but folks with roles-only collections could use this to generate their own docsites
16:13:56 <acozine> and it's good to allow included collections to document roles along with plugins
16:14:16 <acozine> any other open floor items?
16:15:12 <abadger1999> Not from me
16:15:16 <felixfontein> nothing from my side either
16:15:28 <acozine> and no newcomers are speaking up yet
16:15:51 <acozine> all right, thanks everybody!
16:16:06 <acozine> see you next week, probably on libera
16:16:07 <lmodemal> Thanks everyone!
16:16:12 <acozine> look for updates here AND there
16:16:16 <abadger1999> See you all next week; same Bat Time, different Bat Channel!
16:16:20 <acozine> heh
16:16:36 * acozine wonders if she can quickly make an ascii-art bat
16:16:44 <acozine> probably not . . .
16:16:49 <acozine> #endmeeting