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