15:02:09 <acozine> #startmeeting Supplemental Docs Working Group (DaWGs)
15:02:09 <zodbot> Meeting started Wed May 20 15:02:09 2020 UTC.
15:02:09 <zodbot> This meeting is logged and archived in a public location.
15:02:09 <zodbot> The chair is acozine. Information about MeetBot at http://wiki.debian.org/MeetBot.
15:02:09 <zodbot> Useful Commands: #action #agreed #halp #info #idea #link #topic.
15:02:09 <zodbot> The meeting name has been set to 'supplemental_docs_working_group_(dawgs)'
15:02:15 <acozine> who's around?
15:02:25 <felixfontein> hey :)
15:02:25 * samccann waves...supplementally
15:02:28 <acozine> heh
15:02:35 <acozine> hey felixfontein, welcome
15:02:47 <acozine> #chair felixfontein samccann
15:02:47 <zodbot> Current chairs: acozine felixfontein samccann
15:03:25 <acozine> who else is around? resmo andersson007_ cbudz madonius tadeboro . . .
15:03:44 <cbudz> :waves:
15:03:47 * cyberpear listens
15:03:47 <acozine> for anyone who is watching the channel, and wondering, "why doesn't she ask me by name?"
15:04:15 <acozine> I call folks who have been active relatively recently . . .
15:04:21 <acozine> everyone is welcome!
15:04:25 <acozine> cyberpear: welcome
15:04:33 <acozine> #chair cyberpear
15:04:33 <zodbot> Current chairs: acozine cyberpear felixfontein samccann
15:05:13 <felixfontein> abadger1999 might already be awake, though I'm not sure whether he's busy with other stuff
15:05:25 * abadger1999 pops in
15:05:35 <acozine> welcome abadger1999
15:05:38 <acozine> #chair abadger1999
15:05:38 <zodbot> Current chairs: abadger1999 acozine cyberpear felixfontein samccann
15:06:02 <samccann> #chair cbudz
15:06:02 <zodbot> Current chairs: abadger1999 acozine cbudz cyberpear felixfontein samccann
15:06:11 <acozine> oops!
15:06:17 <acozine> welcome cbudz!
15:06:50 <acozine> as always, agenda is at https://github.com/ansible/community/issues/521
15:06:55 <cbudz> good morning
15:07:03 <felixfontein> btw, community.general, community.network, community.crypto and community.internal_test_tools now validate changelog fragments
15:07:28 <acozine> for today, we will cover topics we missed yesterday, so https://github.com/ansible/community/issues/521#issuecomment-627504676 and neighboring comments
15:07:35 <acozine> felixfontein: that's awesome!
15:07:54 <felixfontein> the feedback is unfortunately harder to read, because this is another tool than ansible-test (and I didn't want to reimplement the reporting facilities of ansible-test)
15:07:56 <acozine> #topic changelogs in collections/ACD
15:08:42 <acozine> #info changelogs summary: https://github.com/ansible-collections/overview/issues/18
15:08:57 <acozine> felixfontein: do you have sample feedback you can share?
15:09:12 <felixfontein> I unfortunately didn't manage to do much changelog related recently, but I started writing some docs: https://github.com/felixfontein/ansibulled/blob/changelog-docs/docs/changelogs.rst
15:09:16 <felixfontein> acozine: uno momento
15:09:39 <felixfontein> I created a test PR with a broken changelog fragment: https://github.com/ansible-collections/community.crypto/pull/50
15:10:06 <felixfontein> you need to look at the shippable console output: https://app.shippable.com/github/ansible-collections/community.crypto/runs/206/2/console
15:10:12 <felixfontein> 00:20 Test "changelog" failed with the following 2 errors:
15:10:13 <felixfontein> 00:20 changelogs/fragments/broken-fragment.yml:0:0: (WARNING/2) Inline interpreted text or phrase reference start-string without end-string.
15:10:15 <felixfontein> 00:20 changelogs/fragments/broken-fragment.yml:0:0: invalid section: unknown_category
15:12:04 <samccann> what's this part mean -  Test "no-unwanted-files" failed with the following 1 errors:
15:12:04 <samccann> 00:20 plugins/modules/random-data.yml:0:0: extension must be one of: .cs, .ps1, .psm1, .py
15:12:23 <felixfontein> I also added a test which checks that no unwanted files are added to plugins/
15:12:32 <samccann> ah ok phew
15:12:34 <felixfontein> (the PR also triggers that test by adding plugins/modules/random-data.yml)
15:12:41 <samccann> thought I was missing something entirely :-)
15:12:57 <felixfontein> that's one of the sanity tests that ansible-base is doing, that aren't part of ansible-test
15:13:14 <samccann> #info some docs for the changelogs - https://github.com/felixfontein/ansibulled/blob/changelog-docs/docs/changelogs.rst
15:14:26 <felixfontein> I tried to sum up what's important for users, if anyone can think of something that's missing, please tell me :)
15:14:33 <samccann> #info felixfontein  Felix Fontein -community.general, community.network, community.crypto and community.internal_test_tools now validate changelog fragments
15:14:34 <felixfontein> (or create a PR once this is merged)
15:15:07 <felixfontein> this is the changelog generator config for community.general: https://github.com/ansible-collections/community.general/blob/master/changelogs/config.yaml
15:15:14 <samccann> ok to back up a bit (I'm feeling slow today) - the validation tests only exist in those three repos, yes?
15:15:27 <felixfontein> it is essentially the default config created (I think I only changed `title`)
15:15:41 <felixfontein> samccann: four, but yes :)
15:15:53 <acozine> felixfontein: this looks great
15:15:58 <acozine> thank you for all the work
15:16:04 <felixfontein> they use this extra sanity test runner: https://github.com/ansible-collections/community.internal_test_tools/tree/master/tools
15:16:18 <felixfontein> (which conveniently describes how to set up changelog fragment validation)
15:16:20 <samccann> #info example of a changelog generator config - community.general: https://github.com/ansible-collections/community.general/blob/master/changelogs/config.yaml
15:16:27 <acozine> where is the best place to document "how to use the community changelog tools"?
15:16:44 <acozine> ah, you beat me to it felixfontein
15:16:57 <felixfontein> sooner or later ansible-test itself will allow to write plugins for it, but until that point this runner must do the job
15:17:03 <samccann> #info those 4 repos use use this extra sanity test runner: https://github.com/ansible-collections/community.internal_test_tools/tree/master/tools
15:17:29 <samccann> do we see that as something other repos may want to start using as well to validate changelog fragments?
15:17:38 <acozine> should we put a link to the tools README in the docs for collections developers?
15:18:19 <samccann> tools readme?
15:18:36 <felixfontein> you could also integrate `ansibulled-changelog lint` into your workflow in other ways, depending on how your collection's CI looks like
15:18:38 <acozine> samccann: https://github.com/ansible-collections/community.internal_test_tools/tree/master/tools
15:19:12 <acozine> the README there describes how to use the runner
15:20:12 <samccann> so for docs - we need how to use the changelog generator - in the collection dev guide imo
15:20:32 <samccann> (aka PR felix's work listed above)
15:20:32 <acozine> that makes sense
15:20:42 <felixfontein> yes
15:21:03 <samccann> then we have this supplemental tools.  First we need to know - do we want  the community using them already?  if so, we should move the readme again into the dev guide.
15:21:17 <felixfontein> btw, I mentioned to abadger1999 on Sunday (?) that I might prefer another name for ansibulled, since ansibulled screws up tab completion for ansible :)
15:21:20 <samccann> if it's all just 'nice to have, give it a try', then we just add a link to it from the deve guide
15:22:10 <samccann> #agreed need to move https://github.com/felixfontein/ansibulled/blob/changelog-docs/docs/changelogs.rst into a PR for collections dev guide on docs.ansible.com/ansible
15:22:27 <felixfontein> if we change the name, we should do it ASAP, before everyone gets used to it. but I can't think of something better (except sticking to ansible). abadger1999 suggested changelog-ansibulled instead of ansibulled-changelog.
15:22:31 <felixfontein> any opinions on this? :)
15:23:47 <samccann> so ansibulled will do three things, right - build 2.10, build docs (ansibulled-doc) and generate changelogs (ansibulled-changelog)?
15:24:16 <acozine> changing the names so they begin with the unique parts sounds like a good idea to me
15:24:25 <acozine> although I suppose it's a double-edged sword
15:24:49 <samccann> well we have ansible-test right?
15:25:01 <felixfontein> changelog-ansibulled and doc-ansibulled sound strange, like test-ansible would sound to me
15:25:02 <samccann> so...why did this end up ansibulled?
15:25:07 <acozine> easier auto-complete, but it means you have to remember all the options
15:25:12 <acozine> they do sound weird
15:26:00 <acozine> I think ansibulled is the home for build tools that used to come from core and are needed in collections
15:26:22 <samccann> ansitool?
15:26:26 <samccann> spitballin here
15:26:29 <acozine> heh
15:26:44 <felixfontein> right now I can type ans<TAB> to get ansible
15:26:55 <felixfontein> both ansitool and ansibulled stop that from working :)
15:27:13 <samccann> true
15:27:34 <acozine> so names that start with ansible and continue from there work
15:27:42 <felixfontein> I think I can get used to ansibulled, though I'm not sure how much other people will complain
15:28:01 <felixfontein> ansible-doc is already taken
15:28:04 <samccann> collbulled?
15:28:05 <acozine> but names that start with ansi and diverge from there interfere
15:28:08 <abadger1999> ansibulled sounds like ansibuild.   But yeah, we can change names....  To make tab completion we probably either have to change the order or we need to abandon the ansi* puns.
15:28:12 <samccann> (for collections)... and yeah still spitballin
15:28:13 <felixfontein> otherwise I'd suggest ansible-build, ansible-doc and ansible-changelog ;)
15:28:29 <acozine> coansibulled?
15:28:45 <bcoca> at this point it feels like you are bullying the name ...
15:28:48 <abadger1999> the-real-ansibulled?
15:28:53 <acozine> heh
15:29:08 <acozine> galabulled?
15:29:12 <bcoca> ansiblue-webdocs
15:29:14 <samccann> HAHAHA
15:29:38 <felixfontein> bcoca: that also breaks tab completion :)
15:30:19 <samccann> the problem with ansible-build etc is we will forever take that name. In that instance, maybe it makes sense because it IS building ansible (aka acd)
15:30:40 <felixfontein> after all ACD is named ansible on pypi :)
15:30:42 <samccann> ansible-doc is already taken
15:30:53 <felixfontein> ansible-doc-gen?
15:31:01 <samccann> but ansible-doc-build maybe
15:31:36 <felixfontein> ansible-doc-tool?
15:31:40 <bcoca> in retrospect, i would avoid ansilbe- and leave that for base project to add new cli
15:31:50 <samccann> ansible-changelog works since I think it will eventually be used for all changelogs (including ansible-base) right?
15:31:59 <felixfontein> I'd hope so
15:32:11 <cbudz> jumping in I think something hypenated is more meaningful
15:32:12 <samccann> bcoca yeah that's been my worry as well
15:32:14 <acozine> the thing I like about the ansibulled name (apart from the pun) is that it gives us the ability to group all the non-core tools using similar names
15:32:32 <samccann> good point
15:33:22 <acozine> if `ansible-playbook` and `ansible-doc` and `ansible-test` all apply to ansible, `ansibulled-doc` and `ansibulled-test` would apply to collections
15:33:33 <acozine> patterns make things easier to remember
15:33:54 <samccann> #info issues with ansibulled as a tool name - can't use ansi<tab> for command completion anymore. but ansible-changelog etc creeps into the tool names that the core team may want to keep control of
15:33:56 <acozine> but tab completion is so handy to ahve
15:34:04 <acozine> er, have
15:34:34 <cbudz> I am a tab completion fanatic
15:34:55 <felixfontein> ansible-collection-doc?
15:35:14 <acozine> yeah . . . so can we think of a name/pattern that would advertise the connection to Ansible and the limitation to collections (not core)?
15:35:14 <felixfontein> or ansible-acd-build, ansible-acd-doc, ansible-acd-changelog?
15:35:32 <felixfontein> that would be clear enough linked to ACD and not to core
15:35:33 <samccann> someone would likely shoot us for using acd :-)
15:35:36 <acozine> heh
15:35:40 <acozine> they started it
15:35:46 <felixfontein> acd-changelog can be abbreviated by acdc :D
15:35:59 <samccann> AAAHAHAH
15:36:02 <acozine> heh
15:36:06 <felixfontein> acdb, acdd, acdc for the three tools ;)
15:36:18 <bcoca> +100 for ac-dc
15:36:26 <felixfontein> ansible community distribution changelogs
15:36:27 <bcoca> acd-c
15:36:30 <samccann> ok should we put this one as a action item to follow up with maybe the community team for advice and move on?
15:36:32 <acozine> so . . we would need an acda
15:36:35 <acozine> somehwere
15:36:57 <acozine> just for the sake of alphabetical completeness
15:37:02 <felixfontein> how about acd-build, acd-doc, acd-changelog? then we don't have the ansible- prefix and names aren't too long
15:37:59 <samccann> ^^ seriously doubt we would be allowed to continue using acd on anything
15:38:28 <acozine> that checks the main boxes (leaves A-N-TAB available, easy to remember)
15:38:42 <abadger1999> heh, I just started renaming internal things last week.
15:38:57 <acozine> abadger1999: examples?
15:39:17 <acozine> do you mean ansibulled?
15:39:34 <abadger1999> Yeah, ansibulled started off as acd-build.
15:39:49 <felixfontein> re
15:39:52 <abadger1999> A lot of the internals still say "acd_foo"
15:39:54 <acozine> heh, so we'd be going back in time
15:39:57 <felixfontein> sorry, my irssi died (I couldn't type anymore)
15:40:11 <abadger1999> No worries, you didn't miss much.
15:40:13 <acozine> felixfontein: welcome back!
15:40:29 <abadger1999> too bad ac/dc-build doesn't work.
15:40:38 <samccann> how about ac-build so we don't get flack for using acd?
15:40:39 <abadger1999> Maybe there's better things to talk about right now :-)
15:40:57 <felixfontein> why is acd (probably) no longer allowed?
15:41:00 <abadger1999> But yeah, We can change the name as soon as we figure out something better.
15:41:29 <felixfontein> abadger1999: once people start using the changelog generator, we shouldn't really change the name anymore
15:41:55 <abadger1999> <nod>
15:42:01 <acozine> felixfontein: it was meant to be a marketing name for "Ansible plus Galaxy/Community Collections" but then we decided to keep using "Ansible" for that
15:42:27 <abadger1999> action item for this week?  discuss a new name?
15:42:30 <acozine> so it doesn't mean anything
15:42:58 <felixfontein> so how about ac-build (as samccann suggested), with ac-doc and ac-changelog?
15:43:17 <acozine> that sounds good to me - ac for Ansible Collections
15:43:23 <abadger1999> yeah, I don't see any conflicts.  Kind of bland, though ;-)
15:43:27 <acozine> true
15:43:28 <felixfontein> true :
15:43:29 <felixfontein> )
15:43:46 <abadger1999> Think on it a week and if we don't come up with anything better, we can go with that?
15:43:48 <acozine> how about everybody tries to come up with a more "fun" name pattern
15:44:00 <felixfontein> also AC is generic enough that nobody can complain that it is their brand
15:44:01 <acozine> with ac-* as the backup if we can't find one
15:44:29 <abadger1999> unless someone is already using it ;-)  The only thing I know is auconf uses ac as a suffic (not a prefix)
15:44:41 <samccann> #action - think up naming options to replace ansibulled-xxx.  ac-xxx is one option but command completion will be important as well as ease of remembering
15:44:54 <abadger1999> *autoconf
15:44:54 <acozine> #agreed collections tools will be renamed `ac-*` unless we can come up with a more interesting pattern that still preserves autocomplete for the main `ansible` tools
15:45:05 <felixfontein> on my system there's only autoconf which uses the ac prefix (during tab completion) for aclocal
15:45:46 <felixfontein> sounds good
15:45:57 <acozine> report name ideas here through the week
15:46:22 <felixfontein> once we fix names, we could also make a first release abadger1999 so that people can install it without installing from git :)
15:46:24 <acozine> anything else to discuss on changelogs?
15:46:50 <felixfontein> except maybe Andersson007's PR, I don't think so
15:47:01 <felixfontein> oh
15:47:05 <felixfontein> maybe
15:47:15 <felixfontein> in the link to the example config, you see a list of all sections
15:47:37 <felixfontein> these are the sections the original changelog generator from Ansible was using, plus some new ones that came up in a docs meeting some weeks ago
15:47:44 <felixfontein> https://github.com/ansible-collections/community.general/blob/master/changelogs/config.yaml
15:47:47 <felixfontein> here is the link again
15:47:57 <felixfontein> are you happy with these sections?
15:48:25 <felixfontein> the new ones are `breaking_changes` and `security_fixes`
15:48:50 <abadger1999> felixfontein: release schedule works for me.
15:48:58 <felixfontein> so `breaking_changes`, `deprecated_features` and `removed_features` together should contain the info that the porting guide used to contain (at least for collections)
15:49:21 <felixfontein> (which I guess leads to one of the next topics: porting guide)
15:49:29 <acozine> the difference between `security_fixes` and `bugfixes` is obvious
15:49:31 <samccann> heh yeah was about to say that
15:49:52 <acozine> the difference between `breaking_changes` and `major_changes` will need a bit more documentation
15:49:54 <acozine> but we can do that
15:49:58 <samccann> (what felix said... i'm working in slow motion today)
15:50:06 <acozine> I'd say those categories look good
15:50:15 <samccann> same here
15:50:15 <acozine> #topic porting guides in the collections ecosystem
15:50:18 <samccann> +1
15:50:20 <abadger1999> I've wanted a `trivial` section as well (for things that don't need to go into changelog... idea being then you can require that all PRs have a changelog fragment but the ones that don't need to be end user visible won't be added to the generated changelog)
15:50:32 <felixfontein> great :) I was pretty sure that these were what we discussed in a previous meeting, but I thought it's better to ask again :)
15:51:11 <samccann> Do we want the changelog generator to ignore the 'breaking_changes' category and have that go only in a porting guide? or have it repeated in both places?
15:51:28 <felixfontein> abadger1999: such a section would probably be handled specially, similar to release_summary
15:51:32 <acozine> abadger1999: ah, adding `trivial` would let us test for "you must have a changelog fragment"?
15:51:50 <felixfontein> samccann: personally I'd have it in both places
15:51:59 <felixfontein> acozine: yes
15:52:54 <acozine> I see the appeal of having a blanket rule. That said, do we have problems with PRs that don't have changelogs? Other than it's inconsistent?
15:52:55 <felixfontein> abadger1999: I guess that trivial sections would be handled during linting and changelog.yaml generation like any other section, but not included in the generated .rst file?
15:53:00 <samccann> on `trivial` - how much would that annoy developers to have to have a changelog fragment all the time tho?
15:53:45 <felixfontein> since most PRs already should have a changeolg fragment, I think the amount of PRs that would be affected is relatively small
15:53:47 <acozine> it might be easier than getting a review with "oh, and could you add a changelog fragment for this"
15:53:56 <felixfontein> yes
15:54:40 <acozine> helpful for reviewers too, perhaps . . . as an indication of how much scrutiny a given PR needs
15:55:16 <acozine> that's probably not a question the DaWGs should decide on our own, though
15:55:24 <felixfontein> true
15:55:43 <abadger1999> @acozine @felixfontein yes, that's what I was thinking.
15:55:49 <felixfontein> there just has been a discussion in #ansible-community to set up a regular community meeting, I guess that would be the place for that (at least for the big community collections)
15:55:57 <acozine> I'm in favor, and I don't mind the extra overhead to handle trivial changelog entries, but it doesn't directly affect docs otherwise
15:56:11 <felixfontein> if I don't forget I could prepare a feature in the changelog generator to allow having a `trivial` section
15:56:16 <acozine> heh
15:56:41 <felixfontein> then we can document / require it later without much extra work
15:57:29 <samccann> just about at the 1hr mark here
15:57:33 <felixfontein> yep
15:57:39 <felixfontein> time runs
15:57:44 <felixfontein> (do you say that in english?)
15:57:51 <samccann> time flies
15:57:59 <felixfontein> ah yes, that's it :)
15:58:29 <acozine> or "tempers fidget" in our household (a mispronunciation of `tempus fugit`)
15:58:39 <acozine> not sure where that one came from
15:58:45 <felixfontein> :D
15:59:21 <felixfontein> I guess that's one of the cases where a new word / expression is invented in a family, and might or might not spread around the world eventually
15:59:37 <acozine> if you hear it over in CH, let me know!
15:59:52 <felixfontein> I will!
15:59:59 <felixfontein> (though it might be me using it :D )
16:00:02 <acozine> heh
16:00:29 <acozine> so can I put you down to add the ability to handle `trivial` to the changelog generator felixfontein ?
16:00:38 <felixfontein> acozine: you can
16:00:53 <acozine> dang, is there an IRC command for that?
16:00:53 <felixfontein> put me down
16:00:59 <felixfontein> (context saves lives)
16:01:03 <acozine> heh
16:01:14 <acozine> definitely not like that!
16:01:17 <samccann> action is the irc command
16:01:28 <samccann> action <name>
16:01:31 <abadger1999> #action felixfontein will add trivial to the changelog generator
16:01:44 <acozine> thanks samccann and abadger1999
16:01:49 <felixfontein> cool :)
16:02:05 <felixfontein> do you want to continue now, or next tuesday?
16:02:59 <acozine> looking at the agenda, I think we can move the rest of the topics to next Tuesday
16:03:17 <acozine> and add "revisit the naming convention for collections build tools"
16:03:28 <acozine> samccann: what do you think?
16:03:42 <felixfontein> sgtm
16:03:43 <samccann> sounds good for next tues
16:04:14 <acozine> all right, let's have open floor, in case there are important topics we missed, forgot, or didn't know about
16:04:18 <acozine> #topic open floor
16:04:55 <acozine> As always, everyone is welcome to add agenda items to https://github.com/ansible/community/issues/521 - just add a comment at the bottom of the issue
16:05:07 <acozine> We even promise to discuss them one day!
16:05:15 <felixfontein> :)
16:05:20 <acozine> But if you have a burning issue today, now is your chance.
16:05:21 <felixfontein> maybe we'll finally manage porting guide next tues ;)
16:05:34 <acozine> we, uh, mentioned porting guides?
16:05:40 <acozine> it's a start . . .
16:05:47 <felixfontein> true!
16:06:03 <acozine> Anybody out there with a question, comment, idea, complaint?
16:06:40 * acozine waits at least a minute
16:06:52 * acozine is working on patience
16:07:32 <acozine> No open floor topics today.
16:07:54 <acozine> As always, feel free to chat in the channel any time.
16:08:30 <acozine> Thanks abadger1999 cbudz cyberpear felixfontein samccann
16:08:54 <abadger1999> thanks for running it!
16:08:56 <acozine> Next official meeting next Tuesday at the usual time.
16:09:06 <felixfontein> thanks everyone as well :)
16:09:12 <acozine> best meeting of my week!
16:09:17 <acozine> #endmeeting