15:02:23 <samccann> #startmeeting Documentation Working Group aka DaWGs
15:02:23 <zodbot> Meeting started Tue May 31 15:02:23 2022 UTC.
15:02:23 <zodbot> This meeting is logged and archived in a public location.
15:02:23 <zodbot> The chair is samccann. Information about MeetBot at https://fedoraproject.org/wiki/Zodbot#Meeting_Functions.
15:02:23 <zodbot> Useful Commands: #action #agreed #halp #info #idea #link #topic.
15:02:23 <zodbot> The meeting name has been set to 'documentation_working_group_aka_dawgs'
15:02:39 <samccann> #topic opening chatter
15:02:44 <samccann> @room Meeting time! Who is here to talk the docs?
15:02:55 <samccann> Raise your ascii hand (o/) to say hi or any other way you want to let us know you are here. And Welcome to any new folks!
15:03:11 <BlaisePabon[m]> (I'll be slipping in and out of DaWGS due to a conflict with $DAYJOB)... (full message at https://libera.ems.host/_matrix/media/r0/download/libera.chat/2263aad6cdfdd212aa999304bf7e5aaf66558d1a)
15:03:48 <orandon[m]> o/ but also have a conflict
15:03:56 <tremble> o/
15:04:16 <ompragash[m]> o/
15:04:16 <tremble> (About, but in another meeting too)
15:04:23 <samccann> Blaise Pabon: Yeah sounds like a good idea. I think in general we need to 'get started' on multiple levels. The general one Don Naro is working on now, and then for each of the main pieces of the Ansible pie, we should have a good walkthrough on the basics.
15:04:39 <samccann> #chair Blaise Pabon Don Naro ompragash tremble
15:04:39 <zodbot> Current chairs: Blaise Don Naro Pabon ompragash samccann tremble
15:04:43 <BlaisePabon[m]> Hi, my name is blaise and I haven't been to a meeting in a few years.
15:04:43 <BlaisePabon[m]> ...it's been 5 days since I last ssh'd into production.
15:04:59 <samccann> lol welcome back then!
15:05:26 <samccann> briantist: you around to talk docs today?
15:05:38 <BlaisePabon[m]> Oh! hey, my meeting got moved so I have 30 mins
15:05:40 <briantist> oh hey, yeah I'm sort of here
15:05:49 <samccann> #chair briantist
15:05:49 <zodbot> Current chairs: Blaise Don Naro Pabon briantist ompragash samccann tremble
15:06:11 <samccann> ok let's get going then
15:06:18 <samccann> #topic Documentation updates
15:06:40 <samccann> #info Ansible 2.9 and 2.10 are officially EOL for community.
15:06:58 <samccann> means we won't patch the docs on those anymore
15:07:44 * samccann she sez jinxing herself that something really bad will need fixing
15:08:07 <briantist> haha
15:08:08 <samccann> #info need help - https://github.com/ansible/ansible/issues/77908 python package on RHEL/centos for kerberos.
15:08:36 <samccann> Mostly I want so know if folks think the summary in that docs issue is correct
15:09:04 <samccann> (aka installing python-devel on rhel/centos/fedora is actually installing python3-devel or some variant of that)
15:09:53 <samccann> I tried locally and seems RHEL 8 has to be installing python3-devel and it will pick up whatever is the current python version.
15:12:05 <BlaisePabon[m]> python3 is all the modern stuff
15:12:39 <BlaisePabon[m]> (says the fedora guy)
15:12:56 <samccann> yeah the tricky part - installing python-devel still works on fedora.. it just installs python3-devel. On RHEL (8) it doesn't work. Has to be install python3-devel.
15:13:12 <samccann> But figured I'd ask folks to take a quick look to be sure I wasn't missing anything thanks!
15:13:43 <samccann> so imma say we change it to install python3-devel since that works on both (and i'd assume on centos.. don't have that handy to test at the moment)
15:14:24 <samccann> ok onto another topic...
15:14:32 <samccann> #topic community docs writers project
15:14:45 <samccann> #info - working on a community docs project board to coordinate across a group of volunteer community writers
15:15:14 <samccann> So the idea here - we have a good handful or more of writers looking to get some opensource experience
15:16:11 <samccann> These folks can come in and review docs PRs and do some basic Edit on Github work. It would be grammar type edits since they don't know Ansible at this point.
15:16:30 <samccann> But tremble  - I'm thinking they could have done the PR review you requested here earlier.
15:16:53 <samccann> This isn't the 'permanent' project board - I need to move it to a different github org, but I'm thinking something like this - https://github.com/orgs/ansible/projects/92
15:17:20 <samccann> And then you'd just add your request there and select whether it is a PR review or an edit on github kind of issue etc.
15:17:59 <tremble> Yup, someone good at the word-smithing side, but light on the Ansible/Dev side would be perfect and exactly what I was after.
15:18:25 <samccann> cool! I'm hoping once I get this all set up, other collection owners can take part.
15:18:26 <BlaisePabon[m]> Ok, I see. Yes, there is a python-devel  but that is 2.7 legacy python.
15:18:26 <BlaisePabon[m]> Explicit is better than implicit. `python3-devel` FTW
15:18:45 <samccann> Blaise Pabon: great thanks!!
15:20:05 <samccann> #topic Archive docsite
15:20:19 <samccann> #info will move older docsets to an archive site. At what point do we move more recent EOL docs over once it is set up? https://github.com/ansible-community/community-topics/issues/78#issuecomment-1072535541
15:21:13 <samccann> I mentioned this before but we want to move the old docs (definitely say 2-3 - 2.8) to an archive site. This would change the urls (and thus remove them from google searches that are picking up very old stuff today)
15:21:58 <samccann> I have notes somewhere about redirects - so users would start getting /latest/ doc hits instead of /2.3/ for example. But it would still keep 2.3 docs available someplace else so people actually using very old releases can still find the docs
15:24:17 <briantist> nice! archive site sounds like a good idea
15:24:55 <samccann> yep. it's been something i've always wanted to do in docsland.. so you  know... bucket list FTW! ;-)
15:25:08 <briantist> 🎉
15:25:23 <samccann> ok let's swing over to ...
15:25:29 <samccann> #topic doc-tools
15:25:49 <BlaisePabon[m]> For example:
15:25:50 <BlaisePabon[m]> https://docs.ansible.com/ansible/latest/user_guide/collections_using.html#using-collections
15:25:50 <BlaisePabon[m]> Is really nice and it might be good to surface it early for folks who stumble into the docs from ansible-galaxy for example.
15:26:26 <briantist> I can talk a tiny bit about github-docs-build: https://github.com/ansible-community/github-docs-build
15:26:34 <samccann> #info https://docs.ansible.com/ansible/latest/user_guide/collections_using.html#using-collections is a little buried- let's surface it better in the docs
15:26:44 <samccann> briantist: cool go for it!
15:27:35 <briantist> it's in a good place for folks to start using now that we have the GitHub Pages publishing option, but I'm not quite ready to announce in the bullhorn just due to personal time, soon I think though
15:27:59 <samccann> how are the docs around that? (as in how to use it etc?)
15:28:28 <briantist> https://github.com/ansible-community/github-docs-build/wiki/Getting-started-with-GitHub-Pages
15:28:33 <briantist> docs are so-so, needs work
15:28:54 <samccann> ok
15:29:15 <samccann> so the next question - is that a good home for them? We can add a pointer to there from the developing collections docs on docs.ansible.com for sure
15:29:33 <BlaisePabon[m]> I have to leave. You are all such awesome people, doing the lord's work.
15:29:44 <samccann> :-) thanks Blaise Pabon
15:29:59 <briantist> I have a PR open for implementing it in `community.windows`, but nitzmahone did a security assessment, and decided that while there are not specific vulnerabilities, out of caution they don't want to do the PR workflows in any RedHat-controlled collections (but do not seem to have concerns if other collections want to do so)
15:30:30 <briantist> this was discussed in the Windows Working Group meeting so the full conversation is available for anyone who wants to read it: https://meetbot.fedoraproject.org/ansible-windows/2022-05-24/ansible_windows_working_group.2022-05-24-20.00.html
15:31:53 <samccann> #info some discussion about security 'worries' over github PR workflow proposed for collection docs changes https://meetbot.fedoraproject.org/ansible-windows/2022-05-24/ansible_windows_working_group.2022-05-24-20.00.html
15:32:27 <samccann> #info no specific vulnerabilities but probably not something to use on a RH based certified collection.  Will be open for other community collections soonish
15:32:57 <samccann> cool thanks for the details! I'll go back and read the log just so's I can follow along
15:34:03 <samccann> anything else in docs tooling to discuss today?
15:34:40 <samccann> (for anyone new  docs tooling is the background code that makes the docs happen - mostly collection docs)
15:36:38 <samccann> ok thenk!
15:36:40 <samccann> s/thenk/then
15:36:45 <samccann> #topic Open Floor
15:36:54 <samccann> Any thing else we want to discuss today?
15:37:02 <samccann> fav PR? fav issue lingering?
15:37:38 <orandon[m]> sorry I've been a bit quiet today but conflicts... can I plug my Getting Started PR? still looking for reviews. https://github.com/ansible/ansible/pull/77897
15:38:42 <samccann> #info  pr review welcome on revamped Getting Started guide - https://github.com/ansible/ansible/pull/77897
15:39:13 <samccann> Don Naro: how close do you think it is? like maybe we can merge by end of week? or still want more reviews etc?
15:39:39 <orandon[m]> I'm pretty happy with it tbh
15:39:39 <samccann> keeping in mind it's 10x better than what's there today so.. would like to get it out  there and iterate improvements as we go so to speak
15:40:16 <samccann> cool!
15:41:02 <tremble> Looks like nitzmahone's concerns with the docs-build PR is related to granting write access to the repos themselves.  I'd like to comment that the temporary build and validation workflows are still really useful.
15:41:32 <tremble> docs-build workflows rather
15:43:06 <samccann> tremble: is there a middle ground here? Like the temp build/validation is one set of tasks, and the full she-bang with write access to the repo a step beyond that?
15:43:14 * samccann really needs to read the docs on this!
15:43:54 <tremble> yes, community.aws and amazon.aws are using the validation and non-publishing workflows and they're really helpful
15:44:02 <samccann> coolness
15:44:08 <tremble> * and non-publishing build workflows and
15:44:48 <samccann> Do we have any other open floor topics today?
15:45:00 <BlaisePabon[m]> (naive question)...
15:45:00 <BlaisePabon[m]> has the group looked into zuul-ci for building the docs?
15:45:00 <BlaisePabon[m]> I'm thinking more specifically of https://www.softwarefactory-project.io/ or https://opendev.org/
15:45:36 <BlaisePabon[m]> (that way all the build logic would be Ansible plays)
15:46:14 <tremble> In theory it can be done, unfortunately (as I understand it) the team managing Zuul doesn't really have much spare capacity right now.
15:46:35 <tremble> Zuul is already used for a lot of the test and release workflows
15:48:01 <BlaisePabon[m]> Ok. yes, I wasn't going to suggest zuul upstream but maybe one of the public offereings like opendev or softwareffactory
15:48:44 <samccann> what does ^^ do for us that the current CI doesn't (or the current, tho internal to RH, jenkins buiilds)?
15:49:30 <BlaisePabon[m]> The immediate benefit is that all the build steps would be written in Ansible
15:49:57 <BlaisePabon[m]> ... and zuul can auto merge non-breaking changes.
15:50:54 <BlaisePabon[m]> You can run it on tops of Jenkins
15:50:54 <BlaisePabon[m]> https://opensource.com/article/20/2/zuul
15:50:55 <tremble> The security issue is more to do with reducing the chance of something being able to slip an extra commit into the repo, so Zuul vs Actions doesn't really solve it.
15:50:55 <samccann> so automerge would be after 'some specific approvals' yes?
15:52:05 <BlaisePabon[m]> well, yes. The criteria for automerge are typically ansible plays that perform several tasks.
15:53:10 <tremble> The suggestion from the meeting was basically to have the workflow only publish to somewhere other than the main collection repo.
15:53:14 <BlaisePabon[m]> Oh! ok, in that case, you wold want to use Gerrit, where every commit is reviewed
15:53:29 <BlaisePabon[m]> (it sounds bad when I say it like that)
15:53:51 <BlaisePabon[m]> yes, I think that is a great idea.
15:54:55 <tremble> It doesn't need to be Gerrit, you can set the relevant rules in GitHub, but if the action can push a commit that it generates, then if you can compromise the action in some way the whole repo could be compromised.
15:56:12 <BlaisePabon[m]> yes, that would be bad.
15:57:07 <samccann> oooch yep
15:57:13 <BlaisePabon[m]> btw, I'm only asking about zuul because it's intended for projects comprised of mutiple repos.
15:57:54 <briantist> sorry was in a meeting, tremble: yes, it's around the write access, but as discussed, the part with write access never runs any PR code (actually it doesn't run any code from the repo at all), glad you're finding it helpful!
15:59:27 <briantist> the part that runs PR code only runs with a read-only token, and because the workflow is a `pull_request_target` trigger, the workflow itself is always from the target branch, so you cannot modify the workflow in a PR and run it triggered by that same PR
16:00:18 <tremble> briantist: During this meeting the workflows caught a mistake I made ;)
16:01:22 <briantist> I have been using a variation of these for a long time now, before they were separated, it was first because I was creating the initial docsite pages, and I don't know RST well, and it's tricky to get the syntax right, especially when you're making references to pages that are not in your repo
16:01:32 <briantist> the fast feedback is essential
16:02:41 <briantist> the GitHub Pages publishing is new, but I originally used this with publishing to surge.sh and that is still an option for anyone weary of making commits, it just requires someone with permissions on the repo to set the API token in the secrets
16:04:48 <samccann> ok we're about at that time. Anything else before we end the meeting?
16:06:19 <samccann> ok thanks everyone!
16:06:26 <samccann> #endmeeting