14:31:56 <acozine> #startmeeting Docs Working Group aka DaWGs
14:31:56 <zodbot> Meeting started Tue Mar 31 14:31:56 2020 UTC.
14:31:56 <zodbot> This meeting is logged and archived in a public location.
14:31:56 <zodbot> The chair is acozine. Information about MeetBot at http://wiki.debian.org/MeetBot.
14:31:56 <zodbot> Useful Commands: #action #agreed #halp #info #idea #link #topic.
14:31:56 <zodbot> The meeting name has been set to 'docs_working_group_aka_dawgs'
14:32:31 <acozine> #topic sanity check
14:33:11 <acozine> just a quick check-in for those who want to share status
14:33:17 * samccann waves
14:33:25 <acozine> #chair gundalow samccann
14:33:25 <zodbot> Current chairs: acozine gundalow samccann
14:33:30 <acozine> who else is around?
14:33:31 * tremble lurks
14:34:04 <acozine> tremble: even lurkers generally get turned into furniture - it doesn't mean you need to stop lurking
14:34:09 <acozine> #chair tremble
14:34:09 <zodbot> Current chairs: acozine gundalow samccann tremble
14:34:16 * felixfontein waves
14:34:24 <acozine> #chair felixfontein
14:34:24 <zodbot> Current chairs: acozine felixfontein gundalow samccann tremble
14:34:36 <samccann> recent discussion was about insomnia... someone's mum highly recommended pumpkin seeds... just passing that along (the magnesium supposed to help you stay asleep)
14:34:38 <felixfontein> \o/ furniture!
14:35:23 <acozine> someday I'd like to try being an end table, or possibly one of those circular couches that are used so often in theaters
14:35:35 <acozine> but for today, a chair works
14:35:59 <acozine> samccann: oh, interesting about the magnesium
14:36:30 <samccann> my career aspirations are to be  a lounge chair... with comfy padding
14:36:55 <bcoca> you can have it, just ensure you turn off video during meetings
14:37:08 <acozine> #chair bcoca
14:37:08 <zodbot> Current chairs: acozine bcoca felixfontein gundalow samccann tremble
14:37:31 <samccann> heh... why bother? the number of times I've been on video calls and remembered AFTER that I hadn't combed my hair yet... hashtag livin the dream
14:37:50 <bcoca> what is comb?
14:37:54 <acozine> this is why I have a physical cover on my camera :-)
14:37:55 <samccann> heh
14:39:06 <acozine> day four of our stay-at-home order, and our pantry and freezer are stuffed full of supplies . . . but our refrigerator is strangely empty
14:39:46 <felixfontein> acozine: I bought a laptop which has no camera in the first place :D
14:39:56 <acozine> felixfontein: smart!
14:40:12 <felixfontein> it even saved money (something like < 10 $)
14:40:30 <acozine> I didn't know that was an available option
14:40:52 <felixfontein> I don't think it's an option for most laptops... it was one for lenovo's x270
14:41:13 <felixfontein> I opted out of the mic as well
14:41:15 <bcoca> tape!
14:41:33 <felixfontein> probably the last time I'm able to buy a laptop without these two...
14:41:46 <acozine> probably, yes
14:41:59 * tremble got a cool slide-y thing to go over the camera from Prod Sec
14:42:18 <acozine> I hate the feeling that the devices in my house are listening
14:42:27 <felixfontein> tremble: that's also cool! at least if it is a material which is really light-proof
14:42:47 <acozine> tremble: I have something similar on my big monitor (which i usually use at my desk
14:42:55 <felixfontein> acozine: I'm waiting for when I can't buy a new fridge / oven / ... which won't work without internet connection *and* mic/camera
14:43:00 <acozine> when it's closed, you can see a halo of light
14:43:18 <bcoca> if they want to listen to me snore .. im ok with it
14:43:21 * samccann totally convinced my house is eavesdropping on me, and feeding that info to instagram advertisers
14:43:44 <acozine> felixfontein: I'm pretty sure when that happens in my household, the refrigerator will go all HAL on us, decide we're a threat, and let the mayonnaise go bad on purpose to get rid of us
14:43:51 <samccann> saw and advertisement for a smart faucet.  smart....faucet....
14:44:12 <acozine> so you can turn the water on before you get home???
14:44:13 <felixfontein> I don't know about which of these two lines to laugh harder ... and be more scared of
14:44:31 <samccann> you could tell it to measure out xx ml of water
14:44:34 <felixfontein> so that internet blackmailers can get your money for not flooding your home
14:44:45 <samccann> like it was hard to put a measuring cup under it to do the same dang thing
14:44:55 <samccann> but I digress :-)
14:45:00 <acozine> heh
14:45:09 <bcoca> forget faucet, smart toilet
14:45:21 <acozine> aaaaaand on that note, let's turn to the agenda
14:45:27 <felixfontein> lol yes
14:45:36 * bcoca is master of ending tangents
14:46:03 <samccann> heh everyone has a special talent!
14:46:23 <acozine> today's agenda is at https://github.com/ansible/community/issues/521#issuecomment-606234088
14:47:06 <acozine> ahem
14:47:08 <acozine> correction
14:47:15 <acozine> today's agenda is at https://github.com/ansible/community/issues/521#issuecomment-600166114
14:47:33 <acozine> #topic contributor summit summary
14:47:52 <samccann> #info Contributor summit summary - https://meetbot.fedoraproject.org/ansible-community/2020-03-29/ansible_contributor_summit_2020.2020-03-29-10.50.html
14:48:12 <samccann> #info contributor summit log - https://meetbot.fedoraproject.org/ansible-community/2020-03-29/ansible_contributor_summit_2020.2020-03-29-10.50.log.html
14:48:20 <samccann> (thanks to gundalow for those links!)
14:48:30 <gundalow> I'll be doing a full write up over the next week or two
14:48:52 <acozine> gundalow: awesome
14:49:44 <acozine> conversation around docs at the summit mostly focused on two topics:
14:50:17 <acozine> 1. what are our options for changelogs and porting guides in the New World Order (NWO)
14:50:33 <acozine> 2. how will Ansible docs generally be handled in the NWO
14:51:07 <felixfontein> ah, I've been always wondering what NWO actually is
14:51:08 <acozine> at least, that's what I heard in the limited time I was there
14:51:35 <felixfontein> these are the two questions I'm most interested in, and I don't remember any other TBH
14:51:48 <samccann> #info docs discussions focues on changelog/porting guide optins and how ansible docs will be handled in the NWO
14:52:40 <samccann> NWO = New World Order ... which always sounds to me like the bad guys in a Star Wars film...
14:52:49 <acozine> felixfontein: do you have questions about the how-will-docs-happen part?
14:52:51 <felixfontein> or james bond
14:53:19 <felixfontein> acozine: not really, I've decided to wait and see what abadger1999 does about that ;)
14:53:19 <acozine> I keep trying to pronounce it as a word . . . nuhwhoah
14:53:30 <felixfontein> I guess changelog+porting guide is more urgent - at least for me
14:53:53 <samccann> Do we want to switch to that topic then ?
14:53:55 <acozine> yes, the changelogs are going to be tricky
14:54:04 <acozine> samccann: good idea
14:54:18 <felixfontein> fine for me
14:54:21 <acozine> #topic changelogs and porting guides from Collections
14:54:51 <samccann> there was some chatter about 'just let people do what they want, so long as there is a changelog that is consumable by ACD into a combined release note'
14:55:21 <samccann> as in ACD wouldn't deal in fragments, it would deal in the end result and combine them into an ACD change log/ release note
14:55:21 <felixfontein> I think that's the best way to go, since there will be (and already are) too many opinions on which tool would be great
14:55:32 <acozine> hmmm, my interpretation was more "people can do whatever they want, but if they want their changelogs included in ACD, they need to follow these guidelines"
14:55:33 <samccann> heh yeah for sure on the opinions!
14:55:46 <samccann> even that one seems questionable acozine
14:56:03 <acozine> is there a way to combine multiple different types of fragments into a consolidated changelog?
14:56:20 <samccann> except that the guidelines would be  something simple like keep your changelogs for all releases within your repo' or something
14:56:35 <samccann> coding solves all problems :-)  Honestly, i don't know
14:56:47 <samccann> some people want rst, some want yaml, others want .md
14:56:49 <felixfontein> my assumption would be that every collection which wants to be included in the changelog has to provide their changelog in a well-defined format
14:56:59 <bcoca> one way you determine internal workings of repo, the other, just the end results
14:57:07 <bcoca> you really dont need fragments for ACD
14:57:24 <felixfontein> .rst vs. .md is a problem; .yaml is (when only used as a container format) not a problem
14:57:39 <samccann> would we mandate  that the change logs have to be .yaml then?
14:57:44 <gundalow> FYI for community.general we are using the same form as ansible/ansible, we've added a `changelog/fragments` directory  https://github.com/ansible-collections/community.general/tree/master/changelogs/fragments
14:57:55 <bcoca> you can even say 'do whatever you want with final changelog, but give us a json/yaml with all the entries'
14:57:59 <samccann> (not the fragments, but the end release change log per collection would be .yaml for it to be consumed by ACD?)
14:58:19 <felixfontein> I've also added changelogs/fragments/ to community.crypto
14:58:24 <gundalow> I'm happy for this group (DaWG) decides to set a hard requirement of "Do exactly X"
14:58:37 <felixfontein> (and already copied all fragments of interest from ansible/ansible over)
14:58:39 <samccann> OUR WAY OR THE HIGHWAY BUSTER!
14:58:42 <samccann> :-)
14:58:57 <felixfontein> bcoca: I think that would be the best approach
14:59:11 <samccann> here's the thing tho, we need someone to program the solution for ACD. acozine and I don't have the coding chops for that
14:59:16 <felixfontein> then everyone can use their tool of choice, and we don't hvae to deal with all the "but tool X is so much better" discussions
14:59:20 <bcoca> single file is also simpler for doing docs, rather than chasing fragmetns and ensure they are part of the specific release
14:59:50 <samccann> but if y'all think 'do what you like but provide .yaml result per release' is good enuf for someone to collect into an ACD change log, that works
14:59:50 <bcoca> samccann: coding is simpler to slurp 1 file per release
14:59:57 <acozine> okay, so our rule would be:
15:00:05 <samccann> heh... coding slurps...
15:00:20 <bcoca> its a technical turm
15:00:26 <bcoca> ...
15:00:46 <acozine> each collection must provide a consolidated version of its changelog in YAML . . .?
15:01:09 <acozine> how do we define the start and end points?
15:01:26 <bcoca> make the file have 'release version' in name
15:01:38 <felixfontein> acozine: I'd say that we keep track of the collection versions included in ACD, and use them to extract changelogs for the versions inbetween
15:01:43 <bcoca> then internally structure as 'we need it', e.g minor: , bugfixes: , etc sections
15:02:03 <samccann> hmmm
15:02:21 <gundalow> I don't think most people will be interested in defining there own system. Changelogs are more of an overhead to people
15:02:22 <samccann> how would we know minor vs bugfix etc in a combined release note?
15:02:42 <felixfontein> samccann: they'll be in different sections in the .yaml file
15:02:47 <bcoca> samccann: the file has sections, as above, just like the fragmetns tdo
15:02:52 <samccann> only if we mandate that tho, right?
15:03:13 <bcoca> gundalow: we can do both, here is recommended 'change log managment', but if you dont want that 'this is REQUiRED output for ACD inclusion'
15:03:16 <felixfontein> yes, we should mandate how the files should look like, otherwise it won't work anyway
15:03:17 <samccann> I mean i can create any ol .yaml file format and just say 'my spiffy release x has these spiffy new thingies'
15:03:32 <samccann> yeah oka what felixfontein said
15:03:43 <acozine> current fragments come from: https://github.com/ansible/ansible/tree/devel/changelogs/fragments
15:03:51 <bcoca> gundalow:  i assume you are already adapting the ansible tool for community.general, easy to offer to rest, but i would not mandate it
15:03:55 <samccann> so we need to say 1 - create a .yaml and have it available per release (per major,minor release)?
15:03:58 <felixfontein> I'll try to create a proposal later today
15:04:08 <felixfontein> (if nobody else wants to)
15:04:13 <abadger1999> I don't think the idea of a container works....
15:04:14 <samccann> and then 2. it must have this format (and specify it to match what ansible/ansible uses today?)
15:04:26 <samccann> welcome abadger1999 !!
15:04:26 <abadger1999> You still have to specify the format of the content in the container.
15:04:30 <abadger1999> Hi :-)
15:04:38 <acozine> #chair abadger1999
15:04:38 <zodbot> Current chairs: abadger1999 acozine bcoca felixfontein gundalow samccann tremble
15:04:39 <felixfontein> abadger1999: that's what we want to do, I think
15:05:32 <samccann> felixfontein -if you create a proposal, can you either add it here or link to this issue so we can keep track? - https://github.com/ansible-collections/overview/issues/18
15:05:36 <bcoca> abadger1999: which we did above
15:06:04 <abadger1999> No, you didn't.
15:06:15 <abadger1999> You specified the structure of the container.
15:06:22 <abadger1999> But the format of the text also matters.
15:06:52 <bcoca> sam had already established yaml format
15:07:35 <abadger1999> ie:  I have one change but when I write up the changelog I want to put in multiple paragraphs, a bulleted list, a code example, and a link to a module.
15:07:59 <abadger1999> So the format of the tet itself matters, not just the format of the yaml container.
15:08:00 <felixfontein> very quick sketch of how it could look like: https://gist.github.com/felixfontein/d15112c7a866e8806d7e9f9ea4085cfa
15:08:21 <felixfontein> entries are assumed to be .rst (didn't write that yet)
15:08:37 <abadger1999> Also... file encoding.  (Please just specify, must be in utf-8.)
15:09:00 <samccann> the one addition maybe - do we want to add an 'upgrade' section so we could pull that out of the changelogs and create a porting guide for ACD?
15:10:18 <acozine> what are the other categories? we have `bugfixes` and `minor_changes`, is there also a `major_changes` category?
15:10:26 <abadger1999> Hmmm.... what are we trying to solve here?  Allowing people to use differing tools?
15:10:49 <samccann> i think that's it yeah abadger
15:11:05 <samccann> we can't seem to get everyone to say 'this is the tool all relevant collections shall use'
15:11:18 <abadger1999> One problem I see with mandating a specific container format is that everyone using different tools will need to write some code to output the container format instead of what the tool usually does.
15:11:41 <felixfontein> abadger1999: true, but that's better than us writing tools to parse what their tools output
15:11:59 <abadger1999> We want to avoid: https://xkcd.com/927/
15:12:06 <abadger1999> felixfontein: yes.  I agree.
15:12:27 <acozine> abadger1999: what folks want is freedom and flexibility to do what they want in their own collections, plus the ability to combine all the various solutions into a single changelog for ACD
15:12:30 <felixfontein> also they can always stick to the tool we recommend, and not have to do anything special
15:12:33 <acozine> and we may not be able to have both
15:12:55 <gundalow> acozine: apart from openstack, does anyone else want to do their own thing?
15:14:04 <felixfontein> zbr has made the argument for release-drafter
15:14:16 <acozine> gundalow: I can't point to anyone specific, but my recollection from a couple of weeks ago was that `reno` and `towncrier` were both popular tools, with the ansible "value-added" solution as a third contender . . . and no consensus on which was best
15:14:32 <abadger1999> felixfontein: It seems like it becomes a question of.... is it more platable for people using non-standard tools to agree that they have to write a plugin for their own tool to output that format or for them to write a tool which transcodes the input to the output format we expect?
15:14:56 <abadger1999> *transcodes their input format to the input format we expect
15:15:42 <samccann> hmm  vs people switching to the tool we mandate for inclusion in ACD?
15:15:43 <abadger1999> Either way, they're going to have to write code.
15:15:44 <zbr> in fact I already have a python tool i used to automate label management on github which I was planning to make it also do the same stuff as release drafter
15:15:54 <abadger1999> samccann: yeah.... I figure, that's always an option ;-)
15:16:12 <zbr> but i did not had time to implement that big
15:16:45 <felixfontein> abadger1999: if they use our tool, they don't have to write any code, just changelog fragments ;)
15:17:43 <abadger1999> felixfontein: yep :-)  But if they're all willing to use our tool, then the rest of this discussion becomes moot ;-)
15:18:09 <samccann> well then it becomes 'use our tool or write some transforming code to get to our format'?
15:18:18 <abadger1999> Yep.
15:18:27 <felixfontein> abadger1999: in that case, we've just specified what our first tool outputs, and what our ACD tool inputs
15:18:57 <abadger1999> samccann: I think no matter whether we're talking about just having them write out fragments or having them write out a container format, that's what it boild down to.
15:19:48 <abadger1999> So to me the question is.... Will a container format get more people to write a transformation tool vs their input -> our input transformation.
15:20:50 <acozine> any idea how we figure out the answer?
15:20:51 <abadger1999> if not.... using a container format is extra work for us too (we'd have to write the code to recognize both  the container and fragments for whatever tool we're using)
15:22:13 <felixfontein> abadger1999: I think we need to adjust our tool to something like that anyway; the current way it works doesn't work well if a collection decides to never have stable branches - they'd end up with an ever growing folder of fragments
15:22:43 <abadger1999> I don't know for sure.  Ask people who are deadset on using their tool, I guess?
15:23:12 <felixfontein> I don't know if there are already plans on how community.general will be versioned. but if there are just new versions (and no stable branches and backports), the changelog fragment folder will grow pretty rapidly
15:24:23 <felixfontein> even if community.general doesn't do this, some other collection will surely do that (because it's the simplest way)
15:24:28 <acozine> abadger1999: heh
15:24:38 <samccann> evergrowing folder of fragments seems to be what openstack does? At least my review of it seems that way and it works for them over years.
15:25:29 <samccann> then again, I don't know how big community.general is compared to the more active openstck projects like ironic etc
15:26:06 <abadger1999> I'm not sure if the evergrowing folder is an issue.  An ever growing changelog might be, though?
15:26:55 <acozine> yeah, we don't want to repeat all the changelog entries from 2.10 in the 2.11 changelog
15:27:19 <acozine> in ansible/ansible we handled that by deleting old entries after branching the new stable branch
15:27:25 <samccann> so something like community.general with lots of fragments - would have a problem on their own if they had only one superlong changelog file (aka no stable branches)?
15:27:42 <felixfontein> samccann: you could split it up into multiple files
15:27:47 <felixfontein> like one per month or year
15:27:49 <acozine> but as felixfontein said, if a collection has no stable branches with backports, then those old entries will never go away
15:27:51 <abadger1999> samccann: well.... sort of.
15:27:52 <samccann> and in openstack I think they handle that by grabbing just the fragments tied to the release (might be done by filename?)
15:28:02 <abadger1999> samccann: There's other ways to manage that besides branches.
15:28:39 <felixfontein> my proposal (https://gist.github.com/felixfontein/d15112c7a866e8806d7e9f9ea4085cfa) allows to split up the changelog into multiple files (even among multiple branches, which would be required for the model ansible/ansible uses)
15:28:48 <samccann> btw my openstack comparisons should be taken w/ a grain o salt. I didn't work with them, I just took a look at what was in their folders vs their output files
15:28:55 <felixfontein> "proposal"
15:29:03 <abadger1999> (*) If there's never multiple streams of development, delete fragments that were in the last major release when you start developing the next major release.
15:29:44 <acozine> felixfontein: thanks for the proposal, it really helps to have something concrete to discuss
15:29:58 <abadger1999> (*) Create a new directory after every release.  Before you make the new release, decide whether you want to merge the changelogs (copy this directory into the old one) or have a new changelog (point your tool at the new directory)
15:29:58 <felixfontein> abadger1999: but we might need also these entries, when they released several major versions during one release cycle of ACD
15:31:31 <acozine> in felixfontein's proposed model, we define the output (which is the "container" abadger1999 was talking about???) and let collection owners decide how to create it?
15:31:50 <abadger1999> (*) Use a tool like reno instead of the ansible/ansible tool.  Then you can use git tags to manage that.
15:31:51 <abadger1999> Yep.
15:32:26 <abadger1999> Well... felix's proposal is both container and format.
15:32:37 <abadger1999> If you look, his changelog entries contain rst formatting.
15:32:43 <acozine> and then for the ACD changelog, we pull entries based on `first_included_collection_A_release` through `latest_included_collection_A_release` for each included collection, using the version numbers in the output/container
15:33:01 <felixfontein> acozine: yes
15:33:06 <samccann> there were comments in the issue about not wanting to mandate git tags I think (and was a reason ansible/ansible created our own solution)
15:34:24 <samccann> https://github.com/ansible-collections/overview/issues/18#issuecomment-603976620 for reference
15:34:42 <abadger1999> samccann: for your earlier question about how openstack decides which ones to grab... I think they use reno so they're based off of whether a commit happened after tag 1.0.0 and before tag 2.0.0 (for isntance)
15:34:43 <samccann> from mattlcay
15:35:02 <samccann> ah gotcha.. thanks abadger1999  that sounds familiar now
15:35:59 <acozine> felixfontein: abadger1999: the main objection to felix's proposal is that collection owners may not follow the rules, so the ACD changelog will be incomplete? or it would be more work (for the community/core teams? for collection owners?)?
15:36:07 <acozine> or both?
15:36:35 <felixfontein> if collection owners don't follow the rules, it doesn't depend on the procedure we want to establish, it will always not work :)
15:36:47 <felixfontein> i.e. changelog is incomplete / we can simply link to their changelog
15:36:51 <samccann> heh
15:36:58 <acozine> very true
15:37:01 <abadger1999> I guess.... I like felixfontein's proposal if collection owners who don't use whatever tool we mandate are willing to implement their side of it (writing out their changelogs in that format).
15:37:37 <abadger1999> If they aren't willing to, though, then my objection would be that it's extra work that isn't useful.
15:37:55 <abadger1999> Oh... felixfontein would the core team have to output that format as well?
15:38:15 <felixfontein> abadger1999: that would make it easier I guess
15:38:43 <felixfontein> in my ideal world, the currently internal tool used by core would be extended to a public tool which can be used for collections and which outputs this format
15:39:02 <felixfontein> and in my even more ideal world, everyone would simply use that tool ;)
15:39:05 <acozine> abadger1999: felixfontein: in this scenario, we would have two options for collection owners - 1. use our tool, or 2. use your own solution and provide us with a file that looks like <proposal>
15:39:07 <abadger1999> Okay, so the extra work would be: (1) core team has to get the ansible/ansible changelog generator to output the new format.  (2) the community team would have to write code for the acd changelog generator to consume the new format.
15:40:19 <felixfontein> I think so
15:40:31 <abadger1999> acozine I agree with that statement
15:40:49 <acozine> abadger1999: thanks, I'm trying to get things clear in my head
15:41:04 <felixfontein> so what's the atlernative(s) to that proposal?
15:41:11 <felixfontein> *alternative
15:41:33 <acozine> so close to `antlernatives`
15:41:44 <abadger1999> hee hee
15:41:45 <felixfontein> heh
15:41:50 * acozine sees Internet Deer everywhere
15:42:13 <samccann> #info one idea - we would have two options for collection owners - 1. use our tool, or 2. use your own solution and provide us with a file that looks like <proposal> https://gist.github.com/felixfontein/d15112c7a866e8806d7e9f9ea4085cfa
15:42:25 <acozine> what are our other alternatives?
15:42:30 <samccann> #info this would require (1) core team has to get the ansible/ansible changelog generator to output the new format.  (2) the community team would have to write code for the acd changelog generator to consume the new format
15:42:57 <acozine> is there any scenario in which we can use the current tool without modifications?
15:43:15 <abadger1999> (A) We mandate one tool (B) We link to people's disparate changelogs (C)  people write an input => input transform + metadata  of what input fragments are needed for the next release.
15:43:18 <felixfontein> I guess probably not
15:44:04 <felixfontein> for (A) we'd still have to integrate that tool's output with core's changelog
15:44:21 <felixfontein> (B) is definitely the least amount of work (and the generic fallback :) )
15:45:04 <abadger1999> I like felix's proposal better than (C).  But it would be what do collection owner's like better rather than what I like better :-)
15:45:09 <acozine> (A) and (C) put the burden on collection owners; (B) puts the burden on users
15:45:10 <samccann> #info another idea - we mandate one tool and integrate that tool's output with core's changelog (aka collections in ACD would not have a choice but must use this tool)
15:45:16 <felixfontein> I'm not fully sure what (C) is (resp. how it is different from my proposal, except that there are individual fragments instead of a container)
15:45:50 <abadger1999> felixfontein: yep, that's the only difference.
15:46:00 <samccann> #info - third idea - we link to peoples disparate change logs (least work, but doesn't give comprehensive view of changes, just a bunch of links users have to follow)
15:46:58 <samccann> #info - fourth idea - people write an input => input transform + metadata  of what input fragments are needed for the next release. - similar to first proposal, but there are individual fragments instead of a container
15:47:23 <acozine> abadger1999: how much work would be involved in (A)? are any of the tools truly plug-and-play for our needs?
15:47:24 <abadger1999> Hmmm.... If ACD was a Linux Distro...... changelogs would be links.  however, there would be a common release notes that individual components could contribute things they considered major enough to be worthy of that.
15:47:28 <felixfontein> for (A), we would need a flexible tool which people would actually adopt. it needs to be flexible enough to allow different release models
15:48:12 <samccann> #info fifth idea - we handle ACD like a linux distro - changelogs would be links.  however, there would be a common release notes that individual components could contribute things they considered major enough to be worthy of that.
15:48:23 <acozine> abadger1999: yes, that's analogous to how we've used the Porting Guides
15:48:24 <felixfontein> abadger1999: collection owners would have to write these, and ACD maintainers would have to collect these from them (sounds painful to me :) )
15:48:33 * samccann wishes she numbered from the first idea... since we know have six ideas... but anyway
15:49:16 <samccann> Are we at a point where the handful of us here can rule out any of these six different ideas?
15:49:31 <abadger1999> felixfontein: <nod>  Yeah...  I'll also note that in the release note/linux distro model.  Most of that work happens on the major release boundary.  Very few things enter the release notes on updates.
15:50:36 <felixfontein> (A) ('another idea') depends a lot on which tool is chosen
15:50:44 <abadger1999> felixfontein: It would probably be more of a pain for the collection owners.  ACD maintainers would probably just merge changes from the collection owners.
15:52:00 <abadger1999> (A) and flexibility... i think many of the tools are flexible but targetted for certain workflows.  So other workflows are possible but would end up fighting the tool.
15:52:07 <felixfontein> sounds like a lot of fun for community.general :)
15:52:42 <abadger1999> (Core could have made reno work for them but would have ended up fighting with the git tagging autodetection of versions, for instance)
15:52:57 <acozine> what's the best way to take the next steps? write up all the available options with pro/con lists?
15:53:19 <acozine> try to do a short demo of one option?
15:53:43 <abadger1999> Our goal is to have as complete a changelog as possible, right?
15:53:51 <felixfontein> and a porting guide
15:53:55 <felixfontein> (I think)
15:54:37 <acozine> from a docs perspective, the goal is to have a useful porting guide - one that tells users what changes they must make to their playbooks
15:54:39 <felixfontein> and potentially a way to show a combined changelog and combnied porting guide for people wanting to upgrade from ACD 2.10.3 to 2.13.6
15:54:48 <samccann> porting guide seems critical imo.  I don't have any stats to say how often users read the changelogs we produce
15:55:01 <acozine> I suspect only developers read the changelogs
15:55:04 <abadger1999> Okay.. from an ACD perspeciv, I think the same tool could write out both (core would need to either expand its current tool or write a new tool)
15:55:50 <acozine> using one tool for both the total changelog and for the this-affects-playbooks porting guide would be awesome
15:57:09 <abadger1999> I don't think that any of the upstream tools are reall optimized for having differing porting guides and changelogs.
15:57:40 <abadger1999> They might be able to keep separate directories of fragments for each.
15:58:34 <felixfontein> I'd also expect the fragments of a porting guide to be more like sections, while fragments for a changelog are more like sentences
15:58:45 <felixfontein> (resp paragraphs)
15:58:55 <acozine> could we have a category or tag for `porting_guide` changes? then pull those into a skeleton porting guide?
15:59:09 <samccann> that was what I suggested with the upgrade section
15:59:25 <acozine> samccann: ah, I missed that . . . I like your idea
15:59:27 <samccann> (I think reno uses that?) but then reno doesn't pull out a separate porting guide
15:59:53 <samccann> so I was just trying to piggyback the porting guide fragments into the changelog fragments
15:59:55 <acozine> I agree with felixfontein that a proper porting guide should have more than one-sentence entries
16:00:15 <samccann> i think the proposal allows for that right, with embedded .rst
16:00:39 <acozine> but at least knowing what topics we need to include is a start
16:00:48 <felixfontein> samccann: partially... it currently only allows whole sections (with title), but I guess that's not flexible enough
16:01:05 <samccann> ah gotcha
16:01:27 <abadger1999> For reno, we'd have to repurpose one of their existing sections, I think: https://docs.openstack.org/reno/latest/user/usage.html#editing-a-release-note
16:01:36 <felixfontein> I think there are parts of the porting guides which are very close to a changelog, and other parts which are more like document sections
16:03:35 <abadger1999> Note that talking about upstream tools..... these concerns would be up to the collection owners to resolve.
16:04:38 <abadger1999> Since they're the ones who would need to write out the file with the unified format for our consumption.
16:04:40 * acozine notices we've gone 30 minutes over the usual meeting length
16:04:52 <felixfontein> almost 35 :)
16:05:04 <acozine> felixfontein: always with the Swiss precision . . .
16:05:19 <samccann> heh
16:05:22 <felixfontein> abadger1999: I guess most collections wouldll do the porting guide part manually
16:05:53 <abadger1999> <nod> Yeah, that would be fine from our side.
16:06:12 <felixfontein> it's mainly for community.general that this is painful
16:06:28 <bcoca> the more you split off, less painful
16:06:40 <felixfontein> true
16:06:50 <bcoca> s/less painful/distributed the pain/
16:07:11 <samccann> even a manual collection level porting guide would have to be parsable by ACD to create an ACD porting guide, right?
16:07:25 <felixfontein> samccann: yes
16:07:34 <bcoca> automating porting guide is pretty hard, would require massive changelog/commit entries
16:07:45 <felixfontein> if we don't want to resort to "just link to it and let the users figure it out"
16:07:47 <bcoca> or 'additional porting fragments'
16:07:58 <abadger1999> acozine, samccann So way forward... (1) Are there any of these proposals that we think are definitely less desirable for collection owners?  let's either strike those from the list.
16:07:59 <bcoca> felixfontein: only when we hate the users
16:08:03 <felixfontein> bcoca: yes
16:08:20 <samccann> that's what we were talking about - porting fragments and can we piggyback on the changelog fragments to achieve this
16:09:34 <acozine> abadger1999: agreed
16:09:41 <samccann> and are any of these proposals definitely less desireable for collection/ACD users? as in, is it an option to just have ACD release note as a linkfest back to the collection level changelog file(s?) aka the linux distro approach?
16:10:09 <acozine> I think we need to have one document somewhere that lists all the options, with pros/cons for each
16:10:18 <felixfontein> I think that's not desirable, but the fallback option we'd have to use for collections that don't want to help us (or if we don't manage to have a tool in time)
16:10:18 <acozine> aka I don't think IRC is the best format for comparing
16:10:38 <bcoca> depends on scop, if ACD == 12334 collections .. then i would link, if ACD== 12 collections .. i would try to aggregate
16:11:07 <samccann> abadger1999 - any idea yet how many collections in ACD first release?
16:11:16 <acozine> samccann: could you and I put together a three-column document, with 1. Option 2. User Pain Points 3. Maintainer Pain Points ?
16:11:20 <abadger1999> I can get the list.
16:11:52 <abadger1999> https://github.com/abadger/misc-work/blob/master/ansible/build_acd/acd.in
16:12:09 <abadger1999> 55 collections listed in there.
16:12:10 <samccann> acozine we can create the shell, but a) - where is it publically visible and editable? and b) we can only guess at some of the maintainer pain points for sure (this the need for editable for the community)
16:12:33 <felixfontein> 55 is "fun" for links
16:12:38 <samccann> #info ACD as currently envisioned would have 55 collections
16:13:07 <bcoca> as person 'not doing the work' .. at that number i lean to links
16:13:34 <abadger1999> samccann: I think the linux distro approach of linking to upstream is okay for changelogs.  We do need a porting guide story though.
16:13:46 <abadger1999> (for ACD users)
16:14:16 <samccann> agreed
16:14:19 <bcoca> well, acd needs to at least incoporate ansible-base porting guildes
16:14:33 <bcoca> since that is normally biggest impact to 'playbook language'
16:14:47 <abadger1999> Also, I do agree with felixfontein about it being desirable for the end users.... but it is within the realm of "this is okay if we have to"
16:14:55 <abadger1999> *being less esirable
16:14:58 <abadger1999> *being less desirable
16:15:03 <acozine> heh
16:15:16 <bcoca> also, something that can change in future, right now there are also time constraints to deal with
16:15:16 <felixfontein> yes :)
16:15:19 <samccann> the difficulty with an ACD porting guide for 55 collections - getting the info into it, across potentially multiple collection-level release for each of the 55
16:15:23 <bcoca> and user feedback will guide us
16:15:38 <acozine> samccann: we can create a google doc and make it public, right?
16:15:54 <acozine> and link it to the GitHub issue
16:15:56 <bcoca> ^ use community overview?
16:16:00 <samccann> dunno acozine - never tried to have it visible outside of RH peers
16:16:09 <acozine> I'm pretty sure it's possible
16:16:18 <abadger1999> we could also do etherpad.
16:16:20 <acozine> if it's not, we can copy the content to a gist
16:16:31 <abadger1999> or create a google doc from a non-redhat account
16:16:31 <bcoca> gh wiki ...
16:16:32 <acozine> ah, etherpad is good
16:16:38 <bcoca> docs_plan.md
16:16:39 <felixfontein> etherpad sounds nice, then everyone can edit it
16:16:58 <gundalow> acozine: samccann You can't share Google Docs outside of redhat.com. Please use A) gh/ansible-collections/overview B) Etherpad
16:17:12 * acozine has mixed feelings about everyone editing ;-)
16:17:19 <gundalow> GitHub should be the default place for stuff
16:17:19 <samccann> is the overview github editable by everyone?
16:17:33 <acozine> github works
16:17:34 <felixfontein> samccann: only for members
16:17:36 <gundalow> samccann: nop then anyone can add a comment, then if we like it we can update the first comment
16:17:57 <acozine> I care less about where we do it, and more about getting a summary in one place
16:18:04 <samccann> and ok so basically a continuation of the issue I put the reno/towncrier summary in
16:18:16 <gundalow> samccann: sounds good
16:18:43 <samccann> #agreed we will add the pros/cons for all the ideas here - https://github.com/ansible-collections/overview/issues/18
16:18:46 <gundalow> \o/
16:18:47 <gundalow> Thanks
16:18:53 <abadger1999> Cool
16:19:56 <acozine> phew, thanks gundalow abadger1999 felixfontein samccann bcoca tremble
16:20:10 <felixfontein> thanks everyone!
16:20:12 <felixfontein> almost two hours :D
16:20:26 <acozine> one hour fifty minutes ;-)
16:20:30 <acozine> but who's counting?
16:20:32 <felixfontein> the longest docs meeting ever?
16:20:37 <acozine> very possibly
16:20:56 <acozine> a really good one, and an important one
16:21:18 <acozine> keep an eye on that issue, folks
16:21:32 <acozine> we'll also post updates when we've got things ready to review
16:21:51 <acozine> #topic open floor
16:22:02 <acozine> just in case someone has been waiting and watching this whole time
16:22:06 * samccann ponders who stayed this long
16:22:09 <felixfontein> are you trying to get to two hours? :D
16:22:16 <acozine> and wondering when they'd get a chance to pipe up
16:22:29 <acozine> felixfontein: we're going for a record!
16:22:42 <acozine> though you're probably right that we've already set one
16:22:57 <acozine> going once . . .
16:23:13 <acozine> open floor going twice . . .
16:23:40 <acozine> looks like no takers
16:23:48 <acozine> thanks again everybody!
16:23:51 <acozine> #endmeeting