14:30:54 #startmeeting Docs Working Group aka DaWGs 14:30:54 Meeting started Tue May 26 14:30:54 2020 UTC. 14:30:54 This meeting is logged and archived in a public location. 14:30:54 The chair is acozine. Information about MeetBot at http://wiki.debian.org/MeetBot. 14:30:54 Useful Commands: #action #agreed #halp #info #idea #link #topic. 14:30:54 The meeting name has been set to 'docs_working_group_aka_dawgs' 14:31:07 #chair felixfontein 14:31:07 Current chairs: acozine felixfontein 14:31:10 who else is around? 14:31:41 samccann maybe? 14:31:44 abadger1999? 14:31:56 * samccann waves 14:32:11 abadger1999 bcoca dmellado relrod samccann you folks doing docs today? 14:32:15 #chair samccann 14:32:15 Current chairs: acozine felixfontein samccann 14:32:40 hey acozine 14:32:46 Óla 14:32:50 I'm around, although with the kid, so best effort xD 14:33:16 briantist cbudz cyberpear madonius Pilou shaps tadeboro thedoubl3j Xaroth zoredache want to talk docs? 14:33:27 #chair abadger1999 14:33:27 Current chairs: abadger1999 acozine felixfontein samccann 14:33:40 dmellado: understood - family first 14:34:52 all right, let's start with the changelog stuff 14:35:02 #topic changelogs in a collections ecosystem 14:35:32 https://github.com/ansible-collections/overview/issues/18 is the tracking issue 14:35:55 felixfontein: can you give a quick update on your code? 14:36:38 I've implemented a `trivial` category (which isn't shown in the generated .rst file; useful if f.ex. a collection wants to have a changelog fragment with *every* PR) 14:37:06 excellent - we can have Ansible Trivia nights! 14:37:12 lol 14:37:17 besides that I implemented support that you can use the tool when galaxy.yml isn't there (you'll have to provide more parameters via command-line arguments, surprise ;) ) 14:37:29 #info implemented a `trivial` category (which isn't shown in the generated .rst file; useful if f.ex. a collection wants to have a changelog fragment with *every* PR 14:37:48 besides that I only added a few tests, and was mostly busy with version number tagging in ansible 14:38:34 I have post-holiday brain today . . . 14:38:52 #info felixfontein also implemented support that you can use the tool when galaxy.yml isn't there (you'll have to provide more parameters via command-line arguments) 14:39:07 is there an open PR? or has all your stuff been merged? I looked at https://github.com/felixfontein/ansible-changelog, but that's old 14:39:22 it's all in https://github.com/ansible-community/ansibulled now 14:39:41 with docs (https://github.com/ansible-community/ansibulled/blob/master/docs/changelogs.rst https://github.com/ansible-community/ansibulled/blob/master/docs/changelog.yaml-format.md) 14:40:18 w00t! that is awesome! 14:40:22 \o/ 14:40:32 Sayee: welcome! 14:40:44 folks, Sayee is our Ansible docs intern for the summer 14:40:54 Sayee: welcome! 14:40:55 ah! welcome Sayee! 14:41:02 great having you around! 14:41:06 #chair Sayee 14:41:06 Current chairs: Sayee abadger1999 acozine felixfontein samccann 14:41:11 Thank you 14:41:28 Sayee: time to get used to "becoming furniture" 14:41:34 lol 14:41:40 :-) 14:41:46 #info this work is in https://github.com/ansible-community/ansibulled now 14:41:46 10:39 AM with docs (https://github.com/ansible-community/ansibulled/blob/master/docs/changelogs.rst https://github.com/ansible-community/ansibulled/blob/master/docs/changelog.yaml-format.md) 14:41:57 hmph that didn 14:42:04 didn't work.. 14:42:13 #info documentation: https://github.com/ansible-community/ansibulled/blob/master/docs/changelogs.rst https://github.com/ansible-community/ansibulled/blob/master/docs/changelog.yaml-format.md 14:42:20 heh thanks! 14:42:28 the `info` command doesn't do multi-line, apparently 14:42:46 IRC doesn't allow multi-line :) 14:42:55 heh 14:43:08 (in case you're using the matrix bridge) 14:43:25 * gundalow waves 14:43:31 I'm on IRCloud . . . it turns multiline cut and paste into snippets 14:43:38 gundalow: welcome! 14:43:39 * relrod waves too 14:43:46 relrod: welcome! 14:43:49 full house today! 14:43:54 #chair gundalow relrod 14:43:54 Current chairs: Sayee abadger1999 acozine felixfontein gundalow relrod samccann 14:43:55 acozine: great, I'm a fan of glowing-bear :D 14:44:13 dmellado: that's a great name, glowing-bear 14:44:35 acozine: it's a weechat frontend xD https://github.com/glowing-bear/glowing-bear 14:44:38 talking about naming... ;) 14:44:40 felixfontein: is anything left in the "To Do" column for changelogs? testing? 14:45:19 heh, yep we have some candidate names . . . as soon as the changelog topic is done and dusted 14:45:41 acozine: I guess mainly more testing and rooting out bugs, which hopefully aren't much anymore 14:46:50 So should we 'spread the word' so to speak and get more collection owners trying this out now? 14:46:58 the only big changelog todos left are a) getting collections to have changelogs, and b) create an ACD changelog out of the collection changelogs 14:47:04 I think so 14:47:08 awesome 14:47:23 it's probably good if we could get a first version on pypi, so that people can install it in an easy way 14:47:29 (and to fix the naming :) ) 14:47:34 heh 14:47:36 lol so very true 14:47:50 I was just going to say, to get it on pypi we need to agree on a name 14:48:06 #info what's left to do on this - more people testing/using it - first get it on pypi for easy install, and settle on the naming convention for these tools 14:48:12 * abadger1999 queues up the naming information 14:48:39 #topic naming for the new docs build tool (and other related tools) 14:48:43 * felixfontein is just trying to find the wiki page 14:48:55 (it would help if I would remember in *which* wiki) 14:49:34 abadger1999: do you have that list of name ideas handy? 14:49:38 https://github.com/ansible-community/ansibulled/wiki/Naming-things-is-hard 14:49:51 (ah yes. kind of obvious...) 14:49:52 abadger1999: thanks! 14:49:53 felixfontein: Yes, my problem exactly. 14:50:10 the most obvious place, and the last one I'd have checked probably... 14:50:22 pequenino 14:51:04 background: we called the tools `ansibulled` (a pun on Ansible/Ansibull and build), but that ruined auto-complete for the main `ansible-` command line tools 14:51:22 so we're looking for a name that doesn't start with `ansi` 14:51:37 preferably one that can be expanded if we need new tools in the toolbox in future 14:52:06 extra points for puns/jokes and for names that remind people they're related to Ansible 14:52:14 `antsybuild` 14:52:22 heh 14:52:27 formic 14:52:49 I like things with deeper meanings or seeming non sequitors that actually relate. Unfortunately, the best of those are taken... prince, paisley, able..... 14:53:44 ablebaker and antsybuild are probably my favorites right now. 14:54:16 should it be antsybuild, antsybuild-changelog etc., or should it be antsybuild (or antsy-build), antsy-changelog, etc.? 14:55:10 good question - what tools do we know we need, other than `changelog` and `docs`? 14:55:24 changelog.yaml linter 14:55:29 off the top of my head I like ansty-XX or whatever we pick as a base name, plus a hypen to the tool name 14:55:51 * acozine is looking at the `antsy` project and wondering what it's used for 14:56:15 `Sweet interpolated ANSI strings` doesn't mean much to me (yet) 14:56:17 https://github.com/willyg302/antsy 14:56:20 antsybuild ans antsybuild-changelog preserve the pun (antsybuild sounding like ansible). I'm okay with the subcomands being antsy-changelog if that's what you want.... The library name antsy has already been taken on pypi, though, so the library name would have to be antsybuild or antsy_build. 14:56:47 .. just the connotation .. antsy .. for stuff that tries to formalize structure ... does not seem congruent 14:56:58 antsi ? 14:57:07 (The same goes for able-baker..... The library name would need to be able-baker, but the subcommands could be able-changelog if we like the shorter forms) 14:57:38 I'm just wondering whether it's good of the ACD build tool is called antsybuild, while the other tools are called antsybuild-xxx. that is a bit confusing 14:57:41 felixfontein: thanks for that link - the GitHub repo is much more user-friendly than the pypi page 14:57:59 `antsybull-*` might work too.. (I honestly didn't think we would discuss `antsybuild` seriously I just love puns haha) 14:58:18 antsy-blah 14:58:20 felixfontein: yeah, we can name them antsychangelog (or name the main one antsy-build) . 14:58:21 xD 14:58:21 briantist: it has been on the list since last week :) 14:58:31 oh lol I didn't even know 14:58:48 antsibull- or antsybull- as a common prefix is also fine for me 15:00:16 so `antsybull-build` and `antsibull-docs` and `antsibull-changelog`? 15:00:19 heh 15:00:25 typos galore! 15:00:47 hahaha 15:00:48 briantist: welcome! 15:00:56 #chair briantist 15:00:56 Current chairs: Sayee abadger1999 acozine briantist felixfontein gundalow relrod samccann 15:01:16 (and antsybull-lint-changelog-yaml) 15:01:41 that's a mouthful 15:02:09 Maybe we make that antsybull-lint ? 15:02:26 abadger1999: in that case I would expect it to also lint changelog fragments, and lint ACD builds etc :) 15:02:28 would it lint anything other than the chanelog? 15:02:29 (with subcomands for changelog, and anything else we need to lint? 15:02:41 but yeah, it could be that, with right now exactly one subcommand (for linting changelog.yaml) 15:02:45 felixfontein: yeah, if we build those linters, then that would go in there. 15:02:54 sounds like a good plan :) 15:02:57 Cool. 15:03:12 * abadger1999 checks really quickly for antsybull on pypi 15:03:32 Not taken :-) 15:03:40 * acozine breathes out 15:04:07 https://github.com/adamkpickering/antsy-bull - A configuration management (and more) framework with all the benefits of Ansible and none of the drawbacks 15:04:22 Boo... okay, that's probably not a good idea then. 15:04:34 first and last commits on may 25, 2018 15:04:54 the name sounds familiar 15:05:58 antsibull? 15:06:27 Heh, looks like there's only one code file and it is just a stub 15:06:28 has very few hits on google, and they are all like "I shellback tick bite, 2 hopper ants, I bull ant and 3 leeches " 15:07:01 I guess antsybull should be ok too :) 15:07:03 So i guess antsy-bull could still be okay. 15:07:10 Yeah. 15:07:30 also we chose antsybull and not antsy-bull 15:07:38 15:07:59 that tool would screw up tab completion for us (and vice versa), but only if it ever gets completed 15:08:12 Okay, any objections to antsybull ? I can make it so today so that we can do a release this week. 15:08:24 is it better to use anstibull instead to avoid that? 15:08:32 heh 15:08:48 It would still mess it up since they both start with "ants" 15:08:53 I'm both fine with antsibull and antsybull 15:08:55 `antsibull`? 15:09:13 abadger1999: true, but the name would be more different :) 15:09:18 heh, it took me so long to make sure I'd typed it correctly, I missed the moment 15:09:25 ++ for more different :-) 15:09:54 and antsibull is closer to ansible 15:10:21 and the pun still works, at least to me as a non-native english speaker ;) 15:10:23 I like that antsy is a pun. 15:10:24 yep, that's what I was liking about it 15:10:44 whereas antsi is not... but good point, the word as a whole is. 15:10:57 it's an omnibus pun . . . 15:11:01 :-) 15:11:11 ^^ that antsibull is like ansible.... but then as I was typing it, I nearlly typed ansibull by mistake... so maybe anstybull would be more memorable in that sense 15:11:18 heh 15:11:24 And in the end I won't bikeshed it.... If you like antsibull better, that's fine with me. 15:11:31 heh :-) 15:11:40 close.... but not tooooo close. 15:11:49 I'd mainly want to reduce collisions with antsy-bull 15:11:59 so it sounds like we're all agreed that some form of Antsy Bull is good 15:12:10 we just need to decide how to spell it 15:13:11 are we trying to avoid collisions with antsy-bull because we think it might actually become something and folks would execute the wrong thign? 15:13:18 or out of professional courtesy? 15:13:24 Let's not take up meeting time, then.... acozine, felixfontein, samccann after the meeting, lets just choose one of the spellings, even if it's a coin-fli[ 15:13:42 it's more professional courtesy, after all that person already came up with the name two years ago (even though it wasn't properly used yet) 15:13:53 fine for me! 15:13:59 #agreed we will use something like antsy-bull/antsibull - to be discussed/decided later 15:14:08 or whoever else wants to take part in bikeshedding ;) 15:14:12 heh 15:14:26 * acozine announces the construction of the bikeshed to follow this meeting 15:14:33 what's next on the agenda? 15:14:55 porting guides? 15:15:01 #topic porting guides 15:15:04 yeah that's a good morph 15:15:05 or Andersson007's changelog PR? 15:15:17 let's do porting guides now, hoping it will be quick 15:15:21 yep 15:15:36 showing up faded so don't think they are around today. but we SHOULD review that one maybe later today since it's been on the agenda for a bit 15:15:36 can we create a porting guide based on the changelog entries? 15:15:40 * samccann feels bad on punting 15:16:07 I'm a bit tending to that we might no longer need porting guides for collections, but could use the changelog for that 15:16:11 samccann: I put it on the agenda :) 15:16:35 acozine: that's what I mean 15:16:52 we have sections 'deprecated_features', 'removed_features', 'breaking_changes' 15:16:59 yeah, that will be an incentive for collection maintainers to create and enforce changelog entries 15:17:02 these cover essentially everything that's in the porting guide 15:17:13 (maybe a bit of major_changes as well?) 15:17:25 the old porting guides are a lot more verbose than the changelog entries 15:17:32 do we still want to make that possible/ 15:17:34 ? 15:17:48 porting guide entries for modules/plugins are usually pretty short anyway 15:17:54 that's true 15:17:55 and changelog entries can also be pretty long :) 15:18:29 (not that it's probably a good idea to write more than one paragraph into one entry) 15:18:41 the verbose entries tend to be for things in core 15:18:54 yeah I envisioned a combination of both. A manual section were we can add what we want, and a generated section that pulls in the appropriate changelogs from each collection (felixfontein's list from above) 15:18:56 I can say as a user and someone trying to migrate company-wide repos to new versions, the porting guides were incredibly useful, and trawling through the changelog would not have been successful 15:19:12 briantist: that's good information to have 15:19:14 But having sections for deprecated/removed/etc. and auto generating it form that might be good too 15:19:25 acozine: the verbose entries could be for more than core. The internal collection team is trying to keep all their collections doing 'similar things' 15:20:22 briantist: breaking_changes didn't exist before in the changelog, that stuff was mostly added manually to the changelog (with lots of conflicts) 15:20:37 (conflicts in PRs I mean) 15:21:19 if people use the categories correctly, these three categories should be pretty much what the porting guide used to be 15:21:39 yeah, the porting guide pages were difficult to manage, because every change we merged created merge conflicts for every other PR that touched the porting guide for that release 15:22:25 felixfontein yeah agreed, that makes sense and sounds like a better system (less chance of missing things too) 15:22:52 the manual section samccann mentioned would be helpful for things that might fall through the cracks or don't fit into a particular changelog 15:23:51 I would like to write multiple paragraphs and examples of playbooks/code in porting guide entries. 15:24:08 realistically this is easy to do. The autogenerated section goes to foo.rst and the manual section is bar.rst and we have a file porting_guide_2.10.rst that pulls them both in 15:24:10 I think we could do that inside of changelog entries, but I'm not sure... 15:24:28 abadger1999: I'm not sure the generator can manage that at the moment, but I'm sure we can fix that 15:24:30 So many different strings in yaml combined with whatever post-processing we do.... 15:25:20 the problem I envision - 10 collections make the same change... we would rather have one porting guide entry to say 'all these collections now do foo' vs having 10 individual entries, one for each of them. 15:25:33 could we have separate, optional `PortingGuide` fragments as well as Changelog fragments? 15:26:24 * acozine realizes this conversation is not a simple as she'd hoped 15:26:39 I love the idea of having examples in the porting guide, not sure it should be in the rendered changelog entries though (too big), maybe if they were marked as verbose/porting in the changelog file, then rendered in porting guide, and in changelog it renders as a link to porting entry 15:26:58 (saying all this with zero knowledge of the code that generates all this stuff, and the complexities therein) 15:27:57 ah that's a different wrinkle I hadn't thought of briantist - an individual collection/module wanting to add a complex entry like an example. 15:28:20 I think the changelog generator allows for embedded rst, right? (aka this is doable today?) 15:28:41 samccann: in theory yes, I'm not sure it will survive the output step though :) 15:28:53 heh. 15:29:22 I think it can be adjusted so that most things would survive 15:29:31 assuming people don't start trying to use sections in their entry 15:29:43 so that's the wrinkle then - someone creates changelog fragments, that get generated into a porting guide, but then they need to add a complex bit of writing. Do they put it in the changelog itself and hope for the best, or do they edit the end result? 15:29:58 @acozine for your questoin, it's possible... felixfontein should probably evaluate the technical side of whether it's better to do separate fragments or modify the changelog fragments in some way (even if that results in a changelog fragment type of `porting_guide:` 15:30:45 The other question - for ansible 2.10 - are we trying to bite off more than we can chew by automating the porting guide? 15:30:53 abadger1999: that seems like a good solution for the scenario briantist and samccann are talking about 15:30:57 I seem to feel a release is looming in 2 months? 15:31:12 yeah, freeze and ansible-base beta1 i the end of this week. 15:31:23 ansible-2.10alpha1 will probably be early next week. 15:31:39 I don't believe in that until the routing PR is merged :) 15:31:43 ok so if we are to freeze by friday...is anything besides what felixfontein has done actually acheivable in 3.5 days? 15:31:44 (community is tentatively thinking we need to do an alpha rather than jumping directly into a beta) 15:31:54 samccann: we won't commit to doing it for 2.10 (though if we can, it would be lovely) 15:32:22 ok good to know 15:32:38 I think the hardest problem is to figure out how the input looks like 15:32:42 oh 2nd question - is anstibull holding to the same freeze timeline as core/acd? 15:32:50 Oh, also note... freeze == ansible-base freeze... since community is thinking we're doing 2.10 alpha, collections can continue to iterate for a it longer. 15:32:57 implementing it should be not that hard (if there aren't some crazy ideas there :) ) 15:32:59 if we take a long view, we might get it in for 2.11 15:33:14 samccann: antsibull will be separate. 15:33:36 ok so since this tool lives there, it isn't subject to the freeze date on Friday... also good to know :-) 15:33:45 felixfontein: excellent . . . though I imagine some craziness is inevitable 15:33:48 we're past the hour mark ... 15:33:53 heh, again 15:34:18 samccann: I do worry whether we'll need changes to ansible-base for antsibull (because of the routing PR mostly) but it can continue to develop as long as we can work with or work around anything in the deliverables . 15:34:21 shall we do another Overflow DaWGs meeting later this week for the rest of the agenda? 15:34:40 deliverables == ansible-base and all of the dependent collections. 15:35:51 #info automating porting guide for 2.10 from changelog fragments is a stretch goal, but not committed to it yet. need to determine complexity of rst embedded in a changelog fragment etc 15:36:44 are people available for another DaWGs meeting this week? 15:36:51 probably having another meeting won't hurt ;) maybe we could think about how porting guide fragments should look like (which aren't covered by breaking_changes and the related changelog categories) 15:37:14 btw, tomorrow at 18:00 UTC we have the first #ansible-community meeting 15:37:35 would Thursday at half an hour earlier than our usual Tuesday time work for folks? 15:37:40 omgosh thank you! I heard about it but couldn't figure out when it was 15:37:49 https://github.com/ansible/community/issues/539 in case anyone is interested 15:38:05 ooh, cool, thanks felixfontein 15:38:06 acozine: fine for me! 15:38:14 works for me 15:38:29 samccann: there was no official invitation yet, I think, it was mainly written somewhen last week in #ansible-community 15:38:37 briantist: could you make it then? 15:38:39 gundalow: so is the meeting time fixed for tomorrow? 15:38:54 I think he's AFK 15:39:01 sorry I'm in another meeting at the same time, when was that? 15:39:19 felixfontein: we can meet whenever tomorrow 15:39:30 ditto for me ^^ 15:39:31 (also I'm much less important, have it when it works for y'all) 15:39:33 gundalow: I think we said 18:00 UTC 15:39:37 abadger1999: that's brutally early for you, but we've got other meetings later that morning 15:39:37 IIRC :) 15:39:53 Yup, that works 15:40:02 briantist: half an hour earlier than this meeting started today . . . on Thursday 15:40:13 I don't know what TZ you're in . . . . 15:40:36 I think that's ok yeah, I'm in US Eastern 15:40:46 then 10:00 for you 15:41:04 Erm, 1800 UTC is later than now 15:41:06 I will put it on my calendar, thanks for asking! 15:41:17 Or are you referring to any other meeting? 15:41:40 18:00 UTC was the ansible-community meeting tomorrow 15:41:59 the DaWGs meeting is proposed at 10AM ET on Thursday (sorry dunno what UTC that is)? 15:41:59 gundalow: I mean the ansible-community meeting tomrrow 15:42:10 14:00 UTC I think 15:42:40 so are we agreed for 10AM ET on Thursday for DaWGs supplemental meeting? 15:42:43 samccann: yes 15:42:49 Ah, OK. 15:42:53 samccann: +1 15:43:19 gundalow: we'll cover the "what do we need to move issues/PRs" question then 15:43:50 #action samccann to add 'what do we need to move issues/prs for docs' to thursday's agenda 15:43:58 acozine: excellent, thank you. 15:44:07 ok 15:44:09 any other action items from today? 15:44:09 so back to naming? :) 15:44:12 #agreed we will have a supplemental DaWGs meeting at 10AM ET on Thursday this week 15:44:18 let's close this meeting out first? 15:44:22 sure :) 15:44:28 heh, let's do a quick open floor, close the meeting, then move to the bikeshed 15:44:32 #topic open floor 15:44:44 7:00AM Thurs is fine... I may or may not be there but you don't need me for most DAWGs topics :-) 15:45:06 abadger1999: yep, come if you're awake and bored, sleep if you can 15:45:24 so for anyone out there who has been watching/reading this meeting without saying anything 15:45:41 for anyone who has been thinking, "I'd really like some feedback on my PR" 15:46:09 or wondering, "Why isn't anyone talking about this topic near and dear to my heart?" 15:46:16 NOW IS YOUR CHANCE! 15:46:22 It's time for the open floor. 15:46:40 and while we give shy persons the time to speak up . . . 15:47:10 a reminder that agenda items are welcome at any time - just add them to https://github.com/ansible/community/issues/521 15:47:44 also, chat is encouraged on this channel at any time 15:48:04 if you have question or comment, idea or criticism, we'd love to hear them 15:48:29 seems like nobody has open floor topics today, though, so . . . 15:49:19 thanks abadger1999 briantist dmellado felixfontein samccann and everyone on the channel! 15:49:26 #endmeeting