14:31:34 <acozine> #startmeeting Docs Working Group aka DaWGs
14:31:34 <zodbot> Meeting started Tue May  5 14:31:34 2020 UTC.
14:31:34 <zodbot> This meeting is logged and archived in a public location.
14:31:34 <zodbot> The chair is acozine. Information about MeetBot at http://wiki.debian.org/MeetBot.
14:31:34 <zodbot> Useful Commands: #action #agreed #halp #info #idea #link #topic.
14:31:34 <zodbot> The meeting name has been set to 'docs_working_group_aka_dawgs'
14:31:50 * samccann waves
14:31:53 <acozine> who's around?
14:31:56 <acozine> #chair samccann
14:31:56 <zodbot> Current chairs: acozine samccann
14:32:09 * felixfontein 
14:32:36 <acozine> welcome felixfontein
14:32:40 <acozine> #chair felixfontein
14:32:40 <zodbot> Current chairs: acozine felixfontein samccann
14:32:52 <felixfontein> hi samccann & acozine!
14:32:53 <abadger1999> Hi
14:32:59 <samccann> hello all!
14:33:00 <acozine> #chair abadger1999
14:33:00 <zodbot> Current chairs: abadger1999 acozine felixfontein samccann
14:33:15 <felixfontein> and morning abadger1999!
14:33:23 <abadger1999> Good morning felixfontein  :-)
14:33:50 <felixfontein> for me it's already 16:33 ;)
14:35:00 <acozine> tadeboro tremble baptistemm briantist madonius Pilou shaps cbudz_ gundalow you folks around?
14:35:23 <acozine> felixfontein: almost happy hour (do you do happy hour in CH?)
14:35:26 <abadger1999> He heh :-)
14:35:29 <briantist> 👋
14:35:42 <acozine> welcome briantist
14:35:45 <acozine> #chair briantist
14:35:45 <zodbot> Current chairs: abadger1999 acozine briantist felixfontein samccann
14:36:02 <felixfontein> haha, I think so, haven't been in a bar for ages... I remember this existed when I was still studying at university ;)
14:36:59 <gundalow> Hi
14:37:08 <acozine> welcome gundalow
14:37:11 <acozine> #chair gundalow
14:37:11 <zodbot> Current chairs: abadger1999 acozine briantist felixfontein gundalow samccann
14:37:51 <felixfontein> so... should we begin?
14:38:01 <acozine> yes~
14:38:06 <acozine> I mean, yes!
14:38:24 <acozine> anybody who joins late, just say hello when you get here
14:38:39 <felixfontein> (and then you become furniture)
14:38:56 <acozine> heh, yep
14:39:14 <acozine> can't have too many chairs for a good party
14:39:53 <acozine> #topic checking in about changelogs
14:39:57 <acozine> https://github.com/ansible-collections/overview/issues/18
14:39:58 * tremble lurks
14:40:03 <acozine> heh
14:40:15 * acozine whispers "welcome tremble"
14:40:20 <acozine> #chair tremble
14:40:20 <zodbot> Current chairs: abadger1999 acozine briantist felixfontein gundalow samccann tremble
14:40:50 <acozine> so where are we on changelogs
14:41:29 <samccann> #info Ansible-maintained content team considering reno with added work to produce the changelog.yml that felix's work requires.
14:41:48 <acozine> felixfontein: thanks for all the work you've done on changelog generation
14:41:58 <felixfontein> I was talking a bit with dmellado this morning; he's looking into how to generate changelog.yaml from reno; we're writing things up at https://etherpad.opendev.org/p/ansible_changelog
14:42:50 <dmellado> hey o/ I'm on #dad_mode_on, just wanted to chime in that I'll sync with dhellman on the reno thing as soon as I get some time ;)
14:42:59 <felixfontein> and I wrote up a spec for the changelog.yaml format (https://github.com/ansible/ansible/blob/devel/packaging/release/changelogs/changelog.py) and added a linter for changelog.yaml files to the generator
14:43:10 <acozine> dmellado: thanks!
14:43:28 <samccann> #info felixfontein wrote up a spec for the changelog.yaml format (https://github.com/ansible/ansible/blob/devel/packaging/release/changelogs/changelog.py) and added a linter for changelog.yaml files to the generator
14:44:29 <acozine> felixfontein: that sounds great
14:45:10 <acozine> what can we do to help with next steps? is it ready to test/try out?
14:45:29 <felixfontein> IMO it's ready to test and try out
14:45:37 <acozine> w00t!
14:45:57 <felixfontein> I also prepared a WIP PR to replace ansible's changelog generator with it: https://github.com/ansible/ansible/pull/69313
14:46:17 <felixfontein> I guess the next step is testing / playing with it, and maybe moving it to a better (i.e. more official) place
14:46:32 <felixfontein> I don't think ansible/ansible wants to rely their build process on my repo :)
14:46:33 <abadger1999> Cool.
14:46:38 <samccann> #info felixfontein also prepared a WIP PR to replace ansible's changelog generator with it: https://github.com/ansible/ansible/pull/69313
14:47:03 <abadger1999> it's a thing that's useful for people to build ansible collections?  Probably goes into ansibulled then.
14:47:16 <abadger1999> https://github.com/ansible-community/ansibulled
14:47:23 <felixfontein> I'd say so
14:47:30 <acozine> heh, I just "got" that repo name
14:47:36 <abadger1999> hee hee :-)
14:47:50 <felixfontein> does anisbulled have a dependency on ansible / ansible-base itself?
14:47:55 <abadger1999> i debated several spellings which made it more obvious and less -)
14:48:06 <abadger1999> felixfontein: I think it will eventually.
14:48:19 <acozine> and where was this one on the spectrum of most-obvious to least-obvious?
14:48:52 <felixfontein> abadger1999: that might make it harder to use in ansible-test
14:49:04 <abadger1999> Maybe I'll see if I can break the dependencies up into separate things that pip install will download (pip install ansibulled[blahblah] will require ansible but pip install ansibulled will not.
14:49:09 <abadger1999> Something like that.
14:49:37 <felixfontein> cool
14:49:44 <abadger1999> felixfontein: yeah... mattclay and I talked about that one for a long time.... I don't think we arrived at a great solution yet.
14:50:09 <abadger1999> But if changelog doesn't need to require ansible, then at least the split deps will help for changelog specifically.
14:50:18 <felixfontein> ah! what is it? I think I saw you discussing this some days ago, but I didn't have time to follow and forgot to read up later
14:50:54 <abadger1999> Part of plugin_formatter (roughly equivalent to what tadeboro built in ansible-doc-extractor) is going to be moving into ansibulled as well.
14:50:58 <felixfontein> right now it still does, but only for tiny things, and I'm wondering whether it's better to get rid of the dependency
14:51:29 <felixfontein> maybe we should discuss this after the meeting / somewhere else, to not block it :)
14:51:44 <abadger1999> and plugin_formatter uses ansible code to extract the documentation strings from modules
14:51:47 <abadger1999> <nod>
14:52:27 <acozine> sounds like good progress on changelogs
14:52:58 <acozine> I'll try creating a mock collection and testing it out this week
14:53:06 <acozine> meanwhile . . . .
14:53:12 <acozine> #topic docs pipeline update
14:53:41 <samccann> I think felixfontein has a mock collection somewhre already? maybe you can just fork it?
14:53:54 <acozine> abadger1999: thanks for all the work you've done on the pipeline, both in its first iteration and in the current round
14:54:02 <acozine> samccann: ah, thanks
14:54:25 <felixfontein> samccann: acozine: https://github.com/felixfontein/ansible-versioning_test_collection
14:54:57 <acozine> perfect, thanks felixfontein
14:54:58 <abadger1999> Aww, thanks.
14:55:10 <felixfontein> (it has a changelog spanning multiple .yaml files even. I'm not happy with the .rst naming in that collection though)
14:55:35 <acozine> heh, felixfontein that's something I can put up a PR for
14:56:00 <samccann> #info mock collection to experiment with changelog generator - https://github.com/felixfontein/ansible-versioning_test_collection
14:56:08 <acozine> anything else on changelogs?
14:56:14 <acozine> I should have asked that earlier
14:56:40 <felixfontein> an updated ACD changelog generator WIP hack: https://github.com/felixfontein/ansibulled/tree/acd-changelog/acd_changelog
14:56:50 <felixfontein> with result: https://github.com/felixfontein/ansibulled/blob/acd-changelog/acd_changelog/acd.rst
14:57:02 <felixfontein> (it no longer contains community.general etc. since there's no published version with a changelog)
14:57:18 <felixfontein> besides that, no
14:57:49 <acozine> that's a lot!
14:57:55 <samccann> https://www.irccloud.com/pastebin/MVT9chqV/
14:59:27 <acozine> #info updated ACD changelog generator WIP hack: https://github.com/felixfontein/ansibulled/tree/acd-changelog/acd_changelog with result: https://github.com/felixfontein/ansibulled/blob/acd-changelog/acd_changelog/acd.rst
14:59:36 <acozine> thanks felixfontein
15:00:12 <acozine> all right, let's talk about the docs pipeline a bit
15:01:01 <acozine> abadger1999: what's the latest?
15:03:07 <abadger1999> Work is now split into two places.  The collection downloading and generation of rst from those collection files will live in ansibulled: https://github.com/ansible-community/ansibulled/pull/5
15:04:00 <abadger1999> The idea is that this will be usable for both the docs pipeline and external collection authors who want to build docs for just their collections.
15:04:13 <samccann> #info  The collection downloading and generation of rst from those collection files will live in ansibulled: https://github.com/ansible-community/ansibulled/pull/5
15:04:42 <acozine> so if folks want to publish mini-docsites of their own, they can
15:04:45 <acozine> that's excellent
15:04:46 <samccann> #info The idea is that this will be usable for both the docs pipeline and external collection authors who want to build docs for just their collections.
15:04:55 <abadger1999> I'm currently implementing download of collections which were built into an ansible-2.10 release in that tool.
15:05:18 <abadger1999> next, I'll work on implementing parsing of the embedded docs and then output of rst.
15:05:31 <acozine> ah, the "special collection" AKA Stuff That Had To Stay in Core
15:06:14 <acozine> is that what you mean by "collections which were build into an ansible-2.10 release"?
15:06:22 <acozine> s/build/built
15:06:25 <abadger1999> Once that's done, I'll get back to https://github.com/ansible/ansible/pull/59761 and use the ansibulled-docs tool to create the subsection of docs.ansible.com which is devoted to collection content.
15:06:51 <abadger1999> Actually, I mean the set of collections which are in ansible-2.10.
15:07:04 <acozine> glad I asked
15:07:19 <abadger1999> When I build ansible-2.10, it will generate a file which has the collections and the versions which were built into that release.
15:07:27 <acozine> so this is the ACD manifest?
15:07:48 <acozine> the thing we were calling ACD, that is?
15:07:54 <felixfontein> these files in turn will be needed by the ACD changelog tool to generate a combined changelog
15:08:05 <abadger1999> That file will look like this: https://toshio.fedorapeople.org/ansible/acd/acd-2.10.0.deps
15:08:40 <abadger1999> I'll store that file in a git repo: https://github.com/ansible-community/ansible-build-data
15:09:42 <abadger1999> So when the ansibulled-docs tool runs (or the changelog tool or anything else that needs the information) it can get it from the git repo.
15:10:15 <abadger1999> Then it will download those collections at those versions from galaxy.
15:10:22 <abadger1999> And parse them for their documentation.
15:10:39 <acozine> okay, let me see if I'm following this
15:10:45 <abadger1999> That way what we document in the stable branches will match with the versions of the collections which were shipped in that release.
15:11:52 <acozine> when we publish documentation, first we check for the latest release - for example, 2.10.0 - and we check the ACD dependencies to get a list of collections and their versions
15:12:31 <acozine> then we pull those versions of those collections from Galaxy and generation rST files from the plugin files
15:12:39 <acozine> s/generation/generate
15:13:01 <acozine> these two steps happen in in ansibulled-docs
15:13:15 <abadger1999> Yes.
15:13:56 <acozine> the output of those tasks triggers a new build in ansible/ansible, which adds the plugin rST files to the rST files within the repo and generates HTML for all of it
15:14:09 <acozine> that step happens in ansible/ansible
15:14:31 <abadger1999> Sort of.... I'm imagining that it will be a pull process.
15:16:14 <acozine> as a collection owner, then, if I want to publish my docs to mydocsite.mycollection.com, I can use the ansibulled-docs utility to generate rST
15:16:26 <abadger1999> you'll trigger a docs build on ansible/ansible.  The docs build will install the tool from ansibulled as one of its dependencies.  As one of hte build steps, it will run the ansibulled-docs command which will do the steps you mentioned earlier (checking for the last acd release, downloading those collections at those versions, extracting the rst from there)
15:16:28 <acozine> then I implement my own Sphinx build to create the HTML?
15:17:47 <abadger1999> Then the ansible/ansible docs build will possibly add extra things around that (for instance, I'm not sure whether the ansibulled-docs build should create index.rst files or not) and then the ansible/ansible docs build will run sphinx to generate the whole docs site, including the collections info.
15:18:10 <abadger1999> acozine: For the collection owner, you've got it exactly how I see it working.
15:19:00 <acozine> thanks, I think I understand it
15:20:36 <acozine> #info new collections pipeline will be split into two parts, the ansibulled part mentioned above, which generates rST from plugin docstrings, and the Sphinx (rST-to-HTML) part
15:21:34 <acozine> #info collections owners can use ansibulled-docs to generation rST from their plugin docstrings
15:22:12 <abadger1999> One thing I'm not sure about is whether ansibulled-docs should output index.rst files or if that should be up to the collection owner/ ansible/ansible build script.   I think I'm leaning towards ansibulled-docs now since I heard that we might want collections to ship other rst files for the sphinx docsite in the future.
15:22:25 <abadger1999> Like scenario guides.
15:23:16 <abadger1999> ansibulled-docs should be responsible for extracting those from the collections and placing them somewhere... which indicates to me that there should be a per-collection index.rst that links that all together.
15:23:26 <acozine> yes, if collections are going to work well, they will need more than just the bare module docs
15:23:39 <felixfontein> as a collection owner, I'd prefer if ansibulled-docs provides them. (if I don't like the result, I can still replace them.)
15:23:50 <abadger1999> Cool :-)
15:24:29 <abadger1999> There's a second inde.rst as well, one which would list all of the collections which ansibulled-docs built in this run.  I'm not sure if it should build that one too.
15:24:32 <felixfontein> also having the scenario guides in ansible/ansible is another bottleneck on the core (docs) team, though probably not as bad as the module/plugin bottleneck
15:24:32 <samccann> #agreed would be good if ansibulled-docs also outputs index.rst files. Will be handy if/when scenario guides are moved into collections /docs folder and pulled back to docs.ansible.com
15:26:01 <abadger1999> It's also not a big deal for me to generate these in one script for the Proof of concept and then move them around later asw we get experience with how people use it :-)
15:26:07 <acozine> yes, the scenario guides are only as good as the maintenance that's put into them . . . and the community maintainers know a lot more about those topics than the docs team
15:26:33 <acozine> that sounds great
15:26:39 <felixfontein> indeed!
15:27:19 <acozine> other comments, questions, concerns, ideas, etc. on the New Docs Pipeline?
15:28:20 <acozine> all right, we have two minutes left
15:28:26 <abadger1999> I'm trying to have a proof of concept ready by Friday but I am a little behind.  I should definitely have rst output to show by then but the website might not be building yet.
15:28:55 <felixfontein> acozine: we also started somewhat late
15:28:58 <acozine> abadger1999: no worries
15:29:24 <acozine> felixfontein: heh, that Swiss timekeeping working in our favor!
15:29:47 <acozine> I'd like at least to bring up the topic of . . .
15:29:56 <acozine> #topic ansible_metadata
15:29:58 <felixfontein> ANSIBLE_METADATA?
15:30:08 <felixfontein> is there any more use for it?
15:30:11 <acozine> you read my mind, felixfontein
15:30:15 <samccann> there was some chatter yesterday about the different fields yeah
15:30:20 <felixfontein> no, I looked in the agenda :D
15:30:22 <acozine> heh
15:30:29 <abadger1999> Hee hee :-)
15:30:31 <acozine> ruining the illusion!
15:30:40 <acozine> never tell the audience how the trick is done!
15:30:41 <abadger1999> Written communication > ESP ;-)
15:31:22 <acozine> do collections provide everything that ansible_metadata used to provide?
15:31:35 <acozine> maintenance seems obvious
15:31:35 <samccann> so there are three fields, one of which is the metadata version itself.  So that leaves us with status and supported by
15:31:46 <acozine> ah, right supported_by
15:31:54 <acozine> that's what I meant by maintenance
15:31:58 <felixfontein> I guess `supported_by` no longer really makes sense (at least not with its current values); `status` is only needed for deprecation in ansible/ansible I think, and metadata_version... well....
15:31:58 <samccann> supported_by doesn't seem to matter in collections world... they are either certified in full or not
15:32:13 <samccann> and anything in core is I think supported by default right?
15:32:18 <felixfontein> the routing/tombstoning PR will do deprecation in collections; ANSIBLE_METADATA is totally not involved in it
15:32:31 <abadger1999> They only provide supported_by
15:32:32 <samccann> hmm... well collections could have a deprecated module in the future can't it?
15:32:33 <gundalow> https://docs.ansible.com/ansible/latest/dev_guide/developing_modules_documenting.html#ansible-metadata-block defines the format
15:32:43 <acozine> gundalow: thanks
15:32:49 <gundalow> Only thing I'm not sure about is status
15:32:56 <felixfontein> samccann: deprecation is done via meta/routing.yml
15:33:00 <samccann> #info https://docs.ansible.com/ansible/latest/dev_guide/developing_modules_documenting.html#ansible-metadata-block defines the format
15:33:07 <samccann> felixfontein - now and forever?
15:33:10 <gundalow> does status `stableinterface`, `preview` make sense?
15:33:18 * abadger1999 searches for the routing PR again...
15:33:24 <acozine> I'm not sure they ever made much of a difference
15:33:25 <felixfontein> samccann: now not, only from when nitzmahone's PR gets gerged
15:33:39 <felixfontein> abadger1999: http://www.hinwil.ch/de/polverw/verwaltung/rechtsgueltigeamtspublikationen/?action=showinfo&info_id=926111
15:33:42 <felixfontein> lol
15:33:44 <felixfontein> https://github.com/ansible/ansible/pull/67684
15:33:44 <abadger1999> They make sense.  But it's a question of whether people want to use those fields or not.
15:33:48 <felixfontein> that's the correct link
15:33:58 <felixfontein> copy'n'paste is hard
15:34:01 <abadger1999> Thanks :-)
15:34:13 <samccann> I'm struggling with this one (the PR handling deprecation). How does something in ansible/ansible know a module in a random collection has become deprecated in say collection v 1.1.2?
15:34:15 <acozine> wow, German URLs get long
15:34:34 <felixfontein> samccann: the collection's meta/routing.yml, not ansible/ansible's lib/ansible/config/routing.yml
15:35:06 <felixfontein> acozine: it's an official publication by the local town council....
15:35:07 <samccann> aaaah gotcha
15:35:11 <felixfontein> totally unrelated to ansible ;)
15:35:12 <bcoca> see community.general for examples, migration moved _deprecated to deprecated + routing.yml entry
15:35:21 <bcoca> ^ but 'not working yet' .. routing PR ...
15:35:27 <felixfontein> exactly
15:35:33 <acozine> routing.yml in ansible/ansible reflects the Great Plugin MIgration, all changes that happen after that will be in collection-level routing.yml files?
15:35:37 <felixfontein> and ansible-test's validate-modules is bitching about it
15:35:44 <felixfontein> (until gundalow's PR gets merged)
15:35:45 <bcoca> some 'manually migrated' kept the _depname so those need to be fixed
15:36:07 <felixfontein> once gundalow's PR gets merged ansible-test will complain about _depname
15:36:08 <samccann> #info collections meta/routing.yml handles module deprecation in a collection
15:36:28 <felixfontein> gundalow's PR: https://github.com/ansible/ansible/pull/68646
15:36:54 <samccann> #link https://github.com/ansible/ansible/pull/68646
15:37:47 <abadger1999> acozine: by and large.... routing.yml in ansible/ansible is still getting updated but nitzmahone wants to close that spigot at some point.
15:38:26 <acozine> abadger1999: ah, okay . . . still, it will be a "point in time" file, and ongoing maintenance/changes/updates will happen in the collections
15:38:37 <abadger1999> Different dates have been proposed ranging from now, to one of the freezes for 2.10.
15:39:06 <acozine> heh, I hear voices saying "Make it stop"
15:39:06 <felixfontein> IMO it should not be frozen yet, since there are still sporadic movements happening
15:39:30 <felixfontein> and I guess it needs updating so that it actually points to correct places
15:39:37 <acozine> that would be helpful
15:39:50 <abadger1999> I don't know if this is exactly what nitzmahone would say but i think itshould be responsible for what changes in ansible-base... ie, the great migration and any future changes in core modules.  (yum gets moved out to a collection later.  lineinfile gets renamed.   etc)
15:39:50 <acozine> the larger point remains valid - at some point we will stop updating that file
15:39:56 <acozine> and further updates will happen elsewhere
15:40:13 <acozine> abadger1999: that fits the pattern
15:40:13 <samccann> so is it correct to say both the module status is set to deprecated AND the meta/routing.yml?  or is only the latter needed to deprecate a module that is in a collection?
15:40:46 <abadger1999> samccann: currently both.  But we could change to only one.
15:40:48 <acozine> since those modules live in a fake collection within ansible/ansible, we could say that the ansible/ansible routing.yml file *is* "their" collection routing.yml
15:40:51 <felixfontein> samccann: technically the latter suffices (or will suffice), but validate-modules will complain if you don't change the former
15:40:55 <abadger1999> removal is also both.
15:41:13 <samccann> felixfontein  until gundalows PR merges?
15:41:14 <abadger1999> acozine: yep.
15:41:23 <felixfontein> samccann: from the point on when it is merged
15:41:34 <felixfontein> right now it complains that deprecated modules/plugins don't have a _ prefix
15:41:45 <acozine> ah
15:41:47 <felixfontein> which is wrong
15:42:03 <acozine> still, none of this affects the debate about the metadata field
15:42:15 <abadger1999> things like the docs process validate that the metadata is in agreement with the way we used to do deprecations (via file naming).
15:42:35 <abadger1999> so a straightforward port would have the docs process use both and complain if they were out of sync.
15:42:59 <acozine> what's the advantage of keeping both?
15:43:02 <abadger1999> But we can remove the metadata from the equation and just use the other.
15:43:37 <acozine> it sounds like duplication of data, duplication of effort, and an opening for data drift with no advantage . . . am I missing something?
15:43:38 <abadger1999> So....... Do content authors want to use status as a thing that shows up on docs, in ansible-doc, etc?
15:43:43 <abadger1999> That's the real question.
15:44:15 <acozine> that's a cogent summary
15:44:16 <felixfontein> `stable` vs. `preview` could be useful
15:44:32 <abadger1999> yeah, exactly.
15:44:33 <felixfontein> I guess some collections want this
15:45:29 <acozine> so metadata needs to stay in some form or other
15:45:43 <samccann> #info supported_by metadata seems to no longer serve a purpose. TBD on whether collection owners/core still want status field in the metadata (stable vs preview etc)
15:45:55 <abadger1999> So if they want to do that, we should keep the status around (or move it into the DOCUMENTATION schema... before it was supposed to be used by code [only allow modules that are supported to be run on a customer's system].
15:46:22 <abadger1999> removed was also useful.
15:46:35 <bcoca> fyi, i believe the decision was alreayd made to phase out metadata , at least from ansible-base
15:46:43 <abadger1999> It told people "here's the documentation for a module which you might still have in your playbooks but no longer exists"
15:46:47 <felixfontein> removed is also replaced by nitzmahone's PR (tombstoning in meta/routing.yml) I think
15:47:04 <bcoca> felixfontein: not replaced, but that is how collections will work
15:47:32 <samccann> So  in summary - ansible-base is phasing out ANSIBLE_METADATA entirely, collections 'may' still want to use the status field but we need to followup to see if that's true?
15:47:35 <bcoca> not sure it will work for plugins in base
15:47:48 <abadger1999> felixfontein: Okay... If removed in tombstoning allows for the documentation to stay but the module to nt be used, then that can be done wholly from routing.yml as well.
15:48:01 <abadger1999> samccann: that sounds good to me.
15:48:21 <felixfontein> abadger1999: I guess the docs will also go away, but a stub could be left saying that the module no longer exists
15:48:22 <samccann> #info in summary - ansible-base is phasing out ANSIBLE_METADATA entirely, collections 'may' still want to use the status field but we need to followup to see if that's true
15:48:23 <abadger1999> samccann: ooh, there is more we can do if we want.
15:48:38 <samccann> what am i missing toshio?
15:48:46 <abadger1999> samccann: Like we can document and tell people supported_by will be ignored and not shown in the docs from now on.
15:48:51 <felixfontein> there is *always* more :)
15:49:14 <abadger1999> samccann: If we decide routing is canonical, we can say "status deprecated and removed will be ignored and not displayed"
15:49:21 <samccann> yeah we can update the docs on coding a module to say what if any of the metadata is still needed
15:49:32 <abadger1999> yep0.
15:50:02 <samccann> so is the general feeling now that meta/routing.yml should be the source of truth for deprecation/removed ?
15:50:26 <abadger1999> and when we ask people if htey want to usestatus, we can also ask if they would be okay if status moved into a DOCUMENTATIOn field instead of metadata.
15:50:54 <abadger1999> I'd feel good about that but I don't know what adoption will look like.
15:51:16 <samccann> #info collection meta/routing.yml should be the source of truth for deprecation/removed and we can move any other status needs into an optional DOCUMENTATION field
15:51:17 <felixfontein> I guess the docs tool still needs to support extracting that info from ANSIBLE_METADATA when that's still around
15:51:31 <felixfontein> at least for some time
15:51:51 <gundalow> I'm continuing to update ansible-base's routing.yml till ansible-base's beta (~4 weeks)
15:51:56 <abadger1999> The best thing to help adoption would probably be a script which parses ANSIBLE_METADATA and moves it to routing.yml.
15:52:06 <felixfontein> I guess a good place to ask people is here: https://github.com/ansible-collections/overview/issues/45
15:52:24 <gundalow> I plan on merging deprecation update to validate-modules on thursday morning (UK)
15:52:42 <acozine> if docs is the only place we use that metadata field, then putting in the DOCUMENTATION schema makes a lot of sense
15:52:49 <felixfontein> gundalow: good to know! we'll need to update ignore.txt etc. then so that CI won't turn red
15:52:58 <gundalow> I don't know if we've ever move anything from `preview`to `stableinterface`
15:53:07 <abadger1999> Well... we could also think of it as ANSIBLE_METADATA has optional metadata that people don't really use.... in which case, we can say "If you really want to show this to your users, put it here instead"
15:53:11 <gundalow> felixfontein: yup, I guess that will be a chunk of time after it
15:53:19 <samccann> i saw one stableinterface in core, but didn't check to see if it was ever set to preview
15:53:27 <gundalow> abadger1999: are you aware of anyone ever updating `status`?
15:53:40 <gundalow> I'd be tempted to just remove it for collections
15:53:51 <abadger1999> Maybe one or two.
15:53:53 <acozine> most of the stableinterface modules I've seen are the ones I think of as "truly core"
15:53:56 <felixfontein> I've wondered in the past if that value is ever updated, or what are the conditions and permissions required for doing that :)
15:54:10 <acozine> I have not seen any updates to it that I can remember
15:54:28 <acozine> in 2.5 years
15:54:57 <samccann> so the open questions are - can we remove ansible-metadata entirely from collections (core already plans on removing it) and if so, do collections owners want a DOCUMENTATION field for things like preview vs stable for module status instead?
15:55:04 <samccann> does that sound right ^^
15:55:11 <acozine> the only times I've seen the field referenced at all were when someone closed an issue with "yeah, this module changed, it's preview, that happens"
15:55:48 <abadger1999> samccann: yeah, I like that.  It doesn't give them the option of wanting to keep ANSIBLE_METADATA itself ;-)
15:56:46 <acozine> \o/
15:57:02 <abadger1999> One of hte problems with the status field has been it's a guarantee but while in the core repo, the guarantee seems to come from the core team, not the module owner.
15:57:22 <samccann> ok added this to the issue - https://github.com/ansible-collections/overview/issues/45#issuecomment-624141136
15:57:33 <samccann> lemme know if it needs changing etc.
15:57:52 <abadger1999> even if a module owner wanted to declare "I want to tell my customers they can count on this having a stable interface" it might not match up with the length of time that hte core team would want.
15:58:06 <felixfontein> samccann: maybe link to an issue where the discussion should be happening, so #45 stays 'clean'
15:58:18 <abadger1999> now that there are collections, it could probably be done better.
15:58:57 <samccann> good idea felix - will do that now
15:59:33 <felixfontein> import_role, include_tasks and vice versa were changed from preview to stableinterface in Feb 2019 (3c85ac1788ae2b6df73a538589cdf675d6d4b254)
16:00:50 <acozine> oh, interesting
16:00:58 <felixfontein> bigip_command and some more f5 modules where changed from preview to stableinterface in Jun 2018 (58d857f235f25c0dd3b3715566fed1b70727ad4e)
16:00:59 <acozine> though those are hardly modules in the ordinary sense
16:01:15 <acozine> ah, so some of the network folks do use that field
16:01:53 <felixfontein> that was everything bteween Dec 17 and pre-ansible-base
16:02:27 <acozine> not a hugely popular option, then
16:02:45 <acozine> something like 12 out of 3,000 modules?
16:03:19 <acozine> well, let's encourage folks to chime in on samccann's issue
16:03:21 <gundalow> f5 is supported content
16:03:58 <acozine> gundalow: yes, and my bet is that they would be happy to move that field into the DOCUMENTATION sections
16:04:59 * gundalow votes to ignore ANSIBLE_METADATA when building Collection docs
16:05:02 <acozine> if folks start using that field more, maybe we could connect it to the porting guides . . . .
16:05:16 <acozine> we've gone a half-hour over today's meeting time
16:05:41 <acozine> not our longest ever, but still . . .
16:05:52 <felixfontein> too bad we didn't got to version_added :)
16:05:54 <samccann> #info consider ignoring ANSIBLE_METADATA entirely when building collection docs
16:06:14 <acozine> felixfontein: heh, next week can be Metadata Madness
16:06:21 <felixfontein> hehe :)
16:06:55 <felixfontein> I have three PRs for deprecation and version_added in collections
16:07:13 <acozine> a use case! a real, live use case!
16:07:38 <felixfontein> one use-case is that the changelog generator uses version_added to compile the list of new modules/plugins
16:08:04 <acozine> mmm, we're definitely not going to get through that discussion today
16:08:20 <felixfontein> no, next week
16:08:28 <samccann> I'll add it to next week's agenda (along with felix's use case so we don't forget)
16:08:32 * felixfontein has to start preparing dinner now
16:08:34 <acozine> thanks samccann
16:08:46 <acozine> all right, another great DaWGs meeting
16:09:07 <acozine> thanks felixfontein abadger1999 briantist gundalow samccann tremble and all the lurkers out there!
16:09:19 <samccann> oh do we need a quick openfloor?
16:09:26 <acozine> oh, yep
16:09:33 <acozine> gotta observe the protocols!
16:09:34 <samccann> incase anyone has been patiently waiting for 90 min
16:09:38 <acozine> #topic open floor
16:09:43 <felixfontein> thanks everyone!
16:10:10 <acozine> if you have been watching this conversation, wanting to bring up a question or comment or problem, please chime in!
16:10:18 <acozine> felixfontein: ciao, enjoy your dinner
16:10:59 <acozine> meanwhile, the usual reminders
16:11:17 <acozine> comments/questions/suggestions/ideas/concerns are always welcome in this channel at any time
16:12:01 <acozine> you can also add items to the agenda for the weekly meetings by putting a comment on https://github.com/ansible/community/issues/521
16:12:17 <acozine> newcomers welcome!
16:13:19 <acozine> I'll close the official meeting now, thanks, folks!
16:13:22 <acozine> #endmeeting