Proposal: Replace MAINTAINERS.md with maintainers.yaml

[ermo]

To increase the ability to trivially parse and generate reports about package maintainers, I propose that we rewrite the current MAINTAINERS.md file to maintainers.yaml. YAML enables us to use all programming languages with a YAML parser to parse and generate reports on the state of maintainership in the recipe tree.

The format I came up with looks like this and relies on so-called "yaml records":

maintainers:
- Troy Harvey:
  email: [email protected]
  matrix: ~
  active: true
- A. WOL.:
  email: ~
  matrix: ~
  active: false
description: |
This file is used to indicate primary maintainership for this package. A package may list more than one maintainer to
avoid bus factor issues. People on this list may be considered “subject-matter experts”.

Please note that Solus staff may need to perform necessary rebuilds, upgrades, or security fixes as part of the normal
maintenance of the Solus package repository. 

If you believe this package requires an update, follow documentation from:

https://help.getsol.us/docs/packaging/procedures/request-a-package-update

In the event that this package becomes insufficiently maintained, the Solus staff reserves the right to request a new
maintainer, or deprecate and remove this package from the repository entirely.

I've added the active: key as a suggestion, so we have a way to gauge the effect of offboarding a maintainer and a way to enable maintainers to take a temporary leave of absence.

Thoughts welcome.

[ermo]

@davidjharder Assigning this to you so you can keep us on our toes re. helping to suss out our maintainer policies and how to monitor the state of the repo. Justin may have an idea or two here re. his package status PoC?

[TraceyC77]

@Justinzobel - ping since ermo said you might have an idea regarding this

[ermo]

Harvey has a sed script PoC that can help do the MAINTAINERS.md conversion to maintainers.yaml:

https://gist.githubusercontent.com/HarveyDevel/8dacdf12cbf62e1d6c35921d18e5efb3/raw/bdddcd431ff8ec5588d35ff5bc0f4c1a62251952/convert2yaml.sh

[davidjharder]

Thoughts:

• Include github handle
• Order matrix, GH handle, email in the order we expect people to use them
• All explanatory word salad should be replaced with a link to the help center. This avoids the mass commits to change wordings

[Justinzobel]

I would probably put Matrix handle first as reports about packages should be on the packages repo on GitHub. In Matrix they can easily get lost/forgotten.

[silkeh]

I like having a machine-readable format. However, I would prefer that we integrate with CODEOWNERS, as that has additional benefits in terms of automatic pings and PR review requests, approvals, etc.

Counter proposal:

• Have a .github/CODEOWNERS file that contains the maintainers for packages by their GitHub handle, eg:

  # This file is used to indicate primary maintainership for packages. 
  # A package may list more than one maintainer to avoid bus factor issues.
  # People on this list may be considered “subject-matter experts”.
  # Please note that Solus staff may need to perform necessary rebuilds, upgrades, or security fixes as part of the normal maintenance of the Solus package repository. 
  # If you believe a package requires an update, follow documentation from: https://help.getsol.us/docs/packaging/procedures/request-a-package-update
  # In the event that this package becomes insufficiently maintained, the Solus staff reserves the right to request a new maintainer, or deprecate and remove this package from the repository entirely.
  packages/e/example/ @silkeh 
  

• Have a common/maintainers.yaml that provides a mapping of GitHub user names to contact details. For example:

  # This file contains the contact information for all maintainers.
  # It ties in with the `.github/CODEOWNERS` file, which indicates 
  ---
  @silkeh :
    name: Silke Hofstra
    email: [email protected]
    matrix: ~
    active: true
  @<awol>:
    name: A. WOL.
    email: ~
    matrix: ~
    active: false
  

[Staudey]

@silkeh I like this idea. Gives the maintainership concept some actual teeth. Would also make it easy to e.g. deactivate/remove inactive maintainers without having a script/tool scan the whole repo.

[Justinzobel]

It's then tied to Github, so if move to another platform in the future it's not going to work. Platform agnostic code/processes ftw. Just my 2c anyway.

[Staudey]

Should be easy enough to move stuff to something else should it ever become necessary since it's all in one place. One can easily imagine a script / commit hook checking these files even if GitHub functionality were no longer available/preferable.

[Staudey]

Also at least Gitlab also supports a CODEOWNERS file; unsure about other platforms

https://docs.gitlab.com/ee/user/project/codeowners/#codeowners-file

[davidjharder]

One downside: There can only be one Codeowners file for the repo. When looking at files for a given package, you can't tell who the owner is without: 1) consulting the Codeowners file several layers up, or 2) Using some sort of interface like the Github website or an IDE

[Staudey]

True. There could be a go-task function to print maintainer information though and/or pre-commit hooks telling you about the maintainer situation

Honestly I also often overlook the current MAINTAINERS.md files because I'm only navigating the package folder in the terminal

[silkeh]

It's then tied to Github, so if move to another platform in the future it's not going to work. Platform agnostic code/processes ftw.

While I agree that platform-agnostic code is better in general, I don't think it's worth building our own CODEOWNERS equivalent when we can leverage the one on Github.

Seeing as the codeowners concept is not exclusive to Github, a compromise would be to create a master common/codeowners.yaml that then generates the file for GitHub and whatever other platform we would want (and CI enforces it to be in sync).

However, I don't think that's useful unless we're going to also make this repo available on a different Git hosting platform and work in sync on both platforms at the same time. I think a transition should be easy to script otherwise.

Also at least Gitlab also supports a CODEOWNERS file; unsure about other platforms

Gitea also supports the concept, and I think Forgejo does so as well. Making this more agnostic would require fields for usernames for other platforms though, eg:

- name: Silke Hofstra
  email: [email protected]
  github: silkeh
  gitlab: silkeh
  matrix: ~
  active: true

True. There could be a go-task function to print maintainer information though and/or pre-commit hooks telling you about the maintainer situation

Yes! I think we can check if the Git email matches a maintainer and show a warning otherwise, and go-task maintainers could list the maintainer info.

Honestly I also often overlook the current MAINTAINERS.md files because I'm only navigating the package folder in the terminal

Same :sweat_smile:

[Justinzobel]

While I agree that platform-agnostic code is better in general, I don't think it's worth building our own CODEOWNERS equivalent when we can leverage the one on Github.

We already have this, it's https://github.com/getsolus/packages/blob/main/packages/n/network-manager/MAINTAINERS.md

Either way I am not really fussed overall about the maintainers situation. If it auto tagged people in commits that affect their code that will be nice. Otherwise it's just another form of documentation for users to ignore :D