14:31:57 <acozine> #startmeeting Docs Working Group aka DaWGs
14:31:57 <zodbot> Meeting started Tue Apr 21 14:31:57 2020 UTC.
14:31:57 <zodbot> This meeting is logged and archived in a public location.
14:31:57 <zodbot> The chair is acozine. Information about MeetBot at http://wiki.debian.org/MeetBot.
14:31:57 <zodbot> Useful Commands: #action #agreed #halp #info #idea #link #topic.
14:31:57 <zodbot> The meeting name has been set to 'docs_working_group_aka_dawgs'
14:32:10 <samccann> party time!!
14:32:35 <acozine> #chair samccann
14:32:35 <zodbot> Current chairs: acozine samccann
14:32:42 <acozine> who else is around?
14:33:46 * felixfontein is around!
14:34:19 * samccann waves
14:34:22 <cbudz> waves:
14:34:53 <acozine> #chair felixfontein cbudz
14:34:53 <zodbot> Current chairs: acozine cbudz felixfontein samccann
14:34:59 <acozine> welcome, welcome!
14:35:56 <acozine> today's agenda: √
14:35:59 <acozine> grrrr
14:36:01 <acozine> https://github.com/ansible/community/issues/521#issuecomment-613526358
14:36:52 <dmellado> o/
14:37:28 <acozine> #chair dmellado
14:37:28 <zodbot> Current chairs: acozine cbudz dmellado felixfontein samccann
14:37:33 <acozine> welcom dmellado
14:37:41 <dmellado> hi acozine ;)
14:38:49 * felixfontein wonders why github isn't showing a preview of the changelog mockup rst
14:39:43 <samccann> should we officially set the topic to changelogs :-)
14:39:45 <acozine> felixfontein: github generally does a crappy half-and-half job of displaying rST
14:39:48 <acozine> heh
14:39:54 <acozine> #topic changelog mockup
14:40:32 <acozine> oof, freenode is a bit slow today
14:40:45 <felixfontein> I wonder whether we want the collection's changelogs in the ACD changelog in a combined form per collection (i.e. merge changelogs of all versions that were added since last ACD release), or separately as in the mockup (community.general has multiple sub-changelogs: 0.1.4, 0.1.3)
14:41:07 <felixfontein> acozine: true, it does, but it's sometimes nicer to view than the sources
14:41:19 <samccann> #info ACD changelog mockup is at https://github.com/samccann/ansible/blob/test-changelog/docs/docsite/rst/changelog_acd.rst
14:41:40 <samccann> #info hacked together from a couple of existing collections, based on the ansible/ansible changelog.py script
14:42:53 <dmellado> I guess the whole internet's being slow nowadays
14:43:10 <dmellado> I've got 600/600 Mbps fiber and it feels like being back in 56k days...
14:43:22 <felixfontein> here in europe it doesn't feel slow
14:43:24 <samccann> output looks kind of like this https://usercontent.irccloud-cdn.com/file/QP5yahx5/image.png
14:44:09 <samccann> again not perfect because I hacked code I didn't really understand to get the output, so the headings are a bit off. Imagine under community.crypto it would just say v1.0, v1.1, etc
14:44:50 <samccann> (or alternately, what felixfontein asked - maybe it says Major changes, Minor changes, etc and all the fragments are piled in there to cover all the release changes that collection had between ACD releases)
14:45:37 <samccann> My worry about putting everything under Major, Minor, etc - will the fragments still make sense?
14:45:52 <samccann> Say for example a minor change in v1.0 is tweeked in v1.1
14:46:24 <samccann> piled together, they may cause confusion.  Separated as v1.0, v1.1 etc - at least the reader can tell, oh this thingie changed again in v1.1
14:46:30 <felixfontein> true
14:47:00 <felixfontein> definitely both approaches have advantages
14:47:05 <samccann> gundalow: you around? Did you get a chance to look at the mockup? ^^
14:47:12 <cbudz> do they need to be called 'minor changes'
14:47:49 <acozine> it's hard to know what the most typical use case will be - will lots of users upgrade individual collections between ACD releases? or will most people upgrade (if at all) in lockstep with ACD?
14:47:54 <felixfontein> that's mainly tradition, where major_changes was reserved for major core changes
14:47:55 <samccann> That wuold be the next set of decisions - what we want those categories to be. Right now, that's what we use in ansible/ansible
14:48:27 <samccann> acozine:  My recommendation is we start easy, but have the 'foundation' to change based on what we recommend collection owners do
14:49:03 <samccann> so for ACD 1.0 - I think we could even go with a linkfest to the collections most recent changelogs.  Then we incrementally improve in ACD v1.1 etc as we get feedback from the community
14:49:29 <felixfontein> I guess we can try to do better, and fall back to that if we don't succeed :)
14:49:51 <samccann> so what's important imo right now - what do we need collection owners doing so that if/when we want a real changelog for ACD, we have the correct pieces (whatever they are) living in the collections somewhere
14:50:05 <samccann> excatly felixfontein...
14:50:11 <samccann> exactly even :-)
14:50:39 <samccann> oh good to know about t he major core changes !
14:51:04 <felixfontein> I'd definitely want to use major_changes differently now for collections, like highlight major changes as opposed to the long list of minor changes
14:51:04 <samccann> cbudz: those category titles are set in a..erm.. yaml file I think. So we could change them down the road if we want
14:51:16 <felixfontein> https://github.com/felixfontein/community.general/blob/changelog-1.0/changelogs/config.yaml
14:51:33 <felixfontein> that's how a config file for community.general could look like
14:51:39 <samccann> #info the output headings are set in https://github.com/felixfontein/community.general/blob/changelog-1.0/changelogs/config.yaml so we can modify them as needed
14:51:45 <felixfontein> and that's how the compiled YAML changelog could look like: https://github.com/felixfontein/community.general/blob/changelog-1.0/changelogs/changelog.yaml
14:52:08 <samccann> #info the ansible/ansible Major Changes was reserved for core changes. We can reuse that category in collections for 'something else"
14:52:39 <felixfontein> the default comes from here: https://github.com/felixfontein/ansible-changelog/blob/master/ansible_changelog/config.py#L144-L150
14:52:44 <samccann> now what was the reason for the combiled yaml? was it that the ACD changelog script could pull that in instead of the rst?
14:53:14 <felixfontein> there is no ACD changelog script yet, but a ACD changelog script could use that to generate the combined changelog as in your mockup
14:53:33 <samccann> ah ok thanks
14:53:49 <felixfontein> same result in the end :)
14:53:59 <samccann> gonna switch topics for a moment to Felix's work
14:54:10 <acozine> we might even (someday) want to publish two versions of the ACD changelog - one with only Major Changes, one with everything
14:54:11 <felixfontein> and it should be not so hard to convert other changelog generator's input or output to this format
14:54:40 <felixfontein> acozine: indeed! I'm currently thinking that major_changes would be similar to what porting guide is nowadays, at least for collections
14:54:46 <samccann> ah ok so the 'format' we've been bantering on is that yaml file format?
14:55:23 <felixfontein> samccann: it's just an idea how it could look like (inspired from what ansible's changelog generator uses, expanded with actual content instead of only links to fragments and plugins/modules)
14:55:24 <samccann> that use of major changes would work well with reno folks I think, as reno has an 'upgrade' category that could also feed into porting guides
14:55:56 <samccann> #topic changelog generator -wip
14:56:11 <felixfontein> `Removed Features (previously deprecated)` and `Deprecated Features` also belong into the porting guide category
14:56:23 <felixfontein> bugfixes and minor changes do not
14:56:29 <samccann> #info felixfontein has a WIP of what the changelog-generator tool might look like at https://github.com/felixfontein/ansible-changelog/
14:57:02 <samccann> #info generated output for `community.general` is at https://github.com/felixfontein/community.general/blob/changelog-1.0/changelogs/CHANGELOG-v1.rst
14:57:17 <felixfontein> currently that WIP creates the same changelog as ansible's tool for 2.9 does, and it can do changelogs for collections such as community.general
14:57:23 <samccann> #info and in yaml format at - https://github.com/felixfontein/community.general/blob/changelog-1.0/changelogs/changelog.yaml
14:57:37 <acozine> this looks great felixfontein
14:57:58 <samccann> #info this WIP creates the same changelog as ansible's tool for 2.9 does and can do changelogs for collections
14:57:58 <felixfontein> I plan to do more work on it this week, so it also allows to reference previous yaml files, and allows to create a combined changelog for multiple collections
14:58:39 <samccann> okay so if we had this as the recommended solution, what would say a reno user have to do so that their changelogs could feed up into an ACD level changelog?
14:58:59 <cbudz> can that file include a TOC to jump to relevant sections?
14:59:08 <samccann> the rst does, yeash
14:59:15 <cbudz> cool
14:59:16 <felixfontein> they need to come up with something which creates the YAML file out of their reno input (or output). I don't know too little about reno
14:59:55 <acozine> so for collections that are keeping their changelogs in markdown, they'd need to transform their changelog files into YAML?
14:59:59 <felixfontein> meh. sorry for that last sentence, I hope you know what I mean :)
15:00:14 <samccann> dmellado ^^ can you take stab at how reno might produce a yaml file like the one above?
15:00:17 <felixfontein> acozine: they need to convert it to a YAML with .rst in it
15:00:31 <acozine> okay
15:00:56 <felixfontein> but then there are .md -> .rst tools, and hopefully you can somehow work with an intermediate format (or source format) for the changelog generator to avoid having to parse the combined .md output
15:01:40 <samccann> #info collection owners who choose not to use the recommended changelog-generator tool would have to convert their output to the yaml file example included above. That is likely what some future ACD changelog tool would look to pull into an ACD changelog
15:02:15 <samccann> So is our best guess today, that a future ACD changelog tool would want to work on YAML files like this one?
15:02:35 <acozine> I think having an example would help me understand it better, maybe for next week we can find (or mock up) a collection with .md or .rst fragments and try converting those
15:02:38 * samccann realizes she's asking for fuzzy future predictions here
15:02:49 <felixfontein> I think so
15:02:56 <samccann> not sure what you're asking for acozine?
15:03:09 <samccann> do we have collections using .md/rst?
15:03:13 <felixfontein> acozine: community.general, community.network and community.crypto have .rst fragments
15:03:20 * samccann tries to remember if reno uses rst fragments...
15:03:38 <felixfontein> (all the ones from ansible/ansible before pre-ansible-base cleanup, and new ones for changes since then)
15:03:39 <samccann> heh that answers that question on the rst side anyway
15:03:44 <acozine> aren't these YAML? they have yaml extensions . . . https://github.com/felixfontein/community.general/tree/changelog-1.0/changelogs/fragments
15:03:57 <felixfontein> acozine: they are, but YAML is just a container format, the content is .rst
15:04:12 <acozine> ahh, okay
15:04:12 <felixfontein> it is essentially a dictionary, mapping sections to lists of .rst fragments
15:04:39 <felixfontein> (and every .rst fragment is put into an item in a list in the final .rst changelog)
15:04:40 <acozine> so "straight YAML" and markdown would need to convert to .rst content within a YMAL container
15:04:45 <samccann> ok checked and reno creates changelog fragments the same way - yaml format that allows for embedded rst
15:05:10 <acozine> the other one folks have been requesting/championing is towncrier
15:05:13 <felixfontein> samccann: that should make conversion a lot easier, since  there's no .md -> .rst step involved
15:05:41 <felixfontein> towncrier uses .rst files (https://github.com/ansible-collections/overview/issues/18#issuecomment-603466735)
15:06:13 <felixfontein> if they don't use fancy .rst features in there, it's also easy to wrap into a .yaml container
15:06:30 <felixfontein> (the fancy .rst features is more a problem for the resulting ACD changelog)
15:06:42 <acozine> so this may end up being easier than I feared
15:06:47 <acozine> that's good
15:07:10 <felixfontein> I hope so :)
15:07:28 <samccann> Well we still need someone familiar with at least one of them (reno maybe) to evaluate what it  would take to generate/convert their changelog.rst into changelog.yml
15:07:55 <felixfontein> true
15:08:24 <acozine> or we could do a quick-and-dirty test run ourselves
15:08:34 <samccann> #action need to guestimate what it would take to convert a reno or towncrier changelog.rst into changelog.yaml similar to felixfontein's WIP so that a future ACD changelog-generator could bring it in cleanly.
15:08:56 <samccann> acozine - we do have some folks 'inhouse' so to speak familiar with reno and could perhaps make a quick guess
15:09:41 <acozine> could we create a changelog-examples repo that shows sending changelog files from each popular solution to the ACD format?
15:09:54 <acozine> samccann: ah, that's certainly less work
15:10:03 <samccann> I don't know that we want to own all that... even in examples
15:10:18 <acozine> heh
15:10:25 <acozine> not our circus, not our monkeys?
15:10:28 <samccann> my nickel - we want to crreate a recommendation that works for us, but that isn't super painful for those who don't want to follow the recommendation
15:10:41 <acozine> that makes sense
15:10:46 <samccann> with a final fallback of we will give them a file where they can add their links if nothing else works
15:11:00 <felixfontein> so where are all the reno and towncrier fans? :)
15:11:32 <samccann> lol the one we had here today is having flaky network issues... but I know 'where he lives' in the online sense so I'll followup with him later
15:11:48 <acozine> good question felixfontein
15:11:58 <samccann> #action samccann to follow up with dmellado on how to get reno output into this changelog.yaml format
15:12:00 <felixfontein> samccann: great :)
15:12:16 <samccann> and that issue we are all posting into tends to grab attention as well
15:13:27 <samccann> should we add a comment to say 'towncrier/reno/ etc users - please evaluate the WIP changelo.yaml format and if you could get your changelog output to match'  or something like that?
15:14:28 <felixfontein> sounds good
15:14:29 <acozine> that sounds like a good idea
15:14:51 <acozine> and we can start a pool on how many comments that issue will get before we finally close it
15:16:41 <acozine> anything else to discuss about changelogs today?
15:17:18 <samccann> haha
15:17:21 <samccann> added the comment
15:17:39 <felixfontein> :)
15:17:49 <acozine> thanks samccann
15:17:50 <samccann> we have the 'what to do about porting guides' discussion that may relate to this. dunno if you want to open that can o worms today?
15:18:37 <acozine> we can start with a porting guide that skims the Major Changes from each collection's changelog, and see how well that works
15:18:40 <felixfontein> I guess the main question is how a porting guide should look like for ACD, especially the part about collections
15:18:51 <felixfontein> major changes + removals + deprecations
15:18:58 <samccann> #topic porting guides for ACD and collections
15:19:17 <samccann> #info we could potentially use 'major_changes' for porting guide entries in collections
15:19:38 <samccann> #info and include removals and deprecations
15:20:01 <acozine> the hardest-hitting changes moving forward will be in ansible-base
15:20:10 <felixfontein> yep
15:20:11 <samccann> hmm
15:20:16 <acozine> and for those, we will still create a verbose porting guide
15:20:25 <acozine> paragraphs, rather than sentences
15:20:35 <samccann> ah gotcha
15:20:57 <acozine> "here's what changed and here's why it affects you and here's how you work with this change"
15:20:57 <samccann> so would we try to combine an ansible-base porting guide inside the ACD porting guide?
15:21:00 <felixfontein> for collections, it's usually 'module x was renamed to y', 'usage of module x changed, tasks/playbooks need to be adjusted', things like that
15:21:24 <felixfontein> and 'module x was removed, use module y instead'
15:21:40 <samccann> so we envision collection-level porting guide details to be small. That's something we should field with collection owners just to be sure
15:22:30 <acozine> samccann: you mean, you think collections owners might write longer entries (if we don't give them guidance)?
15:23:20 <acozine> or more "let's not make assumptions"?
15:23:40 <felixfontein> I guess we need to document somewhere that major_changes should really only be used for changes which MUST be observed by users, and that they should not be long texts
15:23:48 <samccann> more like lets not make assumptions
15:24:05 <felixfontein> and that 'added new authentication method' is not a major change, if it doesn't break existing behavior
15:24:16 <acozine> I am prone to making assumptions
15:24:20 <samccann> Like the network team introduced resource modules.  that was a paragraph or so on the porting guide
15:24:42 <felixfontein> it's also a gray area...
15:24:48 <felixfontein> lots of discussion possible :)
15:24:58 <samccann> But that does't mean the major_changes section can't handle that. We just need to give guidance.  "if your fragment needs to be large... do xxx so it is formated properly'
15:25:25 <samccann> back in an older job... we had a category called 'behavior change'
15:25:40 <samccann> which was exactly that - users had to do something different.
15:25:58 <samccann> and it was its own category in a release note.  Can't remember now what they called that category
15:26:26 <acozine> ah, interesting
15:27:17 <felixfontein> it would probably be nice to also have such a category... though there are already quite a lot of them
15:28:13 <samccann> well if we have 'major_change' as 'porting guide' on the output... or upgrade or something by default, that could cover it (with explanations in docs)
15:28:28 <samccann> then ansible-base could just change that back to 'major changes' for their changelog output
15:28:44 <acozine> agreed, it would be nice to have a category for "people really need to pay attention to this, because it means they have to do something different"
15:29:23 <acozine> but with a half-dozen categories already, perhaps "major changes" should be that category?
15:29:33 <felixfontein> major changes has too much other meaning IMO
15:29:48 <acozine> ah, okay
15:29:49 <felixfontein> having both major_changes and behavior_changes is probably better
15:30:09 <samccann> so adding a new category to the changelog_generator?
15:30:18 <felixfontein> so that it's clear what's just a major new feature, and what's absolutely important to know
15:30:32 <felixfontein> samccann: there's no real need, it just needs to be added to the (default) config :)
15:31:24 <samccann> #info consider adding 'behavior_changes' to the default config to cover the important changes where a user must do something different when using this new version of a collection/ACD
15:31:56 <acozine> ah, so "module X has this new feature" is a "major change" and "module X now requires parameter Y" is a "behavior change"?
15:32:00 <samccann> #info then 'major_changes` can remain to describe major new features in a collection or ansible-base
15:32:12 <samccann> eggzactly
15:32:19 <acozine> cool, that makes sense
15:32:27 <samccann> #info module X has this new feature" is a "major change" and "module X now requires parameter Y" is a "behavior change
15:32:59 <acozine> yikes
15:33:04 <acozine> we've run over
15:33:15 <felixfontein> acozine: normally 'module X has this new feature' is a minor change, not a major change
15:33:15 <acozine> changelogs are quite engrossing!
15:33:34 <samccann> well replace module with collection above and it could be a new feature
15:33:35 <felixfontein> a major change would be something major for the collection, maybe 'all modules now use the v4 API instead of the deprecated v1 API'
15:33:35 <acozine> felixfontein: ah, so what would count as a major change?
15:33:57 <felixfontein> I guess every collection has to discuss that for themselves
15:34:18 <felixfontein> I guess there should be a most a handful of major changes per changelog
15:34:21 * bcoca preps collectiondrome
15:34:28 <acozine> yeah, we will probably learn a lot from the first and second ACD releases
15:34:32 <felixfontein> yep
15:34:54 <felixfontein> some probably will have way too much in that section
15:35:04 <felixfontein> we have > 50 collections in ACD, so chances that one has is high enough :)
15:35:09 <felixfontein> (IIRC)
15:36:15 <acozine> yep, probably some will head in each direction - "all our changes are major" vs. "what, that little change? not worth discussing"
15:36:26 <felixfontein> yep
15:36:47 <acozine> whatever the majority do, we will likely have to adjust
15:37:59 <samccann> I personally still worry about the size of the resulting ACD changelog.rst file, even if we just leave it in github... but we'll see when the time comes...
15:38:16 <acozine> agreed, it will be a large file
15:38:19 <felixfontein> samccann: true
15:38:49 <felixfontein> but then, the existing changelog also has been long
15:39:00 <felixfontein> and all the work now happening in collections before happened in ansible/ansible
15:39:45 <acozine> yep
15:40:46 <acozine> all right, time for the open floor, for the sake of propriety
15:40:50 <acozine> #topic open floor
15:41:13 <acozine> now is your moment, if you have been watching this conversation, waiting for your chance to ask a question
15:41:15 <acozine> make a comment
15:41:23 <acozine> request a review on a PR
15:42:04 <acozine> as always, agenda items are welcome, just add a comment to https://github.com/ansible/community/issues/521
15:42:23 <acozine> #info agenda items are always welcome, just add a comment to https://github.com/ansible/community/issues/521
15:43:01 <acozine> questions, comments, ideas, suggestions, requests welcome on this channel at any time
15:43:36 <acozine> hearing none for now . . .
15:43:46 <acozine> thanks samccann cbudz felixfontein dmellado
15:43:59 <acozine> #endmeeting