14:31:28 #startmeeting Ansible Docs Working Group aka DaWGs 14:31:28 Meeting started Tue Mar 24 14:31:28 2020 UTC. 14:31:28 This meeting is logged and archived in a public location. 14:31:28 The chair is acozine. Information about MeetBot at http://wiki.debian.org/MeetBot. 14:31:28 Useful Commands: #action #agreed #halp #info #idea #link #topic. 14:31:28 The meeting name has been set to 'ansible_docs_working_group_aka_dawgs' 14:31:59 #topic general check-in 14:32:19 how are folks coping with Life in the Time of Coronavirus? 14:32:34 * samccann waves 14:32:41 #chair samccann 14:32:41 Current chairs: acozine samccann 14:33:51 I've got milk and bread to last at least 10 days.. doing good :-) 14:33:57 (oh and chocolate...) 14:34:15 we have a lot of random groceries in the house 14:34:52 plenty of canned tunafish but not much to mix with it for tuna salad 14:35:01 heh woopsie 14:35:07 a big jar full of rice 14:35:52 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 (only partially here though) 14:36:02 yum yum! 14:36:02 hey, felixfontein! 14:36:15 felixfontein: partial or not, you're getting to be furniture 14:36:19 #chair felixfontein 14:36:19 Current chairs: acozine felixfontein samccann 14:36:50 * gundalow waves 14:36:58 hey, gundalow! 14:37:01 #chair gundalow 14:37:01 Current chairs: acozine felixfontein gundalow samccann 14:37:10 #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 #info We will also do Hackathon on Monday & Tuesday 14:39:14 what's the time UTC now? 14:39:26 * acozine puts the contributors summit on her home calendar 14:39:58 do we have hackathon plans for docs? 14:40:51 In the docs meeting yesterday we talk about the 4 topics of docs. That could be something we could hack on 14:40:56 I put something on the agenda . . . but that was a few weeks back, which now feels like years ago 14:41:12 as well as if there are PRs to review or things to help test/give feedback on 14:43:14 Will devel be unfrozen by Monday? 14:43:58 hi tremble! 14:44:03 #chair tremble 14:44:03 Current chairs: acozine felixfontein gundalow samccann tremble 14:44:16 o/ 14:44:26 I believe it is unfrozen now 14:44:53 at least, the old, batteries-included branch has been replaced with the new, most-plugins-in-collections branch 14:45:05 as of yesterday 14:45:26 PRs that were opened before the Plugin Exodus will need to be rebased 14:45:49 PRs affecting migrated modules or other content will need to be moved 14:46:40 #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 tremble: was there a specific PR you wanted to follow up on? 14:47:24 Nope 14:48:03 okay 14:48:12 * acozine looks at the agenda for today 14:49:22 all right, first topic is release notes/changelogs/porting guides in the Collections Ecosystem 14:49:32 #topic release notes for Collections 14:50:02 from last wee: 14:50:06 er, week 14:50:11 weeeee!!! 14:50:14 heh 14:50:21 * samccann full of useful commentary today 14:50:24 `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 I need to dig up the issue where we are tracking this... 14:51:37 #info tracking issue for changelog process - https://github.com/ansible-collections/overview/issues/18 14:51:56 I haven't gotten to dig into reno etc yet, but I'll put notes there as I do. 14:52:28 I have not used either reno or towncrier 14:53:12 * acozine looks for basic info 14:53:20 Can ask in #openstack-ansible about Reno they uses it a lot 14:53:43 #info reach out to #openstack-ansible about reno as they use it already 14:53:56 acozine: the links are in that issue above ^^ 14:54:28 samccann: ah, excellent 14:56:39 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 agreed 14:57:06 oh... and c) hoping the end result is usable :-) 14:57:08 heh 14:57:41 ...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 so for `a+b` we could enforce that by CI 14:58:34 good to know 14:59:10 if we have to, we can fall back on manual editing for the porting guide, as part of the release process 14:59:15 I struggle with envisioning how we achieve b. 14:59:17 gundalow: what does CI look like on the collections side? 14:59:36 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 gundalow: for repos in `ansible-collections`, at least? 14:59:55 i'm sure there's magic there somewhere, I'm just not up to seeing it yet 15:00:52 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 so the repos don't have to be on GitHub 15:01:52 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 (i.e. combined into very few files) 15:03:03 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 felixfontein: you're right, I'm just not sure how/where we do that . . . 15:04:15 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 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 but then ACD comes in and needs one across all three in this example 15:04:46 changelog.md sounds like "lots of manual work" 15:05:41 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 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 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 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 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 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 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 but say that bug is also in the 1.3 version of the collection 15:10:49 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 yeah ^^ that was my question as well :-) 15:11:35 I don't think so 15:11:41 but I'm not entirely sure 15:11:46 gundalow: do you know ^^^ 15:14:51 Galaxy supports downloading multiple versions, but I think every upload ticks the version number up from the previous latest version 15:14:53 https://galaxy.ansible.com/newswangerd/collection_demo 15:15:43 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 can't you define your own version number? 15:16:15 (was just making up versions btw) 15:16:38 I think they have to follow semver though 15:17:00 semver doesn't prohibit that you release 1.2.8 after 1.3.2 15:17:01 which would mandate whether the patch rolls major, minor, or bugfix numbers 15:17:08 yes 15:17:08 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 ah gotcha 15:18:51 but I don't know if you can choose a lower number 15:19:35 I've asked the galaxy team, will relay the answer when it comes (probably after the end of this meeting) 15:21:37 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 galaxy has a wishlist right now but no current development 15:24:10 bcoca: you can definitely list multiple versions on Galaxy 15:25:00 one feature we recently asked for is 'versions pertaining the version of ansible making teh query' 15:25:07 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 e.g 'ansible-galaxy search' from 2.11 would get collections compatible with >=2.11 15:25:50 acozine: you should be able to, have not tested in a couple of months, but it was possible 15:26:04 you cannot release the same number, but you can increment minor versions 15:26:41 cool, thanks bcoca 15:28:34 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 possibly, but you might need that 15:29:01 for example, cve that affects multiple versions 15:29:04 but at the ACD level, presumably we would only include on version or the other 15:29:11 bcoca: yes, we'd need it 15:29:21 yep, you should not include more than one version of same collection in ACD 15:29:58 but wont you want accumulated changes? 15:30:27 or you want only changes from previous acd to new acd? 15:30:32 that might be very tricky 15:31:02 ideally we'd want changes between ACD 1.0 and ACD 1.1, right? 15:31:04 prev acd = 1.03 new acd = 2.15 and you have 1.54 as latest of 'v1' 15:31:22 ^ all collection version 15:31:36 yep that's the thing I've been trying to think thru bcoca 15:31:41 so acd 1 has 1.03 of coll, and acd 1.1 has 2.15 15:31:49 .... 'fun' 15:31:55 * samccann nods 15:32:14 that's the problem I couldn't find anyone else solving (aka RHEL, Fedora) 15:32:16 ah, yeah, it depends on when in the sequence the developers started the 2.x series 15:32:58 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 yeah, i dont thnk any distro tries to be 'as helpful' as you are being 15:33:37 they mostly have 'changelog packge X is now 3.21' 15:33:53 yep. that's what I saw 15:33:57 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 so do we follow suit, or try to solve the problem others haven't solved? 15:34:37 considering teh difficulty of the problem ... i understand it, still feels like copout 15:34:45 I'm more and more tending to "follow suit" 15:35:00 bcoca: exactly 15:35:37 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 gentoo 'kindof' manages this via changelong but that is only for updates between releases 15:35:59 got a pointer for that? 15:36:04 for security updates, most distros do this, but not for major release 15:36:16 samccann: not sure it can apply, gentoo is 'roling release' 15:36:48 so its always just update specific packages, changelog per package is easier (since they aslo download/compile sources, normally changelog available) 15:38:00 samccann: https://www.gentoo.org/ 15:38:08 oops, we're over time 15:38:28 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 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 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 acozine: CI wise, for community.general we basically have the same in ansible/ansible. for others we have GitHub Actions. 15:40:09 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 gundalow: thanks 15:41:07 acozine: was there more detail you'd like? 15:41:40 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 gundalow: if you have a link to a Shippable run, that would be great 15:42:19 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 felixfontein: I'm having trouble imagining what that looks like, but it sounds plausible 15:43:49 it of course requires that people keep their changelog.yml files in order and with the correct metadata 15:44:23 which we might be able to do for some collections, but which others might not do at all 15:44:25 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 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 acozine: community.general https://app.shippable.com/github/ansible-collections/community.general/runs/119/summary/ 15:45:58 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 I'm going to close out the official meeting and make myself some fresh tea 15:46:58 then I can dive back in . . . 15:47:29 thanks bcoca felixfontein gundalow samccann tremble! 15:47:38 #endmeeting