Agree and Document the format for 'maintainers' in .info files

[yorkshire-pudding]

There have been a number of discussions related to the inclusion of maintainer information in the .info file of contrib projects. https://github.com/backdrop/backdrop-issues/issues/5367#issuecomment-991920866 https://backdrop.zulipchat.com/#narrow/stream/218635-Backdrop/topic/Maintainer.20list.20in.20.2Einfo

On the basis of the latest discussions, I would like to propose that we document the acceptable format:

maintainers[github][gh_username] = Human Readable Name
maintainers[gh_username] = Human Readable Name
maintainers[more] = ""

The maintainers[github][gh_username] = Human Readable Name explicitly defines the location of the username, but assumes with maintainers[gh_username] = Human Readable Name that github is the default.

In theory this allows for other version control/user registration systems, though I can't see how that would work in practice for maintainers. However, if we later decided to include credits then this format would support username sources such as gitlab and drupal

maintainers[more] = "" is a special format to provide a reliable way of identifying where additional maintainers are needed.

Also maintainers[none] = "" is another special format to provide a reliable way of identifying those module with no maintainers.

The information would go here: https://docs.backdropcms.org/creating-modules#info-files

I have tested these formats with backdrop_parse_info_format() and they are successfully parsed and added to the array.

Once agreed and documented what the format should be, we can then follow up with adding into b.org and possibly the project browser and/or the module list.

Is this acceptable?

[klonos]

Thank you for opening this issue @yorkshire-pudding 🙏🏼 ...I'm planning to attend the dev meeting in a few hours, and will bring this up to draw attention to it.

[yorkshire-pudding]

I'm planning to attend the dev meeting in a few hours, and will bring this up to draw attention to it.

@klonos - I think the dev meeting is tomorrow.

[klonos]

It is! I lost track of time 🤦🏼 ...and I'll be on a flight to Greece on Friday, so I'll miss it 😞

[klonos]

...I'll be on a flight to Greece on Friday

I mean "my Friday" (timezones 😅 )

[indigoxela]

Plus one for this idea! :+1: There may be pitfalls or disadvantages, but the current situation's far from ideal, either. IMO a more structured approach would be a real improvement.

[albanycomputers]

Fantastic idea...

We certainly need categories as well, now that the repos are over 1000

[yorkshire-pudding]

We certainly need categories as well, now that the repos are over 1000

@albanycomputers - if so, should probably be a separate ticket. However, I'm not clear what categories would add that can't already be done by tags. A separate issue for the project browser and b.org is how we make use of the tags.

[argiepiano]

Good idea!

[docwilmot]

A note that @bugfolder and I spent a lot of time a few years ago getting the code in to support additional tags and I believe we accomplished quite a bit. See https://github.com/backdrop-ops/backdropcms.org/issues/487. But the next stages would be to expose those tags on b.org and then (or concurrently) to encourage adding tags to modules. I am happy to see this issue rise again!

[stpaultim]

I'm supportive of the idea of specifying the maintainer of a module in the .info file.

I'm a bit confused about the specifics of the proposal.

maintainers[github][gh_username] = Human Readable Name
maintainers[gh_username] = Human Readable Name
maintainers[more] = ""

Can you please provide an example that illustrates the difference between the first two lines and why we need both?

In terms of the maintainers[more], I'm not against this, but also not convinced that it would be that helpful or necessary.

It seems as if 90% of modules are "Seeking co-maintainers." Adding this line to the .info file just doesn't seem all that useful and is just one more piece of clutter.

It seems to me, that the most important piece of information to be included would be the github username for the maintainer. Every maintainer must have a github account to be a maintainer and it's a uniquely identifable string.

Asking for a human readable name is not always helpful, since I've seen people list their name in different ways.

Maintainer: Tim Erickson Maintainer: T Erickson Maintainer: stpaultim (using a common alias that might NOT also be the person's Github username) Maintainer: Timothy Erickson

Github user name would be consistent and predictable.

While we MIGHT assume that a module needs a maintainer if there is none listed, this would not be reliable for legacy projects unless we go back through and update the line for ALL projects.

But, maybe we could just start adding "None" to any project without a maintainer and require the use of a consistent format. Over time, the expectation would be that all modules would eventually have the line "Maintainers[]: " with either a github username or "None." The bug squad could merge PR's to this effect as the projects that need it are identified.

[yorkshire-pudding]

Sorry @stpaultim. My examples weren't clear.

maintainers[github][yorkshire-pudding] = Martin Price
maintainers[stpaultim] = Tim Erickson
maintainers[more] = ""

What we are saying is the human readable name doesn't matter if it varies, the github username is key and would be used for links and for connecting projects to people.

The difference between the first two is one explicitly states the source of the username and one assumes it is github. This was a suggestion from @klonos . I am comfortable either way on this as you are correct that maintainers currently have to be on github, though we don't know whether a change in policy at GitHub could ever force us to look elsewhere. What I said in the original comment was that if we were to extend the info file to include credits then this model could be useful, but that was a theoretical example and I don't know that there is a need for that in info files.

In theory this allows for other repos, though I can't see how that would work in practice for maintainers. However, if we later decided to include credits then this format would support username sources such as gitlab and drupal

I am ambivalent about maintainers[more] = ""; you are right that probably most repos include an invitation for more. For me the critical one is maintainers[none] = "" to provide a reliable way of determining which projects have no maintainer.

[yorkshire-pudding]

A note that @bugfolder and I spent a lot of time a few years ago getting the code in to support additional tags and I believe we accomplished quite a bit. See backdrop-ops/backdropcms.org#487. But the next stages would be to expose those tags on b.org and then (or concurrently) to encourage adding tags to modules. I am happy to see this issue rise again!

@docwilmot - that is much appreciated. I use tags on all my modules. They do seem to have some use in the module list. If you search for a tag and that information isn't elsewhere in the searchable information I think they appear. You can see them when click on more for each project.

I do agree that we could make better use on b.org and in the project browser.

[indigoxela]

Crazy idea, and I hope not to derail anything here: would a maintainers.json file be beneficial? What I mean is: do not put that info in the .info file, but a different file for easier remote parsing (eventually).

Just an idea. Ignore, if too odd. :wink:

[yorkshire-pudding]

The idea was discussed at the dev meeting with @quicksketch and @jenlampton and the principle is supported. The implementation proposal is now:

maintainers[github_username] = Human Readable name
maintainers_wanted = TRUE

or

maintainers_none = TRUE

The thought behind this is to simplify parsing. Also, as we couldn't think of a reason why we might need to have a maintainer without a github username, it was suggested that this (e.g. maintainers[github][github_username] = Human Readable Name)part is shelved for now. Having a single approach will also be easier for people to adopt and therefore hopefully encourage adoption.

Crazy idea, and I hope not to derail anything here: would a maintainers.json file be beneficial? What I mean is: do not put that info in the .info file, but a different file for easier remote parsing (eventually).

Just an idea. Ignore, if too odd. 😉

Interesting idea. Positives

• already structured so easier to parse without backdrop_parse_info_format

Negatives

• less human readable
• structure is less forgiving if someone makes a mistake (e.g. why we tell people it is not a good idea to manually edit config files)
• key information in more than one place

[yorkshire-pudding]

Here is draft text for adding in to the docs:

The following is a sample .info file:

name = Dragon Builder
description = Provides a list of dragons.
backdrop = 1.x
package = Views
tags[] = Development
tags[] = Layouts
type = module
maintainers[dragon_drop] = Dragon Drop
maintainers_wanted = TRUE
dependencies[] = views
dependencies[] = panels
configure = admin/config/content/example

type (Required)

type = module

The type of project. For a module, this will always be "module". Other available types are "theme" or "layout". Although this property is not required to enable the module, it is required to properly package the module on BackdropCMS.org and thus should always be included.

maintainers (Recommended)

maintainers[dragon_drop] = Dragon Drop

Adding the maintainer(s) of the project to the .info file will provide a reliable machine readable way of linking projects to the people responsible for them, providing benefits for maintainers but also for the wider Backdrop community. The maintainers GitHub username must be in the square brackets ([]) and a human readable name must be after the equals sign, though this can be the same if you only want your GitHub username to be used.

If there is no need or desire for other maintainers then that is all that is needed. If you wish to indicate that more maintainers would be welcome add the following line: maintainers_wanted = TRUE

If a project has no registered maintainer then add the following line: maintainers_none = TRUE

These lines will help to reliably populate lists of projects where maintainers are needed or wanted.

stylesheets (Optional)

stylesheets[all][] = node.css

Backdrop allows you to add CSS files in the module's .info file if it should be added on every page, just like theme .info files do. This is an example from the node module's .info file.

Happy to take any improvements. @jenlampton @quicksketch @laryn @indigoxela @docwilmot @albanycomputers @klonos @stpaultim @argiepiano

[yorkshire-pudding]

This is now live at https://docs.backdropcms.org/creating-modules#info-files I created a revision so it is clear.