14:31:16 <acozine> #startmeeting Docs Working Group aka DaWGs
14:31:16 <zodbot> Meeting started Tue Aug 18 14:31:16 2020 UTC.
14:31:16 <zodbot> This meeting is logged and archived in a public location.
14:31:16 <zodbot> The chair is acozine. Information about MeetBot at http://wiki.debian.org/MeetBot.
14:31:16 <zodbot> Useful Commands: #action #agreed #halp #info #idea #link #topic.
14:31:16 <zodbot> The meeting name has been set to 'docs_working_group_aka_dawgs'
14:31:20 <acozine> #topic opening chatter
14:31:22 <acozine> who's around?
14:31:34 <samccann> chatter chatter pumkin matter
14:31:40 <felixfontein> hi!
14:31:46 * samccann seldom makes sense...even in her own head
14:31:51 <acozine> #chair samccann felixfontein
14:31:51 <zodbot> Current chairs: acozine felixfontein samccann
14:32:00 <acozine> hi felixfontein!
14:32:22 <acozine> I think baptistemm is on holiday, even though he shows up as active on my IRC client
14:33:05 <felixfontein> abadger1999 is probably still asleep
14:33:17 <acozine> andersson007_: gundalow briantist cyberpear geerlingguy jhawkesworth Jmainguy madonius mrproper Pilou tremble zbr you folks talking docs today?
14:33:28 <acozine> felixfontein: yeah, at least i hope so
14:33:28 <felixfontein> (he was still awake 4 hours ago)
14:33:32 <acozine> oh jeez
14:33:34 <felixfontein> yep :)
14:33:37 * gundalow waves
14:33:42 <acozine> I REALLY hope he's asleep then
14:33:47 <acozine> hi gundalow
14:33:49 * tremble waves hello
14:33:50 <acozine> #chair gundalow
14:33:50 <zodbot> Current chairs: acozine felixfontein gundalow samccann
14:33:53 <acozine> hi tremble
14:33:56 <acozine> #chair tremble
14:33:56 <zodbot> Current chairs: acozine felixfontein gundalow samccann tremble
14:33:57 <zbr> o/
14:34:02 <acozine> hi zbr
14:34:04 <acozine> #chair zodbot
14:34:04 <zodbot> Current chairs: acozine felixfontein gundalow samccann tremble zodbot
14:34:20 <acozine> hey, that wasn't what I expected TAB to do!
14:34:25 <acozine> #chair zbr
14:34:25 <zodbot> Current chairs: acozine felixfontein gundalow samccann tremble zbr zodbot
14:34:34 <acozine> how do I unchair the bot?
14:34:41 <tremble> You put zodbot in charge of itself, hopefully it doesn't become self aware...
14:34:42 <felixfontein> #unchair zodbot
14:34:42 <zodbot> Current chairs: acozine felixfontein gundalow samccann tremble zbr
14:34:42 <acozine> or is this The Singularity being set in motion?
14:34:48 <felixfontein> maybe?
14:34:51 <samccann> dun da DUN DUN!!
14:35:01 <acozine> felixfontein: thanks
14:35:08 <acozine> tremble: exactly
14:35:18 <jhawkesworth> Sorry not today
14:35:29 <acozine> jhawkesworth: cool, catch you next time
14:36:01 <acozine> today's agenda starts with https://github.com/ansible/community/issues/521#issuecomment-672038948
14:36:31 <samccann> The first two items are really together in the Agenda. I copied felixfontein's item up into it
14:36:43 <felixfontein> ah, ok :)
14:36:51 <acozine> sneaky!
14:37:07 <samccann> yeah made sense in my head last night... but anyway
14:37:07 <acozine> #topic release coordination
14:37:32 <samccann> what are all the moving pieces?
14:38:08 <felixfontein> so what happens for a release (to my knowledge): 1) ansible 2.10.x is released, 2) porting guide needs to be merged to devel, 3) porting guide needs to be backported to stable-2.10, 4) docs need to be rebuild (including module/plugin docs)
14:38:19 <felixfontein> at least these are the pieces I know about :)
14:38:30 <samccann> what about changelog.rst update?
14:38:42 <felixfontein> and 1) consists out of 1a) build ansible package, 1b) check in build data and changelog to ansible-build-data repo, 1c) upload ansible to pypi
14:38:55 <samccann> ah ok
14:39:06 <acozine> do we need some kind of double-check on the List of All Included Collections and Versions?
14:39:12 <samccann> so could we pause before 1c and do 2,3,?
14:39:46 <felixfontein> I'm not sure, maybe 4) needs 1c) to be done
14:39:56 <samccann> or I guess we just have to tighten up 2,3,4 right after 1c?
14:39:59 <acozine> yeah, it feels like 2 and 3 should happen before the pypi package goes out
14:40:12 <acozine> docs should be in place, if possible, before anyone can use the new version
14:40:45 <samccann> yep. though perhaps with alpha, it's okay to lag a day? but actual patch releases shouldn't lag if possible
14:40:50 <felixfontein> hmm, would be helpful if abadger1999 would be around now, since he's very familiar with the relation between 1c) and 4)
14:41:20 <felixfontein> for the last alpha, the lag was more like half a week (at least for the porting guide)
14:41:26 <samccann> heh woopsie
14:41:36 <acozine> I think we can build the docs independently as long as we know which collections are included
14:41:46 <felixfontein> yeah, the was first a RH holiday coming up and then a weekend...
14:41:52 <felixfontein> bad timing ;)
14:41:55 <samccann> so I think 'something' in the ansible release process republishes docs. is that corrext acozine?
14:42:12 <felixfontein> then 4) probably depends on 1b)
14:42:13 <samccann> (in the old process)
14:42:55 <acozine> in the old process, the jenkins job that built the release package triggered the build_ansible_docs job
14:43:11 <samccann> what I'm thinking is - everything is in place in docs before the package goes to pypi
14:43:24 <felixfontein> samccann: that would be great
14:43:47 <samccann> yeah so if we eventually have something similar for the New Ansible, then we just have to get everything in place and backported on time
14:43:52 <abadger1999> Because 2.10 has an rc, we can probably build the module and plugin docs ahead of time
14:44:01 <acozine> welcome abadger1999
14:44:04 <acozine> #chair abadger1999
14:44:04 <zodbot> Current chairs: abadger1999 acozine felixfontein gundalow samccann tremble zbr
14:44:25 <felixfontein> morning abadger1999!
14:44:32 * abadger1999 just woke up and doing morning things but sorta here from his phone
14:44:51 <felixfontein> but we have the same problem for 2.10.1, 2.10.2 etc, which probably won't have RCs?
14:45:05 <felixfontein> also, the porting guide between RC and final release is substantially different
14:45:26 <felixfontein> (the final 2.10.0 one will have all alpha/beta/rc version sections collapsed)
14:45:33 <samccann> yep
14:45:49 <acozine> does the release process all happen on the same day? can we interrupt it briefly to take care of porting guide/changelog stuff?
14:46:05 <samccann> #info what happens for a release (to my knowledge): 1) ansible 2.10.x is released, 2) porting guide needs to be merged to devel, 3) porting guide needs to be backported to stable-2.10, 4) docs need to be rebuild (including module/plugin docs)
14:46:17 <samccann> #info  1) consists out of 1a) build ansible package, 1b) check in build data and changelog to ansible-build-data repo, 1c) upload ansible to pypi
14:46:26 <abadger1999> Yeah, porting guide and things generated as part of the build have a chicken and egg issue
14:47:26 <abadger1999> Right now, in building and uploading ansible from my laptop rather than Jenkins so i can pause before 1c
14:48:19 <samccann> what prevents the porting guide from being generated ...say a day earlier and backported?
14:48:45 <abadger1999> Once it's automated, I'm not sure if that will be possible (but I have so many things in trying to get done by release, automation is a thing that may fall to a later enhancement)
14:49:13 <samccann> so porting guide generation is part of that build then?
14:49:49 <acozine> as long as we know the names and versions of the collections, can't we generate the changelog and porting guide ahead?
14:50:03 <acozine> do we expect collection changes "down to the wire"?
14:50:13 <samccann> perhaps for changelogs?  dunno
14:50:35 <samccann> but yeah, sounds like a solid FREEZE is needed a couple of days at least in advance
14:51:02 <abadger1999> Yeah, part of building the ansible tarball is generating the changelog and porting guide
14:51:06 <felixfontein> we could split the release process in two parts, where the first part only creates the metadata, and the second part is using the current 'rebuild' command to actually build the package
14:51:29 <abadger1999> Felixfontein: yeah, that could work
14:51:33 <samccann> the other option - we have prior notice of exactly when the package is released.  Then docs grabs the prs, merge, backport, republish (say a 4 hr window to get it all done, in case jenkins or shippable is havin a moment)
14:51:45 <abadger1999> Thanks for writing the rebuild command! ;-)
14:52:07 <felixfontein> abadger1999: it would basically be chopping things out, and adding a --date option which allows to say when the release date actually is (because it won't be today anymore)
14:52:10 <felixfontein> abadger1999: yw ;)
14:53:55 <samccann> so... the build with just metadata would generate changelogs and porting guide? so we could merge and backport them?
14:53:57 <abadger1999> We could also move towards making releases a"bitflip".. everything gets built ahead of time but doesn't get pushed into production until a set date
14:54:13 <acozine> ooh, I like that idea
14:54:36 <acozine> though I have no idea how easy or hard it would be to implement
14:54:53 <abadger1999> The problem is i know how bit flip will work for building the ansible tarball but i haven't thought about how docs would do that
14:54:56 <samccann> would it matter that the info would be on devel ahead of time? (assuming we turn on the nightly devel build again for docs)?
14:55:29 <samccann> i guess in general it always is...
14:55:44 <acozine> hmm, devel will be the next 2.x thread, not the next 2.10.y thread
14:56:21 <felixfontein> well, porting guide does through devel right now, because devel also contains the 2.10 porting guide
14:56:26 <felixfontein> (which regularly leads to confusion)
14:56:32 <acozine> heh
14:56:40 <samccann> I'm not sure what a bit flip is, but seems if everything is done, then the only thing docs needs is someone or something to kick the jenkins build for 2.10
14:57:14 <acozine> we'll need to make sure the changelog/porting guide PRs get merged and backported first
14:57:32 <samccann> yes. that all happens ahead of the bitflip.
14:58:07 <acozine> but it would make our lives much easier, I think . . . which gets me wondering if it would make someone else's life much harder
14:58:33 <samccann> so literally, everything is in place.  Then at a set date/time, toshio does the bit flip (and someone republishes 2.10)
14:58:48 <acozine> that would be awesome
14:59:23 <acozine> as long as we have some advance notice, we can ensure someone is here to kick off and confirm the republish job on Release Day
14:59:33 <felixfontein> sounds reasonable
14:59:46 <samccann> yep. I think so long as there isn't an emergency (HAH) it would all work
14:59:57 <abadger1999> The to-be-released content has to be stored somewhere. In our jenkins setup, that may be an issue... (I was also hoping to do all the release work using things the community could see (so GitHub actions instead of jenkins) and that wouldn't have a place to store things either :-/ )
15:00:31 <samccann> abadger1999 - how often in the past has 'something last minute' happened to make an ansible release or dot release go down to the wire?
15:01:04 <acozine> does PyPI have some way to say "turn this previously uploaded release candidate into a Real Release"?
15:01:10 <felixfontein> abadger1999: doesn't the metadata in ansible-build-data suffice? I guess we can already push it there
15:01:21 <acozine> in other words, could we store the to-be-released content on PyPI?
15:01:29 <acozine> and do the bit-flip there?
15:01:29 <felixfontein> abadger1999: or do you want to store the tarball somewhere as well?
15:02:13 <samccann> so my guiding principal here - Docs should go out within hours of a release
15:02:29 <felixfontein> I would prefer hours *before* a release :)
15:02:35 <abadger1999> For the dot oh releases, we've usually said that a new rc was needed (although docs can merge certain things in that window still).  So the last minute stuff doesn't exist.
15:02:37 <felixfontein> (or minutes)
15:02:53 * abadger1999 switches to laptop so he can type faster
15:02:56 <samccann> heh. yeah within minutes would be great. but imo within hours is acceptable
15:03:07 <felixfontein> except that the porting guide now changes between rc and dot oh
15:03:21 <felixfontein> samccann: true :)
15:03:41 <samccann> yes, rc to true release is tricky, but all the dot releases after that shouldn't be right?
15:04:06 <felixfontein> they also get new porting guide entries
15:04:22 <samccann> yep
15:04:28 <felixfontein> but it's just something appended (assuming collections don't modify changelog entries in the past)
15:04:59 <abadger1999> acozine: I thnk pypi can let me upload something and then manually mark it as invisible.  Then I can manually mark it as visible later.  I canno rename an rc to final there.
15:05:28 <acozine> well, I hate to introduce manual steps into the process
15:05:28 <felixfontein> I hope the "manually" part can be automated
15:05:36 <acozine> but it would solve this particular problem
15:06:29 <abadger1999> felixfontein: For the bitflip idea (bitflip comes from the idea that each permission in UNIX (like read permission) is a bit.  And you're flipping the bit from off to on)  I prefer to have the tarball stored already and ideally the docsite built and stored too... then both are just uploaded to their final destinations on release day.
15:06:36 <felixfontein> https://sourceforge.net/p/pypi/support-requests/428/ looks like hiding isn't working well and was planned to be removed (at least in 2014)
15:06:55 <acozine> docs team could take the responsibility for marking it visible once the docs are up
15:07:08 <felixfontein> abadger1999: yep, that would be best (just think of galaxy happens to have an outage on release day)
15:07:11 <abadger1999> felixfontein: :-(  Thanks for that info.
15:07:21 <felixfontein> abadger1999: but maybe that changed again
15:07:49 <felixfontein> it's hard to find anything on it
15:08:06 <abadger1999> <nod>
15:09:49 <acozine> do we have ideas for next steps, or full-on action items?
15:10:04 <abadger1999> So to implement bitflip, I guess something like a jenkins build that stores everything on the web server in a directory that is non-executable.  Then on release day, the ansible tarball from there is uploaded to pypi and the docs directory in there replaces the live 2.10/ directory.
15:10:38 <abadger1999> Do we know if shanemcd is okay with us using the webserver like that?
15:10:44 <felixfontein> #action felixfontein add a `--release-date` option to the build process (for the changelog's build date)
15:11:00 <acozine> abadger1999: I don't know
15:11:19 <acozine> #action acozine to ask shanemcd about using the webserver for pre-release storage
15:11:23 <abadger1999> Cool.
15:11:51 <abadger1999> Are you folks okay with not being able to review the web docs prior to release day?
15:12:05 <samccann> woof
15:12:07 <abadger1999> (We can tweak the process I outlined above if you want to be able to look)
15:12:13 <acozine> can't we publish them to the test site?
15:12:22 <abadger1999> Instead of using permissions to hide it, it could just be security via obscurity.
15:12:31 <abadger1999> We publish to the test site.
15:12:43 <acozine> yeah, I like that better
15:12:46 <abadger1999> You just wouldn't see the actual final artifact.
15:12:51 <abadger1999> (if we use permissions)
15:13:21 <samccann> fwiw - this our publication checklist - https://github.com/ansible/ansible/issues/70783
15:14:05 <acozine> #action acozine to ask shanemcd about adding simple auth to the testing site, with the password printed for all to see, along with a warning about this being a testing site
15:14:30 <samccann> so we'll have to decide if we need all of that in place before release (on both devel and 2.10/latest)
15:14:57 <samccann> then the 'final artifact' is just if something goes wonky with the docs pipeline pulling from galaxy
15:14:59 <abadger1999> So plan not using permissions: New jenkins job(s) that build the ansible tarball and docssite to pre-production locations on the ansible web server.  People can browse or download if they are "in the know" and want to test the gold artifacts.  They'll be uploaded to pypi and moved into the real docs.ansible.com locations (the 2.10 directory in this csae) with a simple jenkins job on release day.
15:15:06 <samccann> which is a big something but still ...
15:16:03 <samccann> ah so it won't be rebuilding the docs on release day, it's just moving those existing files that we presumably already sanity checked in preproduction, to the final 2.10 dir?
15:16:46 <acozine> sounds good to me - we will no doubt learn from the first experience and we can hone the process for the next release
15:17:42 <acozine> #info 2.10.0 release will use new jenkins job(s) that build the ansible tarball and docssite to pre-production locations on the ansible web server.  People can browse or download if they are "in the know" and want to test the gold artifacts.  They'll be uploaded to pypi and moved into the real docs.ansible.com locations (the 2.10 directory in this csae) with a simple jenkins job on release day.
15:18:07 <acozine> #info revisit this in a retrospective after the release, improve, iterate
15:18:42 <abadger1999> samccann: That would be my preference.  it could be built on release day, though.  a few nice things about pre-building: deploying becomes a matter of minutes instead of of 1 hour+ no matter how slow the actual build takes.  We can tell ahead of time if the docs build would fail, instead of on release day)  A drawback: The docs will reflect the data from whenever the docs were last built to the pre-release location.  So a last
15:18:43 <abadger1999> minute docs fix wouldn't be reflected unless the docs were rebuilt before hand.
15:19:00 <abadger1999> (that could become part of your last minute fix checklist, though)
15:19:58 <samccann> yeah I'd rather we just moved the prerelease files to their final directory. That way the only margin of error is that move step, vs repulling everything from galaxy etc
15:20:32 <abadger1999> Yep.
15:21:38 <acozine> felixfontein: you put the porting guide PRs on the agenda, is there anything about those that we need to talk about, and haven't talked about yet?
15:21:55 <felixfontein> oh nice, the first collection managed to include a changelog.yaml that is invalid and lets the generator crash
15:22:05 <abadger1999> #action abadger1999 to look into the jenkins jobs to build ansible and docs to a staging site and bitflipping.
15:22:06 <acozine> head . . . mett desk
15:22:09 <felixfontein> acozine: no, that's basically it
15:22:10 <acozine> s/mett/meet
15:22:20 <felixfontein> nice to meet you, desk!
15:22:43 <felixfontein> acozine: mett -> https://en.wikipedia.org/wiki/Mett
15:23:11 <abadger1999> #action abadger1999 to update https://github.com/ansible/community/wiki/RelEng:-ansible with additional steps that the ansible release process entails now
15:23:16 <samccann> omgosh my aunt would have loved that! (the mett)
15:23:19 <acozine> oh, goodness, it's a bit early in the day here for raw pork
15:24:11 <acozine> though that should be the DaWGs version of "seeing the sausage get made"
15:24:25 <samccann> HAHAHAHA
15:24:26 <acozine> "Time to make the mett for this release"
15:24:29 <felixfontein> #action felixfontein make sure changelog generation does not crash on degenerate changelog.yaml files
15:24:47 <samccann> omgosh raw pork and degenerates... we're ROCKIN IT today!
15:25:16 <samccann> in theory, we have 5 minutes left
15:25:17 <abadger1999> #actio Hee hee
15:26:06 <felixfontein> :D
15:26:23 <acozine> #topic process/pipeline updates
15:27:16 <acozine> other than the "kids today" state of collections changelogs, any updates on the process or pipeline?
15:27:45 <acozine> I ran the build last night and only got 7 Sphinx warnings, which was fewer than I feared
15:27:49 <felixfontein> nothing new from my side
15:28:30 <samccann> omgosh only 7!!! was that devel or stable2.10?
15:28:38 <acozine> devel
15:29:11 <acozine> you and I can test 2.10 later today
15:29:30 <acozine> abadger1999: anything new with redirect?
15:30:04 <acozine> er, redirects
15:30:08 <abadger1999> Nope.  I've been swamped.  I've been getting about 1 days worth of work in on it a week (less last week with the recharge day)
15:30:08 * acozine can't type today
15:30:22 <acozine> np
15:30:35 <abadger1999> freeze and beta1 is this week so it will be about the same this week too.
15:30:35 <acozine> you're doing tons of work
15:30:59 <abadger1999> Yeah, sorry, though.  I know it's a blocker and we don't want blockers to also become nail-biters.
15:31:50 <acozine> yeah, but context-switching doesn't help . . . let it wait while we sort out other things
15:32:23 <acozine> #topic open floor
15:32:58 <acozine> all topics, comments, questions, ideas welcome
15:33:09 <samccann> omgosh we hit open floor only 2 min late!!! That's like a record for 2020 right there
15:33:13 <acozine> heh
15:33:30 * acozine sings We Are the Champions quietly under her breath
15:34:01 <felixfontein> :)
15:34:19 <acozine> if anyone has been waiting quietly for a chance to ask a question or bring up a subject, now would be a great time!
15:34:46 <acozine> I'll toss a quick update in while the floor is open . . .
15:35:22 <acozine> Ansibot has run through open PRs and issues, closing ones that apply to plugins that have moved to collections
15:35:29 <acozine> it didn't eliminate many docs PRs
15:35:35 <acozine> but it did close quite a few docs issues
15:37:14 <acozine> hearing nothing else for the open floor . . .
15:37:31 <samccann> it would be nice if we could filter docs PRs that are only docs... to know what our backlog really is
15:37:33 <acozine> agenda items are always welcome at https://github.com/ansible/community/issues/521
15:38:12 <acozine> samccann: we can look at "PRs by file/directory"
15:38:31 <acozine> hm, though would that filter out PRs with more files?
15:38:34 <acozine> I don't know
15:39:05 <acozine> #info anyone can add an agenda item to https://github.com/ansible/community/issues/521
15:39:30 <acozine> #info and questions are encouraged at any time in the chat channel
15:40:09 <acozine> thanks abadger1999  felixfontein gundalow samccann tremble zbr
15:40:16 <felixfontein> thanks everyone! :)
15:40:19 <acozine> and anyone else who followed along at home!
15:40:28 <acozine> #endmeeting