Requirement: Machine-readable maintainers file in collections

[mariolenz]

Summary

For new collections, the maintainers are documented in collection-meta.yaml. However, this is a manual process. This is not only error-prone, I also fear that changes to the list of maintainers aren't (always) communicated to us so that information can easily get out of date.

Therefor, I wanted to ask what you think about requiering a machine-readable maintainers file in the collections that are part of the community package. This way:

1. we wouldn't have to add the maintainers manually
2. the collections could update the list of maintainers themselves

It would be nice to have a maintainers key in galaxy.yml. But this would mean a change to ansible-core. Alternatively, we could define our own file of maintainers, MAINTAINERS.yml or something.

Thoughts?

Additional Information

See the comments in ansible-community/ansible-build-data#120

[briantist]

I'm fine with this, no particularly strong feelings.

I'm not sure about separate file vs. galaxy.yml. I kind of feel like, if we keep shying away from making relevant changes in core, then we're constantly needing to create new files and workaround it. galaxy.yml feels like the correct place.

Or maybe we should define a single file like community.yml or whatever for things that are community package-related, but don't have any dependency on core?

Really not sure what's best... but implementation details aside I'm +1 on machine-readable maintainers.

[gundalow]

+1 to what this is trying to achive

I'm not sure if galaxy.yml ends up in the final collection. I think it gets rewritten as galaxy.json

I like @briantist's idea of community.yml to avoid more files in the root, maybe we could use the existing meta directory (currently has runtime.yml in), so we'd have meta/community.yml

[mariolenz]

I'm not sure about separate file vs. galaxy.yml. I kind of feel like, if we keep shying away from making relevant changes in core, then we're constantly needing to create new files and workaround it.

Good point.

galaxy.yml feels like the correct place.

For me, too. I just don't know how easy it is to add changes to the galaxy.yml structure in core. But yes, it feels like the best place for documenting the maintainers.

Or maybe we should define a single file like community.yml or whatever for things that are community package-related, but don't have any dependency on core?

Good idea! A MAINTAINERS.yml sounds quite specific. community.yml would be more generic. But since the community package is just ansible-core plus collections, it would be better if we could get all we need from the galaxy.yml without the need for additional files.

[mariolenz]

I'm not sure if galaxy.yml ends up in the final collection. I think it gets rewritten as galaxy.json

But it wouldn't really make a difference if we get the maintainers from galaxy.yml or galaxy.json, would it?

I like @briantist's idea of community.yml to avoid more files in the root, maybe we could use the existing meta directory (currently has runtime.yml in), so we'd have meta/community.yml

Good idea! This would be better than cluttering the root of a collection.

However, at the moment I feel that it might be a good idea to document the maintainers directly in galaxy.yml. It could be generally optional, but mandatory for collections included in the community package.

[briantist]

If we did do a separate file, I also agree I'd like to see it in meta/ and not the root.

[felixfontein]

For me, too. I just don't know how easy it is to add changes to the galaxy.yml structure in core. But yes, it feels like the best place for documenting the maintainers.

I think that'll be pretty hard, since both galaxy.yml and MANIFEST.json have to be adjusted, and this probably also affects Galaxy and Galaxy NG, and maybe even other RH products.

Having meta/community.yml sounds good. One question about it would be who should lint it though. We'll definitely need a linter to avoid chaos :) But having this in ansible-core's ansible-test isn't a good idea (it would be hard to add new things, if you want to lint strictly), and a lint subcommand of antsibull-docs isn't a great place either. Once ansible-lint can do such things it is probably a good place to do that, but I don't know what's its current state.

[mariolenz]

I just don't know how easy it is to add changes to the galaxy.yml structure in core. But yes, it feels like the best place for documenting the maintainers.

I think that'll be pretty hard, since both galaxy.yml and MANIFEST.json have to be adjusted, and this probably also affects Galaxy and Galaxy NG, and maybe even other RH products.

This sounds like any change to galaxy.yml is virtually impossible. Honestly, this looks like an accident waiting to happen...

Having meta/community.yml sounds good. One question about it would be who should lint it though. We'll definitely need a linter to avoid chaos :)

Yes, I've thought about this. But I don't have a solution yet.

But having this in ansible-core's ansible-test isn't a good idea (it would be hard to add new things, if you want to lint strictly)

If we can't get maintainers into galaxy.yml and have to use a community-specific file, I think ansible-test would be the wrong place.

a lint subcommand of antsibull-docs isn't a great place either. Once ansible-lint can do such things it is probably a good place to do that, but I don't know what's its current state.

What about a GitHub workflow, at least to start with? Similar to ansible-community/ansible-build-data#122?

[felixfontein]

a lint subcommand of antsibull-docs isn't a great place either. Once ansible-lint can do such things it is probably a good place to do that, but I don't know what's its current state.

What about a GitHub workflow, at least to start with? Similar to ansible-community/ansible-build-data#122?

I think we want something that the collections themselves can easily run to determine whether they conform, instead of us finding that out only after they made a release with the bad info.

[schurzi]

+1 for the idea.

Regarding file location I would say, that galaxy.yml is the intuitive place from my point of view. Especially since there are already elements for author, repository and issues. These things are semantically connected and placing maintainers in a separate file feels confusing to me.

What about a GitHub workflow, at least to start with? Similar to ansible-community/ansible-build-data#122?

I like that idea too. GitHub has a functionality to include workflows from other repositories (https://docs.github.com/en/actions/using-workflows/reusing-workflows). There are several workflows that come to my mind, which could be supplied by the Ansible community (testing, linting, packaging, ...).

[dmsimard]

Some thoughts and many questions:

re: machine readability, is there tooling that currently use this file ? The only place I can find it right now is briefly in antsibull: https://codesearch.community.eng.ansible.com/?q=collection-meta.yaml

For new collections, the maintainers are documented in collection-meta.yaml. However, this is a manual process. This is not only error-prone, I also fear that changes to the list of maintainers aren't (always) communicated to us so that information can easily get out of date.

I agree.

What kind of information do we want and for what purpose ? Names or usernames ? Emails ?
There's other conventions like CONTRIBUTING.md and CONTRIBUTORS.md but I'm not a fan of manually maintaining a list of contributors or maintainers either, so thinking outside the box a little bit...

Galaxy already knows about source git repositories via galaxy.yml and it has an API -- it's what I used to dynamically retrieve the git repositories of included collections used for the community rss feed (a bit out of date, I should fix that).

Then, we have timestamped git commits (with names and emails attached) of collection repositories with librairies and APIs we can talk to. Would it be reliable enough to take the top 5 (recent) contributor to each collection repository and use that ?
I'm sure there could be cases where a person is "only" a contributor and not a maintainer -- or even an app like zuul or a bot like patchback but it's something ¯\(ツ)/¯

Maybe it could be data available in the collection stats dashboard or dynamically available via antsibull or something ? We can commit any updates to a file in a git repo if need be but I mean to say that it's data that we have and can make available without relying on individual maintainers keeping something up to date somewhere.

Depends on why and what for.

[jborean93]

I'm not sure using galaxy.yml is a good idea for this. Typically it contains the information used to build a collection. We somewhat have a precedence to use meta/... to store metadata about a collection and keep it away from galaxy.yml which is for builting a collection.

[felixfontein]

If the information is only in galaxy.yml and not transferred into MANIFEST.json, we'd have to fetch this information from the git repository (before the collection is built). And not every collection necessarily has a git repo (we also allow other SCMs), and not every collcetion repo has a galaxy.yml (they could be templated or somehow else generated during the build process by some scripts).

What about a GitHub workflow, at least to start with? Similar to ansible-community/ansible-build-data#122?

One big problem with that is that it only works with GitHub, and you cannot run it locally or anywhere else. Linting should not be tied that much to a specific hosting platform.

The upcoming (?) 'profiles' feature of ansible-lint might help here though.

[mariolenz]

If the information is only in galaxy.yml and not transferred into MANIFEST.json, we'd have to fetch this information from the git repository (before the collection is built). And not every collection necessarily has a git repo (we also allow other SCMs)

We did allow other SCMs, but we don't do now: https://github.com/ansible-collections/overview/blob/5c03b3af036c4ea3ce7db22040f5fc99b2e8a77c/collection_requirements.rst#repository-management

[Andersson007]

How about requiring CODEOWNERS file? Moreover, in this case, GitHub will automatically assigned issues/PRs to folks listed in it. It's also supported by gitlab as far as i can see.