14:30:31 <acozine> #startmeeting Docs Working Group aka DaWGs
14:30:31 <zodbot> Meeting started Tue Mar 17 14:30:31 2020 UTC.
14:30:31 <zodbot> This meeting is logged and archived in a public location.
14:30:31 <zodbot> The chair is acozine. Information about MeetBot at http://wiki.debian.org/MeetBot.
14:30:31 <zodbot> Useful Commands: #action #agreed #halp #info #idea #link #topic.
14:30:31 <zodbot> The meeting name has been set to 'docs_working_group_aka_dawgs'
14:30:57 <acozine> #topic message of mutual support
14:32:04 <acozine> the spread of COVID-19 has shown us all how dependent we are on each other, and how much the choices we all make affect us all
14:32:25 <dmellado> o/
14:32:29 <samccann> \o
14:32:46 <acozine> I hope everyone on this channel has a safe place to be, access to health care when needed, plenty of food, and some source of joy in their lives
14:33:10 <dmellado> acozine: likewise, I'm having some issues getting some out-of-stock items
14:33:21 <dmellado> but should be replenished tomorrow, I'll go early in the morning, though
14:33:26 <acozine> and for anyone who has time, attention, and energy left over from taking care of fundamental needs . . . we welcome your work on the Ansible docs
14:33:40 <acozine> dmellado: sorry to hear it
14:34:03 <acozine> I hope you find the things you need
14:34:23 <dmellado> acozine: thanks, I still don't understand the rush on toilet paper xD
14:34:54 <acozine> esp. in the US, where the toilet and the shower are generally right next to each other . . .
14:35:19 <cbudz> well when the close the liquor stores we won't hear much about toilet paper
14:35:39 * gundalow waves
14:35:43 <acozine> oh, dear, that is probably true
14:35:46 <felixfontein> here in Switzerland it got harder to buy tofu, even on the countryside people seem to stock that up...
14:36:07 <acozine> tofu? wow, I have not heard that here
14:36:09 <felixfontein> but there's still enough food to not starve ;)
14:36:35 <bcoca> tofu can be stored a long time and has high nutrition density, its actually a smart choice
14:36:57 <acozine> true, but I still haven't heard that it's in short supply in the US
14:37:49 <felixfontein> bcoca: indeed.
14:37:51 <acozine> I guess Swiss people are better educated about nutrition and/or smarter shoopers
14:37:56 <tadeboro> I cannot complain much since the biggest issue for me here in Slovenia is having to share my "home office" with kids.
14:38:03 <acozine> er, shoppers
14:38:03 <felixfontein> it's not really short supply, but usually there's plenty of it around :)
14:38:13 <dmellado> in any case hope everyone's safe, I'm used to WFH but I'm starting to get the NEED of fresh air, despite the lockdown
14:38:16 <bcoca> we are major producers of soy beans .. and our main market was lost due to trade war, americans dont consume as much
14:38:25 <felixfontein> tadeboro: I think that's pretty common world-wide (for the people having kids that is)
14:38:30 <bcoca> so we probably overstocked
14:38:45 <felixfontein> bcoca: good for you (at least now)
14:38:54 <acozine> tadeboro: are they schooling-from-home?
14:39:17 <felixfontein> it feels like schools are closed in most countries in Europe now
14:39:24 <bcoca> <= has had no change, i see humans 1/week for shoppping and mostly stay at home all day (walk outside at 6am when streets are mostly deserted)
14:40:08 <felixfontein> bcoca: is that you? https://xkcd.com/2276/
14:40:12 <acozine> many US schools are trying to do online classes
14:40:22 <tadeboro> acozine: They do. They get instructions on a daily basis from teachers and then do the work with the help of their parents.
14:40:23 <andersson007_> our kids are allowed not to go to school
14:40:27 <bcoca> felixfontein: that is biographical, yes
14:40:28 <felixfontein> acozine: here too, though a lot are not prepared at all...
14:40:48 <dmellado> I have a toddler about 1yo and he just learned how to walk around the house xD
14:41:33 <felixfontein> sounds like dmellado got the jackpot!
14:41:47 <acozine> andersson007_: that's tough on parents, but probably good public health policy
14:42:00 <felixfontein> the perfect age of children where you can hardly do anything else than watch them :D
14:42:33 <andersson007_> acozine: yes, especially for parents who are working from home and who have more than one kid:)
14:42:36 <acozine> yeah, at that age they're mobile but not yet able to follow instructions
14:43:06 <bcoca> "wall of velcro"TM : best way to deal with kids
14:43:11 <acozine> later they're mobile and just refuse to follow instructions, but at least they can start to understand the laws of cause and effect
14:43:41 <cbudz> my 4 year old is at peak "refuse to follow instructions" so we're taking turns here
14:44:21 <acozine> frequent exercise breaks? jumping jacks, back bends, skipping rope? . . . that's what I'm doing to maintain my sanity
14:44:36 <bcoca> acozine: funny, that is what im NOT doing to maintain sanity
14:44:57 <bcoca> i do have standing desk and static bike though
14:45:00 <cbudz> I am trying to motivate myself to follow an exercise routine like that
14:45:11 <bcoca> cbudz: chasing a 4yr old not enough?
14:45:22 <felixfontein> bcoca: good reminder, I forgot that my desk here at home can be height adjusted
14:45:24 <acozine> bcoca: everybody's different . . . exercise helps me feel less anxious
14:45:35 <acozine> ooh, mine too
14:45:41 * acozine cranks her desk up to standing position
14:46:43 <bcoca> acozine: makes you release 'happyness' hormones, kind of why opiates are soo addictive
14:46:50 <acozine> this is a view I don't see every day . . . i should do this more often
14:48:07 * tadeboro moves some toys from under his chair so he can stretch his legs a bit
14:48:10 <acozine> well, shall we talk docs?
14:48:16 <acozine> anybody with kids at home, feel free to post the stuff your kids say or do while we chat
14:49:10 <bcoca> my sister was about to bring my niece over, but i suddenly had a cough fit on the phone ....
14:49:20 <acozine> #chair samccann cbudz tadeboro bcoca felixfontein andersson007_ dmellado
14:49:20 <zodbot> Current chairs: acozine andersson007_ bcoca cbudz dmellado felixfontein samccann tadeboro
14:49:33 <acozine> anybody else around?
14:50:30 <acozine> #topic collection template
14:50:45 <felixfontein> is that the README template?
14:50:52 <acozine> felixfontein: yes
14:51:06 <acozine> yesterday samccann created a template for the collection README
14:51:13 * acozine scrambles for a link
14:51:34 <acozine> anybody have that PR link handy?
14:52:03 <samccann> https://github.com/ansible-collections/collection_template/pull/1
14:52:07 <tadeboro> https://github.com/ansible-collections/collection_template
14:52:11 <acozine> samccann: excellent, thanks
14:52:50 <acozine> so this is our first draft, what do folks think? what else should we add? should we remove anything?
14:53:13 <samccann> #info Collections readme.md template available now as part of a templated repo to start your collection with - https://github.com/ansible-collections/collection_template
14:53:56 <samccann> Individual collection authors can add/modify to suit their needs of course.
14:54:09 <acozine> oof, I forgot that the markdown view doesn't show the comments
14:54:40 <acozine> to see what the developer would see: https://github.com/ansible-collections/collection_template/pull/1/files
14:54:51 <tadeboro> Raw view: https://raw.githubusercontent.com/ansible-collections/collection_template/master/README.md
14:55:06 <gundalow> #info https://github.com/ansible-collections/collection_template is a "GitHub Template Repo". The idea is when someone next asks for a Collection Repo we will just clone this one. We will add a basic working GitHub Action in as well
14:55:29 <acozine> tadeboro: ah, thanks, that's a better link
14:55:48 <samccann> I think there's a button 'use this template' and that's how you use it to create your own repo
14:55:55 <gundalow> yup
14:56:59 <acozine> I'm wondering if we should put all the optional sections together, and make them all the same heading level
14:57:05 <acozine> maybe group them at the bottom
14:57:39 <acozine> right now it looks a bit like `Supported connections` is a subset of `External requirements`
14:58:18 <samccann> I don't think we should group all the optional sections together. They should be placed in an order that makes sense for the overall flow
14:59:18 <samccann> as to whether a supported connection is an external requirement? Dunno. Originally that was just a Requirements section so it made sense in my mind that supported connections was a subset of that
14:59:28 <acozine> ah, that makes sense
14:59:51 <bcoca> wont most networking collections supply their own connection plugin?
15:00:10 <bcoca> aside from windows, i cannot think of a collection that would really need that section
15:00:19 <tadeboro> I feel the current document will work great once there is more content in it.
15:00:41 <tadeboro> Currently, it looks a bit weird since there are only titles in it.
15:00:55 <acozine> bcoca: users would still need to set the connection, wouldn't they?
15:00:56 <samccann> that's why it's optional. The network folks felt strongly they needed it, and the stat was '1/3 of modules are network' so I put the section in the template but listed it as optional
15:01:26 <samccann> tadeboro - the file is full of comments. look at it raw
15:02:03 <samccann> I could have left them visible but as this is a template, it seemed more appropriate to keep the comments hidden so a new collection doesn't have to delete them all if they don't want to
15:02:43 <acozine> would links to a couple of example README.md files in the comments help?
15:03:23 <tadeboro> samccann: I just wanted to say that at least some of the problems related to "is this a subsesction of something else" will go away once the document is hydrated by the collection maintainer.
15:03:54 <acozine> good point
15:04:14 <felixfontein> I like the template
15:04:22 <tadeboro> As for the connection plugins, it feels a bit strange to have them listed as requirements, since they are something that the collection provides.
15:04:23 <felixfontein> maybe we should fill it out for community.general and see how the result looks like :)
15:04:31 <acozine> heh
15:04:44 <acozine> how long will that list of contents be for community.general?
15:04:45 <felixfontein> tadeboro: I guess that mainly makes sense for network modules
15:04:59 <felixfontein> acozine: I guess that section needs to be adjusted for that ;)
15:05:18 <felixfontein> or a summary, "Everything which wasn't moved to another collection" ;)
15:05:45 <acozine> community.general: if you haven't found it by now, it's probably in here
15:06:02 <felixfontein> +1 for that
15:07:05 <acozine> #agreed template README for collections looks good, we will be ready for minor updates once it's in general use
15:07:12 <tadeboro> I guess external requirements are various libraries that need to be present when using a module from collection, like opestacksdk for OpenStack.
15:07:34 <tadeboro> These need to be installed by the end-user while the connection plugins aready come with the collection.
15:07:50 <dmellado> samccann: got dragged into a meeting, will read the notes later, sorry! ping me afterwards if there's any specific thing you'd like to discuss
15:07:52 <tadeboro> But yeah, minor tweak can resolve this later on.
15:07:56 <felixfontein> in the external requirements comment there is a typo: libraires
15:08:09 <samccann> heh woopsie
15:08:22 <acozine> oops, I guess we got stuck between English and French spelling
15:08:30 <acozine> a typo in any language!
15:08:37 <samccann> lol
15:09:17 * acozine remembers her high school French, word for library is biblioteque . . .
15:09:31 <acozine> so much for my multi-lingual education ;)
15:09:56 <acozine> anyway, thanks for catching that felixfontein
15:10:21 <samccann> should we move on to changelog/release note discussion since we have a wide audience today?
15:10:22 <acozine> anything else on the README template?
15:10:38 <acozine> samccann ++
15:10:57 <acozine> #topic ideas for handling release notes for collections and ACD
15:11:53 <acozine> first things first, do we have an issue anywhere for collections release notes?
15:12:05 <felixfontein> I think the kubernetes collection has its own issue for that
15:12:13 <samccann> Not that I know of at the high level
15:12:22 <acozine> felixfontein: link?
15:12:45 <felixfontein> https://github.com/ansible-collections/kubernetes/issues/40
15:13:30 <acozine> thanks
15:13:38 <acozine> that issue points back to https://github.com/ansible/community/issues/384
15:14:16 <samccann> #link https://github.com/ansible-collections/kubernetes/issues/40
15:14:27 <samccann> #link https://github.com/ansible/community/issues/384
15:14:52 <acozine> we need to think about how to gather the changelog data, and how to publish it and make it findable
15:15:04 <acozine> especially in the context of ACD
15:15:08 <samccann> So are we agreed that the things that need release notes/change log are - ansible/ansible (aka base), ACD, and individual collections?
15:15:29 <felixfontein> it would be nice if there is a common changelog / porting guide format which is used by most collections
15:15:50 <acozine> yes to both samccann and felixfontein
15:16:15 <samccann> #info would be nice to have a common changelog/porting guide format used by most collections
15:16:42 <samccann> #info goal is to have them for ansible/ansible (aka base), ACD, and individual collections
15:17:47 <acozine> looks like geerlingguy and webknjaz both have ideas
15:18:19 <acozine> what would be most helpful in moving the discussion forward?
15:18:19 <samccann> dmellado has ideas as well.. don't know if they all overlap or not?
15:18:38 <samccann> and there is the notion of doing it the way ansible/ansible has always done it so to speak
15:18:53 <felixfontein> towncrier and reno were two options which were thrown up earlier in the discussion
15:19:03 <felixfontein> both are similar to what we do right now in ansible/ansible
15:19:25 <felixfontein> towncrier has a simpler format (no YAML), wile reno seems to make assumptions on the git workflow
15:19:34 <felixfontein> (that's all I remember from last week)
15:19:39 <acozine> we can certainly continue to do the ansible-base changelogs the way we've always done it; collections and ACD give us the opportunity to build something better
15:20:27 <acozine> are there demos/examples of each (reno and towncrier) we could look at?
15:21:36 <samccann> openstack uses reno so we could dig into any one of their projects.
15:22:12 <acozine> is this reno output? https://releases.openstack.org/
15:22:43 <samccann> those individual links, at that page yeah
15:22:49 <acozine> at the project level, that includes https://docs.openstack.org/releasenotes/aodh/train.html
15:23:24 <samccann> yeah so the links at that point to individual project release notes built w reno I think
15:24:08 <acozine> I like the approach there, where there are arrows to move from current to earlier release notes within a project
15:24:37 <acozine> but the URLs don't change, so it's hard to share a specific "timeframe" of changes
15:25:35 <tadeboro> Maybe not completelly relevant, but smaller collections may not need all that machinery.
15:25:44 <samccann> yeah these are potential solutions for the individual collections. I don't know anything that builds the equivalent of ACD. I spent some time last week searching for that (and posted here). but came up empty
15:25:50 <acozine> I think OpenStack may be doing something useful with the "series" releases
15:25:55 <acozine> that could be a good model for ACD
15:25:59 <tadeboro> For Sensu, we do it manually like this: https://github.com/sensu/sensu-go-ansible/pull/168/files
15:26:44 <samccann> acozine not following you
15:26:44 <acozine> tadeboro: I like your priorities! `Do not die when encountering a deprecated asset format.`
15:27:27 <felixfontein> tadeboro: that works really well only for collections with a small/disciplined team, I think. otherwise it will be conflict hell very quickly :)
15:27:44 <acozine> samccann: if I've understood the model correctly (that's probably 50/50), OpenStack itself has a "series" release like the `Train` series
15:27:58 <acozine> and projects within OpenStack can have multiple releases within that series
15:28:15 <samccann> afaik the projects only have one release, tied to that series
15:28:22 <acozine> which sounds a lot like what ACD will do
15:28:31 <acozine> samccann: ah, okay
15:28:48 <acozine> so much for "they've solved this problem already"
15:28:55 <samccann> I can dig deeper, but I only found one release per project and it tied to that openstack series.
15:29:22 <samccann> I also dug into fedora/RHEL, which is closer to ACD in the sense that the subcomponents release independently (e.g. gnome, etc)
15:29:46 <samccann> but RHEL/Fedora only have release notes for themselves so to speak, and a list of what package version it includes
15:30:13 <samccann> so I couldn't find a release note in RHEL that told me what changes happened between the kernel release version in say RHEL 8 vs RHEL 8.1
15:31:08 <samccann> so the summary - i couldn't find anyone solving what we are attempting to solve with ACD release notes/porting guides etc
15:31:24 <acozine> that's too bad
15:31:29 <samccann> but I'm open to digging more if anyone knows of other projects I could dig into
15:31:52 <samccann> could we take this approach:
15:32:31 <samccann> - evaluate the three options (reno, towncrier,  the current ansible/ansible approach) - look at what they produce for fragments, and evaluate if some clever coder could pull those fragments together into an ACD release note?
15:32:36 <acozine> could you write up a short table of "other projects we looked at" with which problems they address, how they address them, and which problems we need to address that they don't even try to?
15:32:41 <samccann> and based on that, we decide what approach we reocmmend?
15:33:01 <acozine> samccann: sure, that sounds like a way forward
15:33:38 <samccann> do you still want the table?
15:33:56 <acozine> for future reference, yeah, because I will forget (again) why the OpenStack approach won't cover our use cases unless it's written down somewhere
15:34:19 * acozine uses writing as a way to shorten the time between forgetting and remembering
15:34:34 <acozine> oops, we're over the official time for this week's meeting
15:34:35 <samccann> ok I can add it as a comment to that issue (not the kubernetes one)
15:34:57 <samccann> #action samccann to write a table to show what we've evaluated so far on other projects (openstack, rhel etc)
15:35:09 <acozine> thanks!
15:35:47 <samccann> #agreed - next step is to evaluate the changelog fragments produced by reno, towncrier, and ansible/ansible and see which ones allow us to create a comprehensive ACD release note across different collection releases
15:35:53 <samccann> and we're over by 5 min
15:36:21 <acozine> thanks andersson007_ cbudz felixfontein tadeboro gundalow dmellado bcoca for a great meeting
15:36:45 <acozine> I expect we'll all be online more for the next couple of weeks
15:36:50 <cbudz> yep
15:36:59 <felixfontein> definitely. though not much less busy ;)
15:37:04 <cbudz> I am typically on very early to balance
15:37:14 <acozine> chat in this channel is open to all topics
15:37:23 <acozine> stay safe, healthy, and sane out there, folks!
15:37:29 <acozine> #endmeeting