15:00:06 <sdoran> #startmeeting Ansible Core Public IRC Meeting
15:00:06 <zodbot> Meeting started Thu Nov 19 15:00:06 2020 UTC.
15:00:06 <zodbot> This meeting is logged and archived in a public location.
15:00:06 <zodbot> The chair is sdoran. Information about MeetBot at http://wiki.debian.org/MeetBot.
15:00:06 <zodbot> Useful Commands: #action #agreed #halp #info #idea #link #topic.
15:00:06 <zodbot> The meeting name has been set to 'ansible_core_public_irc_meeting'
15:00:41 <cyberpear> o/
15:00:46 <mkrizek> \o
15:01:06 <felixfontein> hi!
15:01:32 <sdoran> #chair felixfontein  mkrizek  cyberpear
15:01:32 <zodbot> Current chairs: cyberpear felixfontein mkrizek sdoran
15:01:48 <sdoran> I don't see anything on the agenda for today.
15:01:55 <sivel> hey look, it's meeting time
15:02:03 <sdoran> #chair sivel
15:02:03 <zodbot> Current chairs: cyberpear felixfontein mkrizek sdoran sivel
15:02:37 <sdoran> #topic open floor
15:03:31 <sdoran> Next Thursday is a US holiday so I'm not sure if we will have a meeting.
15:03:48 <sdoran> I'll be out all next week, so I'm not sure if we are still planning on having a meeting on Tuesday or not.
15:04:11 <sdoran> Yey for meetings where we talk about meetings. 😁
15:04:17 <felixfontein> :)
15:04:34 <felixfontein> the community meeting won't happen next week, so I was assuming that the Thursday core meeting would be definitely cancelled
15:04:53 <sivel> I expect the tuesday meeting to also be cancelled
15:05:30 <Shrews> o/
15:05:38 <sdoran> #chair Shrews
15:05:38 <zodbot> Current chairs: Shrews cyberpear felixfontein mkrizek sdoran sivel
15:06:17 <sdoran> #info Due to holidays next week, there will be no IRC meetings.
15:08:54 <sdoran> If we don't have anything of import to discuss, I will end the meeting in two minutes.
15:10:28 <felixfontein> hm
15:10:49 <felixfontein> is there a chance that the role argspec implementation can be changed so that entrypoints are not at top-level of the YAML file?
15:11:45 <sivel> felixfontein: we are discussing it internally right now
15:11:53 <sdoran> #topic entrypoints in the role arg spec
15:11:59 <sivel> so yes there is a chance
15:12:08 <sdoran> felixfontein: I was going to say we have been kicking it around a lot.
15:12:48 <sdoran> I'm not a fan of having to specify `entrypoints:`, but my opinion is subject to change.
15:12:48 <felixfontein> that would be really great!
15:13:17 <felixfontein> having them top-level makes it hard to add top-level information later without resorting to hacks like defining a 'magic' key
15:13:23 <felixfontein> or using another file
15:13:23 <sdoran> Seems superfluous in the `argument_specs.yml` file.
15:13:38 <sdoran> As it stands currently, I think "other" information should go in `metai/main.yml`.
15:13:56 <sdoran> felixfontein: What other top-level information would make sense in the `argument_specs.yml` file?
15:14:11 <felixfontein> sdoran: short_description, description, author, deprecation, version_added
15:14:47 <felixfontein> essentially the top-level information you also have for plugins and modules
15:15:09 <sdoran> `author` should go in `meta/main.yml`. The other fields seem relevant to a particular entry point, not the entire role itself.
15:15:55 <bcoca> in prev iteration we found that any 'common' data to all entry points were really common data to role and would go in meta/main.yml
15:16:29 <felixfontein> how easy it is to extend main.yml? is someone (like galaxy) complaining when you add new data?
15:16:30 <bcoca> or just use yaml anchors, but that required being able to have dummy entries
15:17:28 <felixfontein> for me an entrypoint of a role is a sub-object of the role, so I would expect to be able to have some generic info for the whole role as well
15:17:33 <bcoca> should be easy enough, afaik galaxy only concerns itself with known fields and does not validate unkown ones, this was done early on to allow for both galaxy and ansible to add functions to meta/main.yml w/o stepping over each other
15:17:39 <sivel> felixfontein: unsure, but we are discussing moving it into meta/main.yml
15:17:40 <felixfontein> otherwise why not have two different roles, instead of having differnt entrypoints for one role?
15:17:59 <bcoca> felixfontein: then do that
15:18:12 <bcoca> having the ability does not mean you should be forced to do it that way
15:18:31 <bcoca> for example you have meta/dependencies, but also include/import_role
15:19:16 <sdoran> I still think that anything that would be a top level key adjacent to `entrypoints` in `argument_specs.yml` seems to fit better in `metai/main.yml`. All the top level data points I have seen are about the role itself.
15:19:38 * sdoran would like to eliminate `meta/dependencies`
15:19:47 <bcoca> and 'entry points' is only a thing due to tasks_from
15:19:55 <bcoca> othewirse its all tasks/main.yml
15:20:13 <bcoca> ^ i would even be fine to restricting role spec to main.yml
15:20:21 <bcoca> removes 'entry points'
15:21:50 <bcoca> another proposal in earlier iterations was to have 'matching file names' .. meta/spec/main.yml so it would pick the spec  that matched the tasks/ file
15:25:13 <Shrews> It seems we have 2 view points: 1) this is a documentation feature, and 2) this is a core feature. Current spec is designed around (2), but I don't think that prevents (1) from being expanded on. Does allowing common data to come from `meta/main.yml` meet the needs of docs? Would that common data also need to presented via `ansible-doc`?
15:26:18 <Shrews> If the expectation is that `ansible-doc` would present all of it, then I'm leaning toward everything being in `meta/main.yml`
15:26:30 <bcoca> well, its always been both, once you have a spec/requirement, it has to be documented
15:26:51 <felixfontein> I'd assume that ansible-doc would display all data that's interesting to users (maybe not some galaxy internals), like for plugins and modules
15:26:52 <bcoca> i would avoid overloading meta/main.yml
15:27:47 <bcoca> we alreayd have ansible-galaaxy display 'role info' ... not sure this belongs in ansible-doc
15:30:13 <felixfontein> `ansible-galaxy role info` is not very useful for roles in collections
15:30:50 <sivel> full role documentation is not necessarily a goal for 2.11, so while we may also extend the format, that doesn't necessarily mean ansible-doc will do anything with it
15:32:43 <Shrews> is the expectation that `ansible-doc` would produce all the necessary documentation? or would it go through some other tooling reading the same files?
15:33:19 <bcoca> depends on scope of 'necessary documentation' .. since info already provides a lot of the fields that felix seems to want to add
15:33:19 <felixfontein> Shrews: I would expect it to do so. it also does that for plugins and modules
15:33:42 <bcoca> felixfontein: but does not do for plays and roles .. not even for all plugins
15:34:54 <felixfontein> bcoca: yes, but I guess from a user's perspective, it's better to have one place to show docs for objects, instead of having to choose the correct tool (and in case of `ansible-galaxy role info`, you cannot just pass it a FQCN, you need to find out the directory of the collection first - that can be changed of course)
15:35:05 <bcoca> felixfontein: to get the info that currently a-galaxy role info gets for 'non collection roles' does it mean we need to duplicate functions in ansible-doc or should we 'fix' a-galaxy to be able to also give info/list roles in collections
15:35:24 <bcoca> jinx!
15:35:35 <felixfontein> :)
15:36:12 <felixfontein> that's a very good question. will `ansible-galaxy role info` also show entrypoints and entrypoints option docs?
15:36:45 <bcoca> right now no, im asking does it makes sense to have it there (or a-g role spec <rolename>)
15:36:46 <felixfontein> (will entrypoint argspec actually be available for non-collection roles btw?)
15:37:00 <bcoca> i would say it should work universally
15:37:47 <Shrews> current design is to support non-collection roles
15:37:50 <felixfontein> good question. I've never  really used `ansible-galaxy role ...`, but I'm using ansible-doc a lot, so I'm biased to expect to have ansible-doc also support roles (and playbooks and test and filter plugins ;) )
15:37:50 <sdoran> Yes.
15:41:46 <sdoran> `ansible-galaxy` without a subcommand defaults to `ansible-galaxy role`.
15:42:09 <sdoran> It was written when roles were the only thing to deal with really.
15:42:21 <sdoran> But now that collections are a thing, we have both `role` and `collection` subcommands.
15:42:43 <sdoran> It's better to always be specific. I'm not sure when/if we plan to deprecate and remote the implicit `role` behavior.
15:43:06 <felixfontein> I know, I also didn't really use `ansible-galaxy ...` when collections weren't a thing
15:43:11 <Shrews> and i don't see us modifying the `ansible-galaxy role info` output. you want complete role docs, use `ansible-doc`
15:43:27 <felixfontein> Shrews: that would argue for 'show all info in ansible-doc'
15:44:13 <Shrews> felixfontein: yes. my earlier question was trying to ascertain the main interaction point from a docs perspective. looks like it's the tool, not the spec files
15:44:17 <bcoca> Shrews it becomes 'murky' imho when you have to use ansible-galaxy to list roles and get 'some docs' but rest of docs elswhere
15:44:44 <bcoca> while ansible-doc you can list and see docs for modules
15:44:47 <felixfontein> geerlingguy: if you're around, maybe you have an opinion here since you work with roles a lot
15:45:00 <bcoca> either we add 'all abilities' to ansible-doc or i think we should try to keep it congruent in a-g
15:45:18 <Shrews> felixfontein: i seem to recall from the previous #ansible-docs meeting someone mentioning running the yaml file through some external doc tool, so that's why i asked
15:45:20 <sdoran> `ansible-galaxy role info` does something different. I'm pretty sure that tries to query the Galaxy API and falls back to local info.
15:45:43 <bcoca> sdoran: does both, uses local info and uses galaxy for additional
15:46:15 <sdoran> Ok. I couldn't remember exactly.
15:46:42 <bcoca> but also compare `asnible-doc -t module -l` and `ansible-galaxy  role list`
15:47:01 <bcoca> how would you 'find a role to get spec for?'
15:47:09 <bcoca> thikn of the full user experience
15:47:11 <felixfontein> Shrews: does your PR adds role listing to ansible-doc? (at least roles with argspec)?
15:47:33 <Shrews> felixfontein: yes. any normal role or collection role with an arg spec is listed
15:48:22 <bcoca> what about roles w/o ?
15:48:30 <Shrews> `ansible-doc -t role -l`
15:48:55 <Shrews> bcoca: ignored, atm
15:49:41 <felixfontein> I guess it makes sense to also mention non-argspec-roles once some non-argspec information is shown in the ansible-doc output
15:51:13 <bcoca> Shrews: that seems like a bug in -l
15:52:46 <Shrews> bcoca: it's a feature. not going to display docs for roles w/o docs. but that can be adjusted a bit better with some better tooling to actually enumerate all found roles.
15:53:01 <Shrews> (which is something nitzmahone and myself discussed)
15:53:09 <bcoca> well, for your definition of 'docs' which is restricted to arg spec, roles already have other docs, in info
15:53:33 <Shrews> ok, s/docs/argspec/
15:53:34 <bcoca> users wont see that distinction
15:53:52 <sdoran> Right. We probably should include all roles in `ansible-doc role -l` using info from `meta/main.yml`.
15:53:55 <bcoca> ^ which is probalby what is fueling felixfontein's point of adding 'docs to spec'
15:54:08 <sdoran> But I figured we would get to that after the initial PR was merged.
15:54:34 <bcoca> im fine with taht, but we should at least have a direction that makes sense to the user in the end
15:55:22 <bcoca> the pr was fine in itself, but at review i had also assumed that there was purposful shift to asnible-doc for role listing/docs , didnt think it  was going to be left to have incomplete data on each tool/view
15:55:52 <geerlingguy> felixfontein: it would be nice if ansible-doc were able to show role docs. to limit scope, I would imagine it could just do roles-in-collections
15:56:00 <geerlingguy> so kind of a carrot to lead people to start using roles-in-collections
15:56:08 <bcoca> also users will be confused 'why does ansible-galaxy list N roles but ansible-doc list M and they and many dont show up in the other'
15:56:17 <felixfontein> geerlingguy: it looks like either it supports both, or none :)
15:56:42 <geerlingguy> then I'd go for both, unless we just want to say that modules/plugins and roles exist on two different planes of reality
15:56:55 <geerlingguy> which in the collections world at least, they do right now
15:56:56 <bcoca> ` ansible-doc -t role -l` <= 1 role (i just added argspec)
15:57:34 <felixfontein> bcoca: same here ;)
15:57:43 <bcoca> ansible-galaxy role list <= 5 roles, including the one with argspec, but im not using roles in collection
15:57:48 <felixfontein> I haven't figured out how to get `ansible-galaxy role list` to actually list roles though
15:57:52 <bcoca> if i were, this would start getting really confusing
15:58:04 <bcoca> felixfontein: install role normally
15:58:16 <bcoca> ansigle-galaxy install geerlinguy.apache
15:58:56 <felixfontein> bcoca: it errors out on me that I should add --roles-path. if I do that, it works, but it feels clumsy
15:59:12 <felixfontein> (I only have roles in collections, and roles in roles/ next to playbooks)
16:00:17 <bcoca> i have a 'writeable' /etc/ansible/roles so probalby why it works for me off the bat
16:00:35 <Shrews> felixfontein: `--roles-path` is not required so that shouldn't error out. if you use `--playbook-dir`, it will find playbook adjacent roles
16:00:48 <sdoran> We have reached the top of the hour. Time to wrap up the meeting.
16:01:01 <sdoran> We can continue this discussion in #ansible-devel.
16:01:09 <sdoran> Thank you everyone for attending and for the good discussion.
16:01:18 <sdoran> Just a reminder: no meetings next week.
16:01:19 <sdoran> #endmeeting