14:31:52 <acozine> #startmeeting Docs Working Group aka DaWGs
14:31:52 <zodbot> Meeting started Tue May 12 14:31:52 2020 UTC.
14:31:52 <zodbot> This meeting is logged and archived in a public location.
14:31:52 <zodbot> The chair is acozine. Information about MeetBot at http://wiki.debian.org/MeetBot.
14:31:52 <zodbot> Useful Commands: #action #agreed #halp #info #idea #link #topic.
14:31:52 <zodbot> The meeting name has been set to 'docs_working_group_aka_dawgs'
14:32:07 <felixfontein> hey!
14:32:17 <acozine> agenda is https://github.com/ansible/community/issues/521#issuecomment-624153545
14:32:25 * samccann waves
14:32:26 <acozine> hey felixfontein!
14:32:31 <acozine> #chair felixfontein samccann
14:32:31 <zodbot> Current chairs: acozine felixfontein samccann
14:32:36 <acozine> who else is around?
14:33:37 <acozine> gundalow: are you running with the DaWGs today?
14:34:14 <acozine> cbudz: how about you?
14:34:29 <bcoca> hmm, this seems apropos https://github.com/ansible/ansible/pull/69454 <= was asked yesterday to 'remove metadata from base'
14:34:36 <acozine> #chair bcoca
14:34:36 <zodbot> Current chairs: acozine bcoca felixfontein samccann
14:34:46 <cbudz> hey, I'm half in here, half in another meeting before an 11am
14:35:00 <bcoca> this meeting is always in conflict
14:35:04 <acozine> cbudz: sounds good, ping me when you are ready to "become furniture"
14:35:18 <cbudz> will do
14:35:35 <acozine> bcoca: that PR should be part of the discussion around metadata, thanks for the link
14:36:01 <acozine> speaking of which  . . .
14:36:11 <acozine> #topic removing ansible_metadata
14:36:23 <acozine> I just don't have the heart for all caps today
14:36:42 <samccann> #info collections tracking issue  - https://github.com/ansible-collections/overview/issues/57
14:36:56 <samccann> #info ansible-base issue - https://github.com/ansible/ansible/pull/69454
14:37:11 * acozine takes some time to read the comments on the collections issue
14:37:27 <samccann> #info ansible metdata has two fields, neither of which seem necessary in the new world order
14:38:01 <felixfontein> except maybe status
14:38:24 <bcoca> which i would argue is easy to move into main DOC field
14:38:37 <felixfontein> me too
14:38:58 <bcoca> we might be creating new std for that and probably a few more things in near future, i have old proposal that needs to be expanded for such things
14:39:48 <acozine> looks like there's broad agreement in the comments that making `status` a field in the documentation section of each module is a good approach
14:40:07 <acozine> the main debate seems to be over what the default value should be
14:40:40 <acozine> I'm trying to parse resmo's comment: https://github.com/ansible-collections/overview/issues/57#issuecomment-624483813
14:40:44 <samccann> #agreed move status field to an optional documentation section of each module and remove ANSIBLE_METADATA field entirely
14:40:44 <bcoca> normal use would be something flagged as 'preview' when introduced witha 'interface may change' warning
14:41:23 <bcoca> default would be 'stable' for existing, but the 'meaning' is very diff from stuff 'officially Suported' and stuff 'offcially supported', community and 3rd party
14:41:39 <felixfontein> acozine: resmo wants default to be preview; and says that since it is a docs field, you could also specify a default value for a groups of modules in doc_fragments, and overwrite it for an individual module
14:41:40 <acozine> resmo voted for making the default value `preview` but then said `It would also be easy to change the default to stable in the plugin doc_fragment and overwrite in the modules to preview where appropriate.`
14:41:48 <bcoca> for now, i think adding a note: this is a tech preview is 'good enough'
14:41:57 <acozine> felixfontein: ah, I see
14:42:23 <samccann> bcoca so you are saying no specific doc field for status - if  it's not stable, add that to the module description?
14:42:31 <bcoca> felixfontein: unsure that will work, depends on fragment merging and that was mostly designed for options
14:42:33 <acozine> for those who would prefer the default to be `stable`, that's a good workaround
14:42:38 <bcoca> samccann: basically
14:42:46 <bcoca> cause 'stable' means very diff things to diff people
14:42:51 <samccann> my initial reaction is to agree w/ bcoca
14:42:56 <felixfontein> bcoca: right now modules can always overwrite fragments
14:43:01 * samccann waits for everyone to recover from fainting
14:43:07 <bcoca> but a note about 'hey,c areful this is a new shinny but unstable thing' , is easy to digest
14:43:12 <acozine> samccann: heh
14:43:27 <bcoca> felixfontein:  i designed that for options, dont knwo if it works outside of them
14:43:27 <samccann> I feel like if we put in a default (either one) it won't make people happy. And if it's preview, it will NEVER CHANGE
14:43:46 <acozine> in the old model, `stable` meant "guaranteed not to have backwards incompatible changes"
14:43:48 <bcoca> samccann: yep, that is my thought train also
14:44:04 <felixfontein> samccann: better have 'preview' which never changes, than having 'stable' and suddenly the interface of the module changes
14:44:07 <bcoca> acozine: not really, add 'without a very good reason'
14:44:12 <samccann> i believe that is the first sign of the Apocalypse... or we just cracked open the First Seal or something
14:44:15 <acozine> are we really ready to make that guarantee for all existing modules?
14:44:20 <bcoca> its mostly 'try to avoid as much as possible changing the interface'
14:44:39 <felixfontein> bcoca: that's also what preview often means ;)
14:44:42 <samccann> felixfontein - the deafult would be no default. We don't put anything
14:44:56 <samccann> IF the module creator feels the need for a status, they manually add it to a module themselves
14:45:11 <acozine> samccann: so the default value is null, most modules have no status
14:45:26 <samccann> yes. there is no status 'field' so to speak
14:45:30 <felixfontein> samccann: that would be OK for me too. I just don't like stable as a default :)
14:45:31 <acozine> if a maintainer wants to advertise that her modules are guaranteed backwards compatible, she can
14:45:40 <samccann> if you have something stetchy - add it as a note in the description or something
14:46:03 <acozine> and if a new developer wants to warn that her modules are still WIP, she can label them `preview`
14:46:21 <bcoca> well, several issues a) do we want a standard field, b) if so, what should the values be, c) what do we want to enforce for ACD/AH
14:46:33 <samccann> acozine - label how? if we have no specific field for that anymore. it's just a note
14:46:48 <samccann> my nickel is no standard field
14:46:55 <acozine> ah, so we won't have a field in `DOCUMENTATION` at all?
14:46:57 <felixfontein> bcoca: I guess for ACD there's not much that can be enforced
14:46:59 <bcoca> ^ which i think works for most, at least for 2.10 we can always add later
14:47:12 <samccann> yes acozine... no field at all
14:47:24 <bcoca> felixfontein: it can be, as a rule you must meet certain requirements to be included in 'next ACD release'
14:47:29 <samccann> if we MUST have a field, I'd say it defaults to NULL and if null, never shows up on output
14:47:40 <samccann> but that would mean coordinating with AH/galaxy on that
14:47:48 <acozine> the main downside of that is that people will phrase their notes in many different ways, so there would be no way to look at that data in aggregate
14:48:04 <felixfontein> bcoca: but then someone has to detect it first :)
14:48:23 <bcoca> felixfontein: yep, that is why iask the questions, cause they will require validation
14:48:37 <samccann> does semver help us in any way here?
14:48:39 <bcoca> setting up a standard and not validating == creating 10239128409124 standards per day
14:48:48 <acozine> samccann: theoretically, yes
14:48:49 <samccann> is there a semver version for 'hey this might be unstable' :-)
14:48:51 <felixfontein> bcoca: maybe AH has the resources for this; ACD will probably not have them
14:48:55 <bcoca> samccann: it could
14:49:04 <bcoca> but right now 'version' is per collection, not per plugin
14:49:29 <bcoca> felixfontein: why i make it a point, i dont think either has the resources to enforce such standard
14:49:32 <samccann> bcoca: ah true, forgot about that
14:49:45 <acozine> <1.0 in semver is unstable, any change in the first number (for example 2.x vs. 1.x) means backwards-incompatible changes
14:49:49 <bcoca> we coudl add 'plugin_version' ?
14:50:12 <bcoca> acozine: you also have beta/alpha/etc designations for post 1.0
14:50:13 <samccann> he had that and people wanted it to be just the collection version, not per plugin
14:50:19 <felixfontein> that would make versioning even more messy
14:50:24 <felixfontein> let's stick to collection versions
14:50:26 <acozine> bcoca: that seems like overkill
14:50:42 <bcoca> not advocating, just stating the options
14:51:01 <samccann> ok how about - we have a documentation field for status, it defaults to NULL and we coordinate w/ Galaxy/AH to ignore if null
14:51:23 <samccann> then developers can use the doc_fragment trick to either set all their plugins to stable or preview if they want?
14:51:49 <samccann> so those who want a default of null ...set that in their fragment.. .those who want default preview... set that in their fragment?
14:52:10 <acozine> I like that - it communicates "we make no promises" for anything that's not actively maintained, while giving active developers options for labelling an entire collection at once or module by module
14:52:16 <samccann> hmm... but if we go that far, we might as well just set the default to 'something'
14:52:36 <samccann> acozine: - true - best practices would be set the dang field in a doc fragment
14:53:03 <felixfontein> I like it
14:53:19 <felixfontein> and I think not having a default is good, resp. the default is "don't mention this in the docs"
14:53:52 <acozine> yeah, don't make promises you can't keep, but also don't scare people for no good reason
14:54:12 <samccann> #agreed create a documentation field for status, default is NULL and will not show up in output (docs or Galaxy/AH). Developer set their preferred default in a doc_fragment (preview or stable).
14:54:37 <acozine> so this means we can remove ansible_metadata altogether
14:54:38 <samccann> oh docfragment question  - if the doc fragment is stable, can I then set an individual module as preview?
14:55:00 <felixfontein> samccann: that would be desirable. if it doesn't work yet, I'm sure we can get that to work
14:55:04 <acozine> all you have to do is leave out that doc fragment on that module
14:55:11 <bcoca> module > fragment, but again, designed for options, not top level keys
14:55:49 <samccann> #action - need to test if a module status setting overrides the doc_fragment setting so an individual module could be preview if the doc_frag default is stable for example
14:56:06 <samccann> well since it's a brand new field, it all has to be coded up right?
14:56:15 <acozine> even in collections, doc fragments are "opt in", right? you still have to add `expands doc_fragment foo` to your module
14:56:33 <bcoca> yes
14:56:42 <bcoca> fragmetns only work if plugin references them
14:56:54 <samccann> acozine: yeah but if you did use that for say 10 common options, then it would be really annoying to have to copy those options into a preview module, and then rip them back out again when it becomes stable
14:57:20 <samccann> (when you removed and then added back in the doc_fragment)
14:58:05 <bcoca> looking at code, does seem fragmetns also apply to TLK
14:58:14 <bcoca> it jsut does specific job on notes/seealso/options
14:58:16 <samccann> TLK?
14:58:27 <bcoca> but also, 'options' is required
14:58:42 <bcoca> top level keys, sorry 2 meeeints, i tend to over acronymize
14:58:43 <acozine> well, you can have a separate doc fragment for status if you want it to be easily overridden, right?
14:59:18 <samccann> acozine: true.
14:59:26 <acozine> the most common use case is probably when a new module is added to an existing collection
14:59:37 <acozine> default for the collection is `status: stable`
15:00:02 <acozine> new module overrides that to `status: preview` when first created
15:00:08 <samccann> next question for those who actually create collections/modules -how much of a pain is it if  we require you to create a docfragment per collection at least to cover this status that we can't decide on a default for?
15:00:38 <samccann> acozine: that feels like if a tree falls in a forest kind of question  - can a collection be stable if it contains a preview module?
15:01:07 <samccann> i'd say yes, but you know.. feels deeply philosophical now :-)
15:01:09 <acozine> as long as we don't require a value, as long as the default is null, folks can choose to leave it out altogether, right?
15:01:18 <samccann> yes
15:01:34 <acozine> oh, I thought this value only applied to the individual modules
15:01:34 <samccann> but what behavior do we want? no status (aka null) or stable/preview?
15:01:44 <bcoca> just note, galaxy, AH, docsite and ansible-doc will all have to change
15:02:19 <samccann> #info whatever we decide, galaxy, AH, docsite, and ansible-doc will have to change... and likely docs pipeline and doc generation changes too
15:02:31 <acozine> good question
15:02:46 <abadger1999> Are we still talking about status in documentation?
15:02:53 <acozine> abadger1999: welcome
15:02:57 * abadger1999 started reading log, then skipped a bit.
15:02:57 <samccann> personally, I think I favor no status and the collection-level is what matters.
15:02:59 <acozine> #chair abadger1999
15:02:59 <zodbot> Current chairs: abadger1999 acozine bcoca felixfontein samccann
15:03:00 <acozine> yes
15:03:24 <abadger1999> I'm unsure if stable/preview/etc makes sense in the collection world (except, ironically, for ansible-base)
15:03:33 <samccann> as in a community collection is you takes what you gets... and if the collection owner feels strongly, they can set a default status for all their modules and override as necesary
15:03:47 <abadger1999> It may be something that applies more to the whole collection.
15:03:47 <acozine> samccann: so when a dev adds a new module to a collection, it needs to be stable on day 1?
15:03:48 <felixfontein> abadger1999: it could make sense to declare some modules as preview, and some others as having a stable interface
15:04:06 <abadger1999> (I mean... it could still apply at the individual module level but I'm not sure if it will apply that way in practic)
15:04:16 <samccann> acozine: it's up to the dev to decide.
15:04:50 <samccann> i'd like to say the stability of a module is based on the collection itself. Certified collections for example should have to have stable modules.  Use the community versions to work out the kinks
15:04:52 * abadger1999 stills a second here and there to read the rest of the backlog.... two devices is good ;-)
15:04:55 <acozine> if we set that at the collection level, then the dev has to say either "all modules are stable" or "all modules are preview"?
15:05:14 <samccann> WE don't set at all. default is null.
15:05:23 <felixfontein> I don't think this should be said at collection level
15:05:38 <felixfontein> or do you mean doc fragment level with that?
15:05:40 <samccann> but yes, the dev who disagrees with that is able to set it across their collection via a doc_fragment included in all modules
15:05:51 <samccann> yeah I just mean the doc_fragment. Sorry to not be clear on that
15:06:17 <samccann> So the certified collection owner for sure doesn't need this status (thus the NULL default)
15:06:26 <samccann> what does the community collection owner need?
15:06:38 <felixfontein> samccann: why? also a certified collection could contain preview modules
15:06:39 <samccann> my nickel? they need the field
15:06:56 <samccann> they shouldn't iMO
15:07:14 <samccann> as I understand it, all certified collections have to exist as a community collection as well
15:07:17 <felixfontein> then how could you have a module for a new technology which is constantly changing?
15:07:23 <acozine> samccann: ah, so this would follow the RH standard of "bleeding edge is community/upstream only; certified content must be an older version"
15:07:33 <samccann> so if you need preview modules, you include them in your communit ycollection and don't graduate them to the certified collection until they are stable
15:07:50 <acozine> felixfontein: I think the idea is the new modules and latest changes are in the community version only
15:08:00 <samccann> acozine: for sure but we'd have to verify all that w the certification folks
15:08:16 <felixfontein> so with community, you don't mean collections in the community namespace?
15:08:33 <acozine> and those modules only get added to the certified collection when they are stable
15:08:40 <acozine> felixfontein: ah, good point
15:08:47 <samccann> I mean collections that aren't certified are community.. whatever the namespace (I'm not sure of namespace rules here)
15:09:02 <acozine> in this context "community" means "any collection hosted anywhere BUT in Automation Hub"
15:09:08 <felixfontein> so a collection company.whatever could be "community" since it is not certified?
15:09:26 <samccann> I think so... gundalow ^^ if you are around
15:09:27 <felixfontein> let's better call it "non-AH collection" :)
15:09:37 <acozine> company.whatever will have both a "community" version and a "certified" version
15:09:37 <samccann> heh
15:09:39 <felixfontein> community for me is something which doesn't belong to a company
15:09:46 <acozine> felixfontein: ah, good idea
15:10:13 <gundalow> AH is the only place certified/*S*upported collections exist
15:10:33 <gundalow> though the same (literally bit wise identicle) code may exist on Galaxy
15:11:28 <samccann> gundalow: if a certified collection wants to add a 'preview' module, would that only happen in the community version on Galaxy, or would a certified collection still be certified if it had a preview module in it?
15:11:50 * samccann realizes the irony of asking the community manager a deep certification/downstream question but anyway
15:12:14 <abadger1999> I'm not sure if AH will be all stableinterface (what the status value actually is called, btw ;-)... I'm thinking of things like azure here, which has a lot of work behind it to get it certified but at the same time, as felixfontein points out, could be fast moving in the srvice itself, leading to backwards incompatible module releases.
15:12:18 <gundalow> Well, if there is a single repo, the same meta may exist in both places
15:13:05 <gundalow> I believe someone looked and saw that only a couple of modules had ever changed their `status`, so personally I'd be tempted to ignore it till there is a real demand
15:13:21 <acozine> gundalow: we've agreed to phase out the ansible_metadata field
15:13:34 <felixfontein> maybe we should simply skip that field now, and consider it later, for example with bcoca's proposal
15:13:43 <abadger1999> gundalow: That's tempting for me too.  (ie: don't add an explicit status to DOCUMENTATION until people as k for it)
15:13:45 <felixfontein> https://github.com/ansible/proposals/issues/68
15:14:00 <acozine> so now the question is, do we just leave it out altogether? or do we let people add it to DOCUMENTATION?
15:14:17 <felixfontein> that would also allow to document in which version the module was marked as stable
15:14:39 <felixfontein> acozine: right now `ansible-test sanity` will complain about unknown fields
15:15:22 <abadger1999> also, the way we're designing this, this might be something that a generic keywords field might solve better.
15:15:29 <samccann> which is more common - a module that 'should' be considered stable, or 'should' be considered preview?
15:15:43 <abadger1999> and then let collection owners standardize on a keyword that means stableinterface.
15:16:38 <acozine> abadger1999: do we care if they never standardize? I mean, if we end up with some modules marked "stable" and some marked "mature" and some marked . . . I don't know, something else?
15:17:06 <felixfontein> I would prefer if we standardize it
15:17:14 <felixfontein> to avoid chaos :)
15:17:18 <acozine> do we ever want to look across all collections and say "X percent of modules are `preview`"?
15:17:24 <samccann> yeah that kind of leads back to the earlier discussion of just let them add a note somewhere if that's necessary to distinguish
15:17:27 <acozine> felixfontein: that's my instinct too
15:17:31 <abadger1999> acozine: I'm on the fence... One part of my brain screams, that would be horrible.  But another part of my brain screams, people will do the same thing with a standard name (just different ;-)
15:17:38 <acozine> either standardize, or leave it out altogether
15:17:55 <abadger1999> ie: some people will use stable to mean backwards compatible guarantees, others to mean, relatively bug free.
15:18:04 <abadger1999> etc etc etc.
15:18:06 <samccann> very true
15:18:08 <acozine> "mostly harmless"
15:18:22 <samccann> and as we've mentioned - once it gets set, it frequently never gets changed again
15:18:23 <abadger1999> acozine: ++ for "mostly harmless"
15:18:40 <felixfontein> indede :)
15:18:49 <acozine> the more we talk about it, the more I'm leaning toward just letting it go
15:18:59 <samccann> Let it gooooo let it gooooo
15:19:01 <felixfontein> that's why I like bcoca's proposal - it comes with a common explanation text for keywords
15:19:12 * acozine looks at bcoca's proposal
15:19:12 <felixfontein> acozine: me too. at least for now :)
15:19:28 <samccann> so we let it go and people who want it go look at bcoca's proposal and discuss there for a future solution?
15:19:54 <abadger1999> felixfontein: <nod> That's true... that is a good idea.  I specify a small "keyword" into my docs but it gets expanded into something that is large enough so the meaning is unmistakable.
15:20:05 <abadger1999> It's a good idea on how to resolve that.
15:20:54 <samccann> so I can put a comment in the issue that was getting feedback on status to say we'll drop it entirely and go debate on bcoca's proposal instead? ( and see who screams?)
15:20:57 <felixfontein> one question is whether the values should be standardized per collection, or by ansible for everyone
15:21:10 <felixfontein> samccann: sounds good to me
15:21:17 <acozine> samccann: +1
15:22:13 <samccann> #action - samccann to comment on https://github.com/ansible-collections/overview/issues/57 to drop status entirely and ask for feedback on bcoca proposal
15:22:42 <samccann> #link https://github.com/ansible/proposals/issues/68
15:22:45 <gundalow> I vote that it shouldn't exist (and ansible-test should shout if it does exist)
15:23:01 <acozine> I like having specific descriptors of how a module behaves (supports check mode, executes locally/no connection)
15:23:38 <acozine> felixfontein: I'd say those values should be standardized, and if possible verified by tests
15:23:56 <samccann> so we are all agreed that ANSIBLE_METADATA gets dropped entirely, and no immediate replacement for STATUS
15:24:03 <acozine> samccann: yes
15:24:06 <abadger1999> samccann: +1
15:24:07 <samccann> ^^ was a question :-)
15:24:08 <felixfontein> acozine: most of these values are probably impossible to test automatically
15:24:23 <samccann> #agreed ANSIBLE_METADATA gets dropped entirely, and no immediate replacement for STATUS
15:24:25 <acozine> felixfontein: yeah, you're right . . . sigh
15:24:53 <acozine> but they shouldn't be judgment calls - either your module returns facts or it doesn't
15:24:58 <samccann> we are 5 min to the end... should we try for a quick summary of things like changelog status and docs pipeline?
15:25:03 <acozine> that's not a "rating", it's a description
15:25:07 <abadger1999> Someone could use the python rope library to script removing ANSIBLE_METADATA from modules... /me loves doing cleanup work but it tends to interefere with his job performance ;-)
15:25:10 <felixfontein> version_added please!
15:25:15 <acozine> samccann: good lord, how did that happen?
15:25:16 <felixfontein> I've been waiting for that since last week
15:25:27 <felixfontein> (well in fact for several weeks already)
15:25:34 <acozine> #topic version_added
15:25:42 <samccann> ack I need to drop sorry!
15:25:48 <acozine> samccann: no worries
15:25:59 <acozine> thanks for keeping us on the straight and narrow with metadata
15:26:02 <felixfontein> I'd really like version_added to be used (with the collection version) for collections
15:26:16 <felixfontein> so that it is clear from the docs from which collection version on a module/plugin/feature was added
15:26:44 <felixfontein> bye samccann!
15:27:12 <acozine> felixfontein: so for a parameter in a module in a collection, allow the developer to add `version_added: 1.2` where `1.2` is the collection version?
15:27:36 <felixfontein> acozine: right now it can be used in collections, but there are no sanity tests for it
15:28:05 <felixfontein> (it should be `1.2.0` though, 1.2 is not a valid semver)
15:28:10 <acozine> how does the dev know which version of the collection it will be? especially for a collection maintained by multiple devs?
15:28:32 <felixfontein> I guess the same way as for ansible/ansible - it has to be announced somewhere (potentially by galaxy.yml)
15:28:40 <acozine> I believe the current version process is: each commit == a new version
15:29:02 <felixfontein> currently there is no version process
15:29:13 <felixfontein> (unfortunately)
15:29:18 <acozine> in ansible/ansible before, we set the `ansible_version` to "the next release on the roadmap" and then test against that
15:29:24 <acozine> s/test/tested
15:29:27 <felixfontein> exactly
15:29:42 <acozine> felixfontein: yeah, this proposal requires changes to Galaxy
15:29:53 <felixfontein> I mean collections have to decide for themselves how exactly they determine which value to use
15:29:56 <felixfontein> acozine: why?
15:30:15 <acozine> because right now, every time I upload the collection to Galaxy, the version ticks up
15:30:25 <acozine> at least, I believe that is the case
15:30:39 <felixfontein> well, you have to tick up the version manually by updating galaxy.yml
15:30:58 <felixfontein> galaxy only ensures that you don't upload a version you already had another time
15:31:11 <felixfontein> (and maybe that you don't release 2.3.4 after 2.3.5 and things like that)
15:31:29 <acozine> so if you and I are both adding features to community.general, and I add something to a mysql module and re-upload the collection and get 2.3.5
15:31:46 <felixfontein> the collection is only uploaded when it is released
15:31:58 <acozine> ah, is there a process for release?
15:31:59 <felixfontein> only the RM (or a group of RMs) can do that
15:32:03 <felixfontein> no, not yet
15:32:03 <acozine> ah, okay
15:32:13 <felixfontein> but it would be horrible if anyone could trigger a new release
15:32:24 <felixfontein> then we would have version 37843771 in a year ;)
15:32:26 <acozine> yep, that was the madness I was staring in the face
15:32:42 <acozine> also the unpredictability
15:32:58 <felixfontein> every collection should have a release process determined by the collection maintainers
15:33:05 <acozine> will it be 3.4.7, or 3.4.8, or 3.5.0?
15:33:20 <felixfontein> if you increase the patch level, no new features are allowed
15:33:37 <acozine> if we are working toward a process, then it's much more predictable
15:33:37 <felixfontein> so version_added will always be x.y.0
15:33:46 <felixfontein> (if people don't ignore the semver requirement)
15:33:49 <acozine> heh
15:34:27 <acozine> so the main change on the docs side is to use the collection version instead of the ansible/ansible version, right?
15:34:58 <abadger1999> Lacking a process to release, there are no releases.
15:35:02 <acozine> heh
15:35:58 <felixfontein> acozine: I would say so; putting ansible-base or ACD versions there doesn't really make sense
15:36:01 * abadger1999 had a horrid thought...... git commit hook
15:36:10 <acozine> we'd need to remove pre-existing version_added entries, then enforce them for new features against the collection version
15:36:32 <acozine> abadger1999: if you're horrified, I don't even want to know
15:36:35 <felixfontein> acozine: they were already removed (except for return values) during migration
15:36:45 <acozine> felixfontein: fantastic!
15:36:58 <felixfontein> and I've created a PR which adds (optional) version_added validation to ansible-test, same as it is done for ansible/ansible (https://github.com/ansible/ansible/pull/69291)
15:37:10 <acozine> even better!
15:37:29 <felixfontein> acozine: the hard part is re-adding them with the new values for stuff added after 2.9 - I've already preparing that for community.network, community.general and community.crypto
15:37:50 <felixfontein> I'm mainly waiting for a release process to know which version should be put there etc :)
15:38:09 <acozine> sounds great, thank you for all that work!
15:38:14 <felixfontein> and it would be good if the docs meeting could decide that version_added should actually be used for collection version ;)
15:38:32 <acozine> it's the only thing that makes sense
15:38:34 <felixfontein> right now it is "nobody knows, everyone does what they think is best"
15:38:40 <felixfontein> I think so too
15:38:56 <felixfontein> but so far there doesn't seem to be an "official" opinion on this
15:39:05 <acozine> oh, interesting
15:39:35 <felixfontein> (as for a lot of things)
15:39:37 <acozine> I definitely vote for using the collection version as the basis for version_added from here on out
15:40:04 <felixfontein> any other opinions?
15:40:15 <abadger1999> felixfontein: +1
15:40:54 <gundalow> When to increment is one of the things I'm not sure about
15:41:22 <acozine> we'll need to add documentation on "how to tell which versions of which collections you have installed" so those version_added notations are useful
15:41:37 <felixfontein> acozine: `ansible-galaxy list`
15:41:43 <acozine> perfect
15:41:45 <felixfontein> acozine: `ansible-galaxy collection list`
15:41:47 <felixfontein> I think
15:42:04 <acozine> I meant, we'll need to add a paragraph or page about "how to manage your collections versions"
15:42:15 <felixfontein> you get the version for every installed collection, and `*` if you installed a collection from source (i.e. git checkout)
15:42:25 <felixfontein> acozine: that would be useful indeed!
15:42:45 <felixfontein> gundalow: what do you mean? increment which value exactly?
15:42:54 <acozine> gundalow: are you on board with "version_added should refer to the collection version"?
15:42:56 <gundalow> felixfontein: the version
15:43:03 <felixfontein> in galaxy.yml?
15:43:06 <gundalow> acozine: yes
15:43:10 <gundalow> felixfontein: yup
15:43:10 <acozine> excellent!
15:43:31 <felixfontein> I would do it similarly as for ansible/ansible: bump the version as soon as you release, so it mentions the next version to be released
15:43:48 <acozine> #agreed for new features in the module docs, `version_added` should refer to the collection version moving forward
15:43:54 <felixfontein> at least the next major or minor version - patch versions should probably be released from branches
15:44:00 <gundalow> felixfontein: ah, yes, that sounds sensible
15:44:05 <acozine> I have to step away for a short while
15:44:34 <felixfontein> gundalow: thats one reason why I'm asking about releasing/versioning processes for community.general/community.network, because it's tightly coupled with this ;)
15:45:56 <acozine> I'm going to skip the open floor this week
15:46:21 <felixfontein> I guess nobody will complain
15:46:29 <felixfontein> (or hope)
15:46:35 <acozine> but I will be back at my desk shortly and anyone who has a question, concern, comment, or suggestion should post it here, even though the official meeting is over
15:46:38 <acozine> #endmeeting