14:31:28 <acozine> #startmeeting Ansible Docs Working Group aka DaWGs
14:31:28 <zodbot> Meeting started Tue Mar 24 14:31:28 2020 UTC.
14:31:28 <zodbot> This meeting is logged and archived in a public location.
14:31:28 <zodbot> The chair is acozine. Information about MeetBot at http://wiki.debian.org/MeetBot.
14:31:28 <zodbot> Useful Commands: #action #agreed #halp #info #idea #link #topic.
14:31:28 <zodbot> The meeting name has been set to 'ansible_docs_working_group_aka_dawgs'
14:31:59 <acozine> #topic general check-in
14:32:19 <acozine> how are folks coping with Life in the Time of Coronavirus?
14:32:34 * samccann waves
14:32:41 <acozine> #chair samccann
14:32:41 <zodbot> Current chairs: acozine samccann
14:33:51 <samccann> I've got milk and bread to last at least 10 days.. doing good :-)
14:33:57 <samccann> (oh and chocolate...)
14:34:15 <acozine> we have a lot of random groceries in the house
14:34:52 <acozine> plenty of canned tunafish but not much to mix with it for tuna salad
14:35:01 <samccann> heh woopsie
14:35:07 <acozine> a big jar full of rice
14:35:52 <acozine> I made a big batch of soup, so we have a couple of quarts of that in the freezer
14:35:55 * felixfontein waves
14:36:00 <felixfontein> (only partially here though)
14:36:02 <samccann> yum yum!
14:36:02 <acozine> hey, felixfontein!
14:36:15 <acozine> felixfontein: partial or not, you're getting to be furniture
14:36:19 <acozine> #chair felixfontein
14:36:19 <zodbot> Current chairs: acozine felixfontein samccann
14:36:50 * gundalow waves
14:36:58 <acozine> hey, gundalow!
14:37:01 <acozine> #chair gundalow
14:37:01 <zodbot> Current chairs: acozine felixfontein gundalow samccann
14:37:10 <gundalow> #info Reminder, Sunday is Virtual Contributors Summit, starting at 1100UTC. I hope to see a lot of you there https://etherpad.openstack.org/p/ansible-contributor-summit-gothenburg-2020
14:37:26 <gundalow> #info We will also do Hackathon on Monday & Tuesday
14:39:14 <acozine> what's the time UTC now?
14:39:26 * acozine puts the contributors summit on her home calendar
14:39:58 <samccann> do we have hackathon plans for docs?
14:40:51 <gundalow> In the docs meeting yesterday we talk about the 4 topics of docs. That could be something we could hack on
14:40:56 <acozine> I put something on the agenda . . . but that was a few weeks back, which now feels like years ago
14:41:12 <gundalow> as well as if there are PRs to review or things to help test/give feedback on
14:43:14 <tremble> Will devel be unfrozen by Monday?
14:43:58 <acozine> hi tremble!
14:44:03 <acozine> #chair tremble
14:44:03 <zodbot> Current chairs: acozine felixfontein gundalow samccann tremble
14:44:16 <tremble> o/
14:44:26 <acozine> I believe it is unfrozen now
14:44:53 <acozine> at least, the old, batteries-included branch has been replaced with the new, most-plugins-in-collections branch
14:45:05 <acozine> as of yesterday
14:45:26 <acozine> PRs that were opened before the Plugin Exodus will need to be rebased
14:45:49 <acozine> PRs affecting migrated modules or other content will need to be moved
14:46:40 <samccann> #info devel is unfrozen now.  Open PRs need to be rebased. PRs affecting migrated modules or other content will need to be moved.
14:47:18 <acozine> tremble: was there a specific PR you wanted to follow up on?
14:47:24 <tremble> Nope
14:48:03 <acozine> okay
14:48:12 * acozine looks at the agenda for today
14:49:22 <acozine> all right, first topic is release notes/changelogs/porting guides in the Collections Ecosystem
14:49:32 <acozine> #topic release notes for Collections
14:50:02 <acozine> from last wee:
14:50:06 <acozine> er, week
14:50:11 <samccann> weeeee!!!
14:50:14 <acozine> heh
14:50:21 * samccann full of useful commentary today
14:50:24 <acozine> `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`
14:50:48 <samccann> I need to dig up the issue where we are tracking this...
14:51:37 <samccann> #info tracking issue for changelog process - https://github.com/ansible-collections/overview/issues/18
14:51:56 <samccann> I haven't gotten to dig into reno etc yet, but I'll put notes there as I do.
14:52:28 <acozine> I have not used either reno or towncrier
14:53:12 * acozine looks for basic info
14:53:20 <gundalow> Can ask in #openstack-ansible about Reno they uses it a lot
14:53:43 <samccann> #info reach out to #openstack-ansible about reno as they use it already
14:53:56 <samccann> acozine: the links are in that issue above ^^
14:54:28 <acozine> samccann: ah, excellent
14:56:39 <samccann> I think the tricky part comes from a) coordinating the same format for all collections in ACD and b) keeping them around in the repos in such a way that we can programatically extract across multiple collection versions.
14:56:57 <acozine> agreed
14:57:06 <samccann> oh... and c) hoping the end result is usable :-)
14:57:08 <acozine> heh
14:57:41 <samccann> ...and d) either repeating this approach for porting_guide fragments, or finding some clever way to pull porting guide tidbits out of changelog fragments
14:58:02 <gundalow> so for `a+b` we could enforce that by CI
14:58:34 <samccann> good to know
14:59:10 <acozine> if we have to, we can fall back on manual editing for the porting guide, as part of the release process
14:59:15 <samccann> I struggle with envisioning how we achieve b.
14:59:17 <acozine> gundalow: what does CI look like on the collections side?
14:59:36 <samccann> As in, do we tag older versions in github (and does this mandate everyone has to be in github to be in ACD)
14:59:50 <acozine> gundalow: for repos in `ansible-collections`, at least?
14:59:55 <samccann> i'm sure there's magic there somewhere, I'm just not up to seeing it yet
15:00:52 <acozine> samccann: if we enforce changelog fragments go in a directory called `docs/changelogs`, then those will get rolled into the collections on Galaxy, and we can pull them from there
15:01:07 <acozine> so the repos don't have to be on GitHub
15:01:52 <felixfontein> changelog fragments should better be collapsed for every release, before you end up having 10000 of files just for changelog fragments after some years
15:02:09 <felixfontein> (i.e. combined into very few files)
15:03:03 <samccann> well I'm thinking for example that collection A is version 1.0.0 in ACD 2.10,  and then has say 3 releases before ACD 2.11... so we need to capture the changelog fragments for Collection A version 1.1.x, 1.2.x and 1.3.0 for example.
15:03:14 <acozine> felixfontein: you're right, I'm just not sure how/where we do that . . .
15:04:15 <samccann> what I'm thinking  - Collection A 1.0.0 has a changelog.md file, and 1.1.x has a changelog.md file, and 1.2.x etc etc  - each collection version on Galaxy should have a readable changelog for just that version
15:04:20 <felixfontein> if you have a .yaml file with all changelog entries for every version, and these are named in a useful way, it is rather simple to combine them. the main question is what happens with duplicates. like a bugfix might end up in 1.1.5, 1.2.3 and 1.3.0
15:04:31 <samccann> but then ACD comes in and needs one across all three in this example
15:04:46 <felixfontein> changelog.md sounds like "lots of manual work"
15:05:41 <samccann> felixfontein - I'm thinking something within the collection collects the fragments for 1.1.x and creates changelog.md ... much like it happens today in ansible/ansible
15:06:08 <acozine> so . . . in the repo `ansible-collections/foo.git` we'd have a file called `docs/changelogs.yml` containing entries for each collection release?
15:06:10 <samccann> the goal in my mind is that each collection version has at least a changelog to go with it, and eventually visible in galaxy
15:07:17 <felixfontein> acozine: I would have one .yml file per version. otherwise you have a single file which grows to enourmous sizes for large collections
15:08:22 <acozine> felixfontein: yeah, I'd even say one `.yml` file per minor version of each collection, since I believe each upload to Galaxy triggers a new version
15:09:09 <acozine> so . . . if a developer fixes one bug that exists in 1.2.5, as soon as that bugfix is uploaded the collection version becomes 1.2.6
15:10:35 <acozine> a `docs/changelogs/changelogs_1_2.yml` could contain the bugfix added in 1.2.6 and also the feature added in 1.2.7
15:10:45 <samccann> but say that bug is also in the 1.3 version of the collection
15:10:49 <felixfontein> can you have multiple parallel versions in galaxy, similar as ansible/ansible has today (2.8.x and 2.9.x exist in parallel)?
15:11:10 <samccann> yeah ^^ that was my question as well :-)
15:11:35 <acozine> I don't think so
15:11:41 <acozine> but I'm not entirely sure
15:11:46 <acozine> gundalow: do you know ^^^
15:14:51 <acozine> Galaxy supports downloading multiple versions, but I think every upload ticks the version number up from the previous latest version
15:14:53 <acozine> https://galaxy.ansible.com/newswangerd/collection_demo
15:15:43 <samccann> it would tick up to say 1.2.6 and 1.3.x  - but if ACD goes from 1.1 to 1.3, then we'd get that duplicate changelog problem as it would exist in both
15:15:47 <felixfontein> can't you define your own version number?
15:16:15 <samccann> (was just making up versions btw)
15:16:38 <samccann> I think they have to follow semver  though
15:17:00 <felixfontein> semver doesn't prohibit that you release 1.2.8 after 1.3.2
15:17:01 <samccann> which would mandate whether the patch rolls major, minor, or bugfix numbers
15:17:08 <felixfontein> yes
15:17:08 <acozine> looking at the demo collection, you must have some control, because that collection jumps from 1.0.6 to 1.0.10
15:17:17 <samccann> ah gotcha
15:18:51 <acozine> but I don't know if you can choose a lower number
15:19:35 <acozine> I've asked the galaxy team, will relay the answer when it comes (probably after the end of this meeting)
15:21:37 <bcoca> you should be able to list mulitple versions on galaxy, i believe they were talkinga bout adding a limit but don't think they did yet
15:21:50 <bcoca> galaxy has a wishlist right now but no current development
15:24:10 <acozine> bcoca: you can definitely list multiple versions on Galaxy
15:25:00 <bcoca> one feature we recently asked for is 'versions pertaining the version of ansible making teh query'
15:25:07 <acozine> but it isn't clear whether you can release out of order - for example, on Monday release 1.5, on Tuesday release 2.0, then on Wednesday release 1.6
15:25:19 <bcoca> e.g 'ansible-galaxy search' from 2.11 would get collections compatible with >=2.11
15:25:50 <bcoca> acozine: you should be able to, have not tested in a couple of months, but it was possible
15:26:04 <bcoca> you cannot release the same number, but you can increment minor versions
15:26:41 <acozine> cool, thanks bcoca
15:28:34 <acozine> based on that, we could have `docs/changelogs/1_x_changes.yml` and `docs/changelogs/2_x_changes.yml` . . . and we would run into the problem mentioned above, which is the same bugfix would appear in both files
15:28:54 <bcoca> possibly, but you might need that
15:29:01 <bcoca> for example, cve that affects multiple versions
15:29:04 <acozine> but at the ACD level, presumably we would only include on version or the other
15:29:11 <acozine> bcoca: yes, we'd need it
15:29:21 <bcoca> yep, you should not include more than one version of same collection in ACD
15:29:58 <bcoca> but wont you want accumulated changes?
15:30:27 <bcoca> or you want only changes from previous acd to new acd?
15:30:32 <bcoca> that might be very tricky
15:31:02 <acozine> ideally we'd want changes between ACD 1.0 and ACD 1.1, right?
15:31:04 <bcoca> prev acd = 1.03 new acd = 2.15  and you have 1.54 as latest of 'v1'
15:31:22 <bcoca> ^ all collection version
15:31:36 <samccann> yep that's the thing I've been trying to think thru bcoca
15:31:41 <bcoca> so acd 1 has 1.03 of coll, and acd 1.1 has 2.15
15:31:49 <bcoca> .... 'fun'
15:31:55 * samccann nods
15:32:14 <samccann> that's the problem I couldn't find anyone else solving (aka RHEL, Fedora)
15:32:16 <acozine> ah, yeah, it depends on when in the sequence the developers started the 2.x series
15:32:58 <samccann> where packages rev frequently but the release just grabs one of the latest. All they do is mention the version of the package they include. Users are on their own to find any changelogs, release notes etc for that version or any prior versions
15:33:25 <bcoca> yeah, i dont thnk any distro tries to be 'as helpful' as you are being
15:33:37 <bcoca> they mostly have 'changelog packge X is now 3.21'
15:33:53 <samccann> yep. that's what I saw
15:33:57 <bcoca> and you are on your own to figure out the specific changes between that and prev
15:34:08 * samccann nods emphatically even
15:34:24 <samccann> so do we follow suit, or try to solve the problem others haven't solved?
15:34:37 <bcoca> considering teh difficulty of the problem ... i understand it, still feels like copout
15:34:45 <felixfontein> I'm more and more tending to "follow suit"
15:35:00 <felixfontein> bcoca: exactly
15:35:37 <acozine> it's frustrating, because it's a problem we had solved in the old ecosystem, but the solution doesn't port to the new ecosystem
15:35:38 <bcoca> gentoo 'kindof' manages this via changelong but that is only for updates between releases
15:35:59 <samccann> got a pointer for that?
15:36:04 <bcoca> for security updates, most distros do this, but not for major release
15:36:16 <bcoca> samccann: not sure it can apply, gentoo is 'roling release'
15:36:48 <bcoca> so its always just update specific packages, changelog per package is easier (since they aslo download/compile sources, normally changelog available)
15:38:00 <acozine> samccann: https://www.gentoo.org/
15:38:08 <acozine> oops, we're over time
15:38:28 <samccann> Fedora and RHEL have separate release notes that are built up via a script on bugzilla. Those bugs would be 'update package foo to version 1.2.3' for example
15:38:56 <samccann> IF we had somthing similar (tracking package changes in ACD) we could mandate a more thorough changelog fragment to go with it?
15:39:23 <samccann> but that would mean someone would have to dig into the collection and figure out what's important to surface up to ACD (aka not automagic)
15:39:25 * samccann done
15:39:43 <gundalow> acozine: CI wise, for community.general we basically have the same in ansible/ansible. for others we have GitHub Actions.
15:40:09 <felixfontein> if the entry of changelog-1.x.yml for every version contains a link on which changelog this continues (like 1.5 links to 1.4.3, 1.4.3 to 1.4.2, etc., and 2.0 links to 1.0) it would be possible to prevent duplicate entries
15:40:27 <acozine> gundalow: thanks
15:41:07 <gundalow> acozine: was there more detail you'd like?
15:41:40 <acozine> felixfontein: if I fix BadBug in version 2.1.1 and port it back to 1.5.2, where would I put the changelog entry?
15:42:02 <acozine> gundalow: if you have a link to a Shippable run, that would be great
15:42:19 <felixfontein> acozine: in both places. but if the 2.0 changelog points back to 1.0, and not 1.5.2, then crawling back up does not find the entry twice (or more often)
15:42:59 <acozine> felixfontein: I'm having trouble imagining what that looks like, but it sounds plausible
15:43:49 <felixfontein> it of course requires that people keep their changelog.yml files in order and with the correct metadata
15:44:23 <felixfontein> which we might be able to do for some collections, but which others might not do at all
15:44:25 <acozine> I'd add `BadBug: this won't crash your system any more` to `docs/changelogs/changelog-2.x.yml` and `BadBug: this own't crash your system any more, see changelog-2.x.yml` to `docs/changelog/changelog-1.x.yml`?
15:44:52 * acozine heh, adds a typo
15:45:11 <felixfontein> acozine: no. you add the same entry to both changelogs, but the 2.0 changelog says "I'm continuing the 1.0 changelog" (and not the latest 1.x release's changelog)
15:45:29 <gundalow> acozine: community.general https://app.shippable.com/github/ansible-collections/community.general/runs/119/summary/
15:45:58 <acozine> felixfontein: I'd have to see an example, I think, to really understand it, but it sounds like something we could enforce with testing
15:46:39 <acozine> I'm going to close out the official meeting and make myself some fresh tea
15:46:58 <acozine> then I can dive back in . . .
15:47:29 <acozine> thanks bcoca felixfontein gundalow samccann tremble!
15:47:38 <acozine> #endmeeting