14:32:00 <acozine> #startmeeting Documentation Working Group aka DaWGs
14:32:00 <zodbot> Meeting started Tue Apr 14 14:32:00 2020 UTC.
14:32:00 <zodbot> This meeting is logged and archived in a public location.
14:32:00 <zodbot> The chair is acozine. Information about MeetBot at http://wiki.debian.org/MeetBot.
14:32:00 <zodbot> Useful Commands: #action #agreed #halp #info #idea #link #topic.
14:32:00 <zodbot> The meeting name has been set to 'documentation_working_group_aka_dawgs'
14:32:33 <acozine> Today's agenda includes https://github.com/ansible/community/issues/521#issuecomment-610521747 and any comments below it
14:32:37 <acozine> who's around?
14:32:37 * samccann waves
14:32:45 <acozine> #chair samccann
14:32:45 <zodbot> Current chairs: acozine samccann
14:32:49 * felixfontein waves
14:32:58 <acozine> #chair felixfontein
14:32:58 <zodbot> Current chairs: acozine felixfontein samccann
14:33:02 <acozine> welcome, welcome!
14:34:10 <felixfontein> odyssey4me: there's an issue you might want to follow: https://github.com/ansible/ansible/issues/68755
14:34:17 <felixfontein> I added another item to the agenda, though in a new comment
14:34:17 <acozine> who else is around?
14:34:31 <acozine> thanks felixfontein
14:34:43 <felixfontein> for the notes/changelog part it would be good if gundalow abadger1999 are around
14:35:11 <acozine> it's awfully early for abadger1999, but gundalow might still be at his desk
14:35:20 <acozine> gundalow: you here?
14:35:29 <odyssey4me> awesome, thanks felixfontein
14:35:31 <abadger1999> Hi
14:35:46 * abadger1999 blearily rubs his eyes.
14:35:47 <felixfontein> good morning abadger1999! :)
14:35:52 <felixfontein> which timezone are you located in?
14:36:28 <abadger1999> US Pacific Time, I think UTC -8, but daylight savings always confuses me :-)
14:36:56 <felixfontein> ok, so -10 hours from here :)
14:37:02 <felixfontein> early indeed
14:38:30 <acozine> shall we start with the changelog question? or shall we start with felixfontein's PR and let you get a cup of coffee abadger1999?
14:38:44 <abadger1999> I am okay for whatever :-)
14:39:26 <acozine> let's start from the top then
14:39:45 <acozine> #topic release notes and changelogs for ACD
14:40:06 <samccann> #link https://github.com/ansible-collections/overview/issues/18#issuecomment-613036927
14:40:10 * relrod shows up
14:40:16 <samccann> So that's my summary so far
14:40:18 <acozine> thanks samccann for publicizing the question and bringing in so much feedback
14:40:21 <samccann> hi relrod !!
14:40:28 <acozine> #chair relrod
14:40:28 <zodbot> Current chairs: acozine felixfontein relrod samccann
14:40:34 <felixfontein> hi relrod!
14:40:46 * acozine keeps fatfingering that as "rhelrod"
14:40:47 <samccann> We still hope to get some more collection owners to give their feedback
14:40:52 <samccann> HAHAHAH
14:40:53 <felixfontein> RHELrod?
14:40:57 <acozine> exactly
14:40:59 <samccann> indeed
14:41:20 <acozine> apparently words that being with r must be RHEL-related
14:41:32 <acozine> s/being/begin
14:41:43 * acozine stops typing so she can reboot her fingers
14:42:01 <samccann> So on the changelogs... we are balancing the needs of collection owners, ACD, and collection users in our list of options
14:42:42 <samccann> so far the responses are heavy on the first two, but not so much on the users. I'm guessing the final comment is from a collection user (or potential collection user perspective anyway)
14:43:11 <samccann> Existing responses lean toward #2 - recommend the ansible/ansible approach, but allow the collection owner to do what they want on individual collection changelogs
14:43:31 <abadger1999> One clarification: "The collection owner can also use any tool they want (reno, towncrier, etc), but need to provide a per-collection changelog file that matches the current format of ansible/ansible changelogs."    The format they'd need to provide would be a new format, not the current format.
14:43:33 <samccann> if they use something like reno, we recommend they reformat to match ansible/ansible (or whatever our final format is)
14:43:39 <felixfontein> I don't mind a long list when it is grouped by collection, so I can skip the collections I don't use
14:44:13 <samccann> and if they don't do either (not ansible/ansible or not our new format) then at best they get a link to whatever they have
14:44:15 <felixfontein> ansible/ansible would be more option 3
14:44:19 <samccann> I'm not even sure the link is possible
14:44:41 <samccann> felixfontein - #2 had more votes than #3 for sure.
14:44:44 <felixfontein> they need to have something we can link to, of course
14:45:02 <felixfontein> samccann: yes, but #3 is more what ansible/ansible has now; #2 is ansible/ansible with new combined format
14:45:08 <samccann> That gets us down to 'what can we REQUIRE for ACD collections"
14:45:43 <samccann> felixfontein okay I can clarify my summary to say  ansible/ansible wit ha new combined format to make it cleaerier
14:46:04 <acozine> hmmm, having something we can link to may be a problem
14:46:15 <samccann> but for ACD - can we/should we REQUIRE the collection to provide either the matching format, or a fixed location we link to?
14:46:22 <samccann> agreed acozine
14:46:47 <acozine> can we assume that every collection will publish a changelog somewhere?
14:46:49 <felixfontein> I think that would be a reasonable requirement
14:47:02 <samccann> I'm thinking of certified collections, where they have their own entire docsite somewhere. They won't want to have to take an extra step to put a file in some fixed location.
14:47:13 <felixfontein> in the "worst" case they could have a .md/.txt/.rst file in their github repository and link to that
14:47:18 <relrod> Yeah I think it sounds fair to require that
14:47:54 <samccann> again, i worry about those certified folks with their own docsite. They may not even have a publicly available github repo
14:48:01 <acozine> that's true, I expect any collection that keeps its sourcecode in a private location will run a docsite somewhere
14:48:07 <samccann> I have lost the plot on all that tho
14:48:45 <samccann> yeah so they may not have a public place to put a changelog, but they would have say a release note on their own docsite that they'd want to include perhaps in ACD's changelog or something like that
14:49:25 <samccann> I see two approaches here:
14:50:16 <samccann> 1 - we have a manual 'fallback' where if we can't find a changelog in the expected location to link to, we allow manual edits to the ACD changelog file (maybe an included fragment) that the collection owner can manually edit to add their link to it
14:50:18 <samccann> or
14:50:36 <samccann> 2. we allow holes. You don't follow the recommended approach, you no get any thing in the ACD changelog
14:50:59 <abadger1999> Note that an external link will likely get somewhat skewed.
14:51:10 <samccann> can you explain further?
14:51:14 <felixfontein> I'm for 2., since I think the assumption that they can publish a changelog *somewhere* is really very easy to fulfill
14:51:56 <abadger1999> (ACD ships version 1.x but the latest upstream collection is 3.1.4.... the changelog link will likely have details of 3.1.4.... hopefully in addition to 1.x)
14:52:37 <felixfontein> the link in ACD could have some text: "previous vresion of ACD had 1.x, the new version is 3.1.4, here's the link"
14:52:39 <samccann> abadger1999 ah gotcha.  Yeah the link would need to be to the changelog or whatever that matches what is in ACD.
14:53:12 <abadger1999> If they need to have a link to the same version as ACD, that will avoid version skew but it means we'll need to update the links with every ACD release which might be difficult to coordinate.
14:54:16 <samccann> yeah I think that depends on the number of collections not following the recommended approach. I think ACD was up around 50+ collections right?  And the number that are under direct control of ansible team folks is quite smaller (we'll say 10-15?)
14:54:45 <felixfontein> true, but ansible team controls the largest ones :)
14:54:49 <samccann> But again, part of the collection move was to make it so that the core ansible team isn't responsible for everyone's everything right?
14:54:53 <samccann> heh
14:54:57 <abadger1999> Yeah, your numbers are correct
14:55:08 <abadger1999> Yep.
14:55:28 <samccann> So if we assume we aren't responsible for the quality of what is in ACD, that would extend to the quality of changelog info etc, right?
14:55:48 <abadger1999> Just listing the pros and cons for each approach so we're not surprised by the final outcome :-)
14:55:53 <abadger1999> Yeah.
14:55:58 <samccann> i'm leading myself down the path of we provide a way to do things well, and some kind of fallback (manual edits to add their links) if they don't do it well
14:56:03 <samccann> and live with the results
14:56:32 <samccann> and I need to catch up on meeting minutes notes here...
14:56:50 <felixfontein> and the worst fallback would be "sorry, we have no changelog for collection xxx"
14:57:19 <samccann> #info survey so far leads to #2 option, with a fallback to manual links added to the ACD changelog for  those collections who don't have the changelog in a fixed location we could link to programmatically
14:57:49 <samccann> #info Still hoping to gather some more feedback from collection owners
14:58:43 <samccann> #info #2 option includes a new combined format, so will be an update to what ansible/ansible provided in 2.9 (and possibly what ansible-base would have for 2.10+)
14:59:36 <samccann> #info any links added to ACD should be for the collection version in ACD, not the latest collection version, which could be more recent
14:59:42 <samccann> ok think I got most of it
15:01:02 <samccann> #info and the final fallback - no link at all if the collection owner doesn't follow the recommended approach, doesn't provide a link in a programmatically retrievable fixed location, and doesn't manually add their link to the ACD changelog (perhaps in  a separate manual link file).
15:01:10 <samccann> phew
15:01:43 <felixfontein> about providing ansible's internal tool: I'm not sure whether it makes sense to package it with ansible itself (like ansible-test). should it be its own package?
15:02:26 <samccann> hmm a collection developer needs ansible anyway... so perhaps the ansible-test approach is best?
15:03:41 <felixfontein> but a Ansible user really doesn't need it
15:03:47 <acozine> From a collection owner's perspective: I can provide changelog fragments in the ansible/ansible format, which get automatically amalgamated and published in the ACD changelog. If I don't want to do that, I can provide the output of my changelog process in a defined format, which gets automatically published in the ACD changelog. If I don't want to do that either, I can provide a link to my changelog, wherever I publish it (including
15:03:47 <acozine> GitHub). And if I don't do any of the above, ACD shows a "no entry available" for my collection in the changelog.
15:04:12 <felixfontein> acozine: sounds like a good summary!
15:04:13 <abadger1999> ansible/ansible has been cutting down on the number of committers to the repo... it might make the most sense that both ansible-test and the changelog tool belong outside of the ansible repo.
15:04:47 <abadger1999> (but the changelog generator will be easier to extract... it's just a few python files which do not depend on the ansible code)
15:04:49 <acozine> From a collection user's perspective: I see a changelog that includes some detailed entries, some links to external resources, and some "no entry available" lines.
15:04:57 <samccann> #info From a collection owner's perspective: I can provide changelog fragments in the ansible/ansible format, which get automatically amalgamated and published in the ACD changelog. If I don't want to do that, I can provide the output of my changelog process in a defined format, which gets automatically published in the ACD changelog.
15:04:57 <felixfontein> abadger1999: ansible-test is more closely coupled to the ansible-base version itself, so it makes also sense to keep it in ansible/ansible
15:05:00 <samccann> #info If I don't want to do that either, I can provide a link to my changelog, wherever I publish it (including GitHub). And if I don't do any of the above, ACD shows a "no entry available" for my collection in the changelog.
15:05:50 <felixfontein> this is Ansible's changelog generator: https://github.com/ansible/ansible/blob/devel/packaging/release/changelogs/changelog.py
15:06:08 <samccann> #Topic how to extract ansible changelog generator
15:06:22 <samccann> #info this is Ansible's changelog generator: https://github.com/ansible/ansible/blob/devel/packaging/release/changelogs/changelog.py
15:07:14 <acozine> I guess I would like to hear from more users. As a user, how helpful is it to have a mixture of links and detailed entries?
15:07:21 <samccann> #info this should most likely be pulled out of ansible-base into its own package
15:07:48 <samccann> acozine can we cover that next after the package discussion (aka the ACD changelog flow)
15:09:19 <samccann> anything else we should discuss about potentially pulling the ansible changelog stuff into its own package? Anything bad about having a separate package to mantain etc?
15:09:58 <acozine> samccann: sounds good
15:10:58 <samccann> hmmm seems like this was a conversation killer eh? :-)
15:11:07 <acozine> heh
15:11:26 <felixfontein> I guess putting it into a separate package would be ok
15:11:45 <felixfontein> no idea if the core team has something against that :)
15:12:26 <samccann> Well, rather than trying to solve it today, perhaps those of you 'in the know' (aka felixfontein abadger1999 relrod ) can think Deep Thoughts about it over the next few days and post here as/when you have ideas on this one
15:12:45 <acozine> thinking about it from the user's point of view, is creating a framework/pipeline to amalgamate the changelogs worth the investment, if we allow collection owners to opt out?
15:13:16 <samccann> #info - continue the to package or not to package discussion next week
15:13:28 <samccann> #Topic ACD Changelog usability
15:13:29 <abadger1999> <nod>
15:13:34 <felixfontein> well, there's always the problem that we have to provide a changelog for community.general and community.network anyway, so we have to do *something*
15:14:03 <acozine> heh, that's true
15:14:15 <samccann> So are we talking about how the ACD would flow?  Like say 20 of the collections have the full info, and the other 20+ have links, and the final 10 have nothing?
15:14:17 <felixfontein> I guess the additional step of adding the container format won't be that much more work. or at least I hope so :)
15:14:54 <acozine> felixfontein: at my previous job, we had a team rule . . . anybody who said a certain chunk of work "should be easy" was automatically assigned that ticket
15:15:13 <thedoubl3j> I was just about to say the same thing haha acozine
15:16:12 <acozine> maybe we should approach this in a more agile-development way
15:16:20 <acozine> #chair thedoubl3j
15:16:20 <zodbot> Current chairs: acozine felixfontein relrod samccann thedoubl3j
15:16:27 <abadger1999> @samccann In a similar vein to mixing links and full info would be whether to have each collection included as a separate section or interspersed together somehow.
15:16:30 <felixfontein> acozine: lol
15:16:36 <felixfontein> I don't mind working on that :)
15:16:45 <acozine> excellent!
15:16:53 <gundalow> Hi
15:17:01 <acozine> #chair gundalow
15:17:01 <zodbot> Current chairs: acozine felixfontein gundalow relrod samccann thedoubl3j
15:17:07 * gundalow waves
15:17:07 <felixfontein> right now I'm mostly waiting for reviews anyway, I've created too many PRs apparently...
15:17:12 * acozine waves at and welcomes newcomers
15:17:36 <samccann> yeah abadger1999 agreed . I think it depends on how many collections the 'average' user would care about
15:18:06 <samccann> i'm thinking an alphabetical list of collection sections in ACD, and then whatever detail we have is put under that section
15:18:15 <acozine> maybe we can solve the collection-level problem using the community.general collection as a guinea pig, and once that is finished and working, we can at least provide a list of links in ACD
15:18:18 <samccann> But it becomes abit of a hodgepodge to look at
15:18:40 <samccann> wouldn't communit.general be one collection with one link?
15:18:48 <felixfontein> samccann: maybe a section per collection which provides a changelog in a usable format, and one section with links for the remaining ones?
15:19:31 <acozine> samccann: yes
15:20:09 <acozine> but it's a small chunk of work we could start with, and then extend
15:20:22 <samccann> #info options for ACD output - a section per collection and whatever we have available in that section (changelog in usable format or a link or nothing). Alternately, we could leave all the links to an end section. That would work better for allowing manual link additions
15:20:25 <acozine> and see what the changelog actually looks like
15:21:05 <samccann> ah gotcha acozine.  My guess is some of the network collections will rev soon as well so will want/need changelogs
15:21:16 <abadger1999> <nod>  Maybe two collections would be good... then you can see what they look like if added sequentially and whether you'd want them interpsersed instead.
15:21:45 <acozine> abadger1999: sounds like a good approach
15:22:24 <gundalow> I like the idea of doing a mockup (starting with the end result)
15:22:34 <felixfontein> community.network and community.general both have a few changelog fragments already
15:22:36 <samccann> #info we could try out the output options on community.general and/or some of the network collections that may have changelog need before ACD releases.
15:22:37 <gundalow> and zero scripts
15:22:41 <felixfontein> (I added the existing ones from ansible/ansible for 2.10)
15:22:44 <acozine> felixfontein: I can't remember exactly what you volunteered (voluntold?) for, are you willing to take a look at that work?
15:22:55 <samccann> ooo I like that idea gundalow !
15:23:18 <samccann> #agreed try a manual mockup of what we want the end result ACD to look like and review that
15:23:26 <felixfontein> I'll play around with the changelog tool from ansible/ansible, to see whether I can get it to work with community.general and community.network
15:23:49 <samccann> #action felixfontein play around with the changelog tool from ansible/ansible, to see whether I can get it to work with community.general and community.network
15:23:54 <gundalow> To be clear, I mean copy-paste a few lines from changelog/fragements into an RST file (no Python required)
15:23:57 <acozine> felixfontein: awesome, thank you!
15:24:15 <acozine> gundalow: we can work on that in parallel with the collection-level work
15:24:17 <samccann> yeah understood that gundalow
15:24:29 <gundalow> :)
15:24:40 <samccann> though I have to toss in here - CAN it be rst?
15:24:50 <samccann> if it's rst, galaxy/AH can't display it in the UI
15:25:07 <samccann> if it's .md - dunno what we can do in sphinx land to display it.
15:25:08 <acozine> Galaxy has no way to display it in the UI anyway
15:25:15 <felixfontein> we could convert the result form .rst to .html, galaxy can hopefully handle that
15:25:19 <samccann> not today but AH definitly will
15:25:40 <samccann> the only thing we know AH can handle is md
15:25:41 <abadger1999> relrod mentioned pandoc being a tool to convert.
15:25:56 <samccann> if we decide anything different, we run the risk of AH not displaying it... ever
15:25:56 <relrod> felixfontein: If you need a hand looking at the changelog tool, feel free to ping me.
15:26:04 <acozine> I guess we can add Galaxy/AH as destinations for the docs build
15:26:05 <felixfontein> relrod: will do!
15:26:05 <abadger1999> rst is probably the better input format to a tool; I think it has more information built into the structure.
15:26:23 <abadger1999> (if we do need both)
15:26:23 <felixfontein> and markdown has too many dialects :D
15:26:32 <acozine> yeah, rst is more clearly defined
15:26:43 <acozine> than markdown
15:26:53 <relrod> and yeah, pandoc can convert between tons of formats. It might be a bit heavy but might be useful here.
15:27:32 <samccann> here's the thing though - galaxy/AH is not likely going to include pandoc to convert our .rst changelogs per collection into md
15:28:01 <acozine> that's true, but if we publish them on docs.ansible.com, do they need to be in Galaxy/AH also?
15:28:21 <samccann> so do we want Galaxy/AH to be able to display changelogs, or do we just say 'collection owner - you should include a link in your README to find the changelogs' and then it doesn't matter what format it is
15:28:39 <felixfontein> samccann: I guess we can convert the resulting .rst file to markdown
15:28:40 <samccann> I personally feel at the very least, a link has to be in Galaxy/AH
15:28:58 <felixfontein> (or at least try)
15:29:06 <felixfontein> no idea how terrible the result will be :)
15:29:28 <samccann> I would 'like' as a user that galaxy/ah eventually displays something higher level (like a release note or porting guide type information) so it is right there at the collection user's fingertips
15:30:03 <acozine> I think adding a link to the changelog in Galaxy/AH would be great, and displaying a more useful release note or porting guide there would be even better
15:30:14 <samccann> keeping in mind that collections change faster than ACD so users may want to get the latest collection from galaxy and would want and need some level of info on 'what's changed'
15:30:40 <acozine> but I don't want to block work on the current problem for something that Galaxy/AH can't currently display at all
15:30:42 <samccann> anyway not a decisin we have to make today
15:30:59 <samccann> that's something I disagree with, but we can take it up later :-)
15:31:21 <samccann> meanwhile I hogged the whole meeting and we didn't get to felixfontein's pr
15:31:44 <felixfontein> it has only been one hour yet ;)
15:31:44 <samccann> do you want to grab that now? or take it up maybe tomorrow at a convenient time here? not sure what your timezone is
15:31:47 <acozine> samccann: ah, interesting, let's have a discussion about that for sure!
15:32:03 <acozine> felixfontein: heh, you're going for a new DaWGs record?
15:32:06 <felixfontein> I'm around for a bit longer
15:32:16 <felixfontein> acozine: I hope not, that one meeting was long enough ;)
15:32:21 <abadger1999> <nod> I think what we'd do with pandoc is have it run and generate a .md in addition to the tool we write generate files in a format that we can consume.
15:32:43 <samccann> #info experiment with pandoc conversions
15:32:48 <samccann> #topic Felix's PR
15:32:50 <samccann> :-)
15:32:53 <samccann> #link https://github.com/ansible/ansible/pull/68899
15:33:39 <acozine> I haven't read it in detail yet, but overall it looks good
15:33:48 <samccann> ooo gundalow has a great question in that - how DO we want to refer to ansible/ansible now?
15:33:48 <acozine> I see a few words I might change
15:34:07 <acozine> ah, that is a good question
15:34:26 <acozine> I lean towards the phrase "the ansible/ansible repo", especially in developer docs
15:34:36 <samccann> it's a mouthful though
15:34:44 <acozine> true
15:34:49 <samccann> I'd love to be able to call it 'ansible-base' but I think we'd need marketing approval.
15:34:54 <gundalow> `ansible-base` repo?
15:35:02 <gundalow> hum, though it's not called gh/ansible/ansible-base
15:35:06 <acozine> exactly
15:35:07 <felixfontein> I'd probably make it "the `ansible/ansible repo <https://github.com/ansible/ansible/>`_"
15:35:07 <samccann> that suggests that's the name of the  repo, yeah
15:35:35 <samccann> gundalow - who could approve a decision like this - to call ansible/ansible  'ansible-base' in docs, presentations, etc
15:35:40 <abadger1999> Ƭ̵̬̊.
15:35:43 <acozine> so far we have not used "Ansible Base" anywhere that I'm aware of
15:35:47 <samccann> cuz we should all use the same term, and ansible/ansible is long
15:36:05 <gundalow> acozine: we can discuss that internally
15:36:29 <samccann> kewl
15:36:51 <samccann> So far seems nothing but some suggested edits coming for this PR
15:36:55 <acozine> felixfontein: I'll review your PR in detail today
15:37:22 <acozine> I'll probably suggest changing `Hacking Collections`, since "hacking" has some connotations we probably want to avoid
15:37:30 <felixfontein> acozine: cool, thanks!
15:37:37 <samccann> as a bit of feedback - we use Sentence case for all but the top-level headings.  So `Integration Tests` should be `Integration tests` for example. Just an fyi
15:37:38 <felixfontein> hehe :) just suggest something different ;)
15:37:59 <samccann> #action acozine to review the PR later today
15:38:15 <acozine> meanwhile thank you for documenting the testing process for collections!
15:38:21 <acozine> this is great information to include
15:38:57 <acozine> we may have to publish samccann's "module docs are under construction" banner so we can get this content published
15:39:16 <felixfontein> questions about that have popped up, and so far there was nothing to link to which doesn't require some knowledge about how stuff works or worked
15:39:35 <acozine> very true
15:39:48 <acozine> all right, we're 10 minutes over
15:40:10 <acozine> we'll do a very, very quick open floor
15:40:14 <acozine> #topic open floor
15:40:35 <acozine> does anyone have something they want to bring up?
15:40:41 <acozine> PR that needs a review?
15:40:48 <acozine> urgent issue we need to address?
15:41:06 <acozine> preview of a topic we can cover in more detail next week?
15:41:19 <acozine> question or request for help?
15:42:03 <acozine> As always, anyone can set an agenda item by adding a comment to https://github.com/ansible/community/issues/521
15:42:22 <acozine> all right, I think that's it for today
15:43:05 <felixfontein> thanks everyone!
15:43:11 <acozine> thanks samccann felixfontein abadger1999 gundalow relrod thedoubl3j and everyone who followed along at home!
15:43:17 <acozine> #endmeeting