16:00:19 <acozine> #startmeeting Docs Working Group aka DaWGs
16:00:19 <zodbot> Meeting started Tue Dec 22 16:00:19 2020 UTC.
16:00:19 <zodbot> This meeting is logged and archived in a public location.
16:00:19 <zodbot> The chair is acozine. Information about MeetBot at http://wiki.debian.org/MeetBot.
16:00:19 <zodbot> Useful Commands: #action #agreed #halp #info #idea #link #topic.
16:00:19 <zodbot> The meeting name has been set to 'docs_working_group_aka_dawgs'
16:00:19 <baptistemm> I think globally we have too much redacted content
16:00:28 <acozine> #topic opening chatter
16:00:43 <acozine> #chair abadger1999 baptistemm felixfontein
16:00:43 <zodbot> Current chairs: abadger1999 acozine baptistemm felixfontein
16:00:53 <felixfontein> :)
16:00:53 <acozine> who else is around?
16:00:58 <baptistemm> yes maam
16:01:01 <acozine> heh
16:01:08 <felixfontein> dmsimard: andersson007_: ping
16:01:13 <acozine> I figured you all were here chatting already
16:01:23 <acozine> so I "voluntold" you
16:01:40 <dmsimard> busy with intermittent dad ops today but will try to pay attention
16:01:52 <bcoca> 'wall of velcro'
16:02:02 <felixfontein> #chair dmsimard bcoca
16:02:02 <zodbot> Current chairs: abadger1999 acozine baptistemm bcoca dmsimard felixfontein
16:02:15 <acozine> heh, bcoca you did too much older-sibling-parental-standing-in
16:02:43 <abadger1999> hey baptistemm  :-)
16:02:52 <acozine> honestly, I think the best thing for today's meeting is a big open floor
16:03:07 <bcoca> acozine: does it show?
16:03:11 <acozine> bcoca: yep
16:03:27 <bcoca> <= eldest by 10yrs of 6 siblings
16:03:32 <bcoca> and only child ...
16:04:02 <acozine> I guess we do have an agenda
16:04:09 * acozine looks up the official agenda
16:04:30 <acozine> #topic new year, new agenda issue
16:04:51 <felixfontein> \o/
16:04:58 <acozine> Remember, we'll close the current agenda issue and open a new one for 2021
16:05:44 <acozine> Current 2020 agenda is https://github.com/ansible/community/issues/521
16:05:49 <acozine> today's agenda is https://github.com/ansible/community/issues/521#issuecomment-745538181
16:06:06 <acozine> I'll move the Jan. 7th agenda to the new issue
16:06:13 * acozine considers doing that right now
16:06:32 <felixfontein> I have something for the open floor: https://github.com/ansible-community/antsibull/pull/225
16:06:47 <felixfontein> the result looks like this: https://gist.github.com/felixfontein/195db3ba5817d89c7968017531dd4686#added-collections
16:09:46 <acozine> https://github.com/ansible/community/issues/579 is our 2021 issue for the agenda
16:10:08 <acozine> #topic Antsibull PR 225
16:10:55 <felixfontein> adding the version to the table's header should be no problem
16:11:10 <felixfontein> I guess we can mainly now discuss/decide how we want it to look like, then I can implement it :)
16:11:42 <baptistemm> having the ansible version in the header is +1 for me
16:12:12 <acozine> felixfontein: this looks great
16:12:46 <acozine> it's easy to read and easy to understand
16:13:26 <baptistemm> yes the whole table is really informative
16:13:38 <felixfontein> you have to thank g. and dmsimard, they suggested it :)
16:14:09 <acozine> I like dmsimard's suggestion of adding the version numbers for previous/new
16:15:03 <felixfontein> do you want simply `Ansible 2.10.x` in the header, or something like `Ansible 2.10.x (old/new)`?
16:15:32 <acozine> abadger1999: just read your comment about the diffs
16:16:58 <acozine> you're thinking that PRs to update changelog.rst may be less readable with the table?
16:16:59 <abadger1999> I'm thinking diffs will be slightly more readable with simple table format but that might not be too bothersome.
16:17:10 <abadger1999> I'd still use a table but I'd use the simple format.
16:17:17 <acozine> ah, gotcha
16:17:23 <abadger1999> https://docutils.sourceforge.io/docs/user/rst/quickref.html#tables
16:17:29 <acozine> tables in rST are not fun to maintain
16:17:43 <abadger1999> The PR uses Grid Table right now.   Simple table is the second example  in that section.
16:17:59 <dmsimard> I might eventually want to have a persistent table (outside the scope of changelog) with versions of collections across ansible versions even if just for reference, a bit like this: https://openstack-ci-reports.ubuntu.com/reports/cloud-archive/victoria_versions.html
16:18:21 <felixfontein> hmm, usually existing entries don't change
16:18:33 <felixfontein> so the table format shouldn't really matter
16:18:57 <abadger1999> Yeah.
16:19:23 <abadger1999> I do like simple table format better when reading the raw rst version of documents too, but that might just be me.
16:20:17 <acozine> heh, we don't want to encourage folks to read the raw rst
16:20:34 <acozine> I mean, we don't want to make it unreadable just for that reason, but . . .
16:21:40 <abadger1999> Well... the raw rst is included in the tarball.
16:21:44 <felixfontein> https://gist.github.com/felixfontein/195db3ba5817d89c7968017531dd4686#changed-collections now has `Ansible 2.10.x` in the headings
16:21:47 <abadger1999> and not built as html
16:22:01 <acozine> mmm, yeah
16:22:05 <abadger1999> So system packagers will likely include the raw rst as documentation.
16:22:06 <felixfontein> to me, both the simple format and the grid format are equally easy to read
16:22:36 <abadger1999> Anyhow.... either table is definitely an improvement over no table :-)
16:22:40 <acozine> I'd vote to merge this change and use it for the next release or two, then revisit the table format if it does turn out to be a problem
16:22:56 <abadger1999> +1
16:23:40 <acozine> what are the failing tests?
16:24:09 <acozine> are they legitimate failures?
16:24:22 <felixfontein> looks like they come from updated dependencies
16:24:26 <felixfontein> (and are unrelated to the PR)
16:26:38 <felixfontein> ok, anyway, that's something unrelated to the PR
16:26:51 <felixfontein> so we can merge later once CI is back working
16:27:03 <felixfontein> the main thing is that everyone's happy with the result :)
16:28:12 <acozine> yep, it's a big improvement
16:28:16 <abadger1999> Yeah, agreed.
16:28:35 <abadger1999> (felix you can merge before CI is passing if you want.  I'm satisfied that it is unrelated)
16:29:18 <felixfontein> abadger1999: thanks, will do once LGTM is happy
16:30:40 <felixfontein> interestingly, after running `poetry update`, tests still pass for me locally
16:30:40 <acozine> merging on failing CI??? The descent into chaos begins!
16:31:04 <felixfontein> hehe :)
16:31:28 <felixfontein> also the last change was minimal, and CI passed before (or at least everything but codecov)
16:31:50 <felixfontein> so chances this is breaking is not that high
16:32:10 <acozine> codecov is annoying . . . useful I suppose but annoying
16:32:33 <felixfontein> it's less annoying once there is enough test coverage
16:32:53 <felixfontein> right now, only parts of the code are covered, and every time you add a line to the uncovered parts, it screams at you
16:33:16 <acozine> ah, so we need a Testing Hackfest?
16:34:22 <acozine> well, that's an item for 2021
16:34:33 <felixfontein> probably wouldn't hurt :)
16:34:33 <abadger1999> :-)
16:34:56 <felixfontein> I have another PR, this time for antsibull-changelog - it's more a RFC though
16:35:00 <felixfontein> https://github.com/ansible-community/antsibull-changelog/pull/48
16:36:22 <acozine> I like the `wipe_server` playbook
16:36:24 <felixfontein> it allows to add test and filter plugins in the `New Plugins` section manually, and adds (optional) `New Roles` and `New Playbooks` sections
16:37:03 <felixfontein> eventually `antsibull-changelog release` should auto-find all new test and filter plugins, and all new roles and playbooks, but that will need them to be documentable etc.
16:37:11 <felixfontein> the PR allows to add them manually with special changelog fragments
16:37:49 <acozine> let me see if I'm following this correctly
16:37:53 <acozine> the progression will be:
16:38:43 <acozine> 1. role argspec defines a common structure for roles, allowing us to extract documentation
16:39:37 <acozine> 2. collections that have or add plugins can notify users of their existence through the changelog
16:40:06 <acozine> s/plugins/test and filter plugins
16:40:58 <acozine> 3. collections that have or add playbooks and roles can notify users of their existence thorugh the changelog
16:41:00 <felixfontein> 2. could be done automatically if test and filter plugins would be documentable. bcoca is working on that, but it hadn't happened yet and will probably take some more time until that really happens.
16:41:35 <acozine> 4. antsibull-changelog will begin automatically adding new filter/test plugins and new roles and playbooks just as it adds new modules today
16:42:10 <acozine> ah
16:42:33 <felixfontein> your 3. is probably more like 0., because it can be done now, while role argspec, test/filter plugin docs, and playbook docs are still under development (or just planned, or not even that)
16:43:00 <acozine> so the current PR is a workaround so users know that test plugins, filter plugins, roles, and playbooks exist  in a collection (as soon as they CAN exist in a collection)
16:43:05 <acozine> ?
16:43:46 <felixfontein> yes. also, they can already exist in a collection, but right now you have to announce them with minor_changes or other not really suitable categories
16:44:10 <acozine> okay, gotcha
16:44:41 <acozine> I can see both sides of this argument
16:44:58 <felixfontein> which is a bit strange, especially for filter and test plugins, that you need to use minor_changes for them, while all other plugins are announced differently
16:45:01 <acozine> on the one hand, it would be nice to let users know about all the content in a collection
16:45:28 <acozine> but on the other hand, it's a bit frustrating to find a changelog reference to a plugin/role/playbook that has no documentation
16:45:50 <acozine> "great, there's a new test plugin, but I don't know how to use it"
16:45:56 <felixfontein> that's another problem :)
16:45:58 <acozine> or
16:46:10 <acozine> "why didn't you tell me this collection had this great test plugin?"
16:46:20 <acozine> I'm not sure which is better
16:46:24 <felixfontein> though we already have that problem nowadays
16:46:31 <acozine> yes
16:46:34 <acozine> sigh
16:46:47 <abadger1999> Should we pair this with being able to include arbitrary documentation in the collection?
16:46:51 <felixfontein> see the first entry in https://github.com/ansible-community/ansible-build-data/blob/c5469d819f3d1f28afe9ce68c314eb6d9f90519f/2.10/CHANGELOG-v2.10.rst#communitygeneral-9
16:47:23 <acozine> that's a nice changelog entry
16:47:29 <acozine> with a usage example
16:47:44 <acozine> abadger1999: that's an interesting idea
16:47:50 <felixfontein> yep, and it's the only place where this filter is documented *at all* :)
16:48:29 <acozine> it seems like the most vital bit of work is making filter/test plugin documentation possible
16:48:32 <abadger1999> Some documentation is better than no documentation?
16:48:45 <acozine> yeah, you're probably right
16:49:02 <acozine> we'll get complaints either way
16:49:24 <felixfontein> so far I only saw complaints that you cannot announce new roles the same way as new plugins/modules :)
16:49:55 <acozine> but maybe the complaints of "I'm excited to use this new filter plugin/role but why isn't there documentation?" will spur the wider team
16:50:28 <acozine> and raise the priority level of the role argspec and the filter/plugin docs work
16:50:31 <felixfontein> bcoca: you mentioned that you had a branch or something like that for documentable test/filter plugins, do you remember where it is? I've tried looking for it, but haven't found it
16:50:45 * acozine has to step out to accept a deliver
16:50:49 <acozine> er, delivery
16:54:21 <acozine> our new back railing has arrived, just in time for winter
16:56:56 <felixfontein> I'm off now, if you have further comments / ... on the PR, feel free to write them here or in the PR.
16:57:11 <felixfontein> abadger1999: https://github.com/ansible-community/ansible-build-data/pull/44 for the generated changelog
16:57:15 <acozine> bye felixfontein
16:57:18 <acozine> Happy New Year
16:57:41 <acozine> #topic open floor
16:58:09 <acozine> the whole meeting has been an open floor, really
16:58:13 <acozine> but just for form's sake
16:58:17 <abadger1999> Thanks felixfontein !
16:58:34 <acozine> #info 2021 agenda will be https://github.com/ansible/community/issues/579
16:59:30 <acozine> questions, comments, ideas, criticism all welcome
16:59:45 <acozine> both in the agenda issue, and here in the chat channel
17:01:48 <acozine> thanks abadger1999 baptistemm bcoca dmsimard felixfontein and all lurkers!
17:02:00 <acozine> Happy New Year, everyone!
17:02:05 <acozine> #endmeeting