[META] Support more data in projects' *.info files

[docwilmot]

This has been raised over several different issues here and there and its always a pain to find. This is to collate all the recommendations (and my ideas). Needed for #95 and project browser.

TODO list for things to add to info files:

• Source URL
• Support URL
• Documentation URL
• Recommends / suggests / supports ?
• colors (see Support a little more data in .info files #487)
• tags (see Support a little more data in .info files #487)
• screenshots (see Support a little more data in .info files #487)
• maintainers (see Support a little more data in .info files #487)

More info in .info files!:

**// Where the repo lives**
source = url

**// Where the support and docs can be found**
support = url
documentation = url

**// Theme screenshots (maybe modules and layouts too?)**
screenshots[] = screenshots/projectname_1.jpg
screenshots[] = screenshots/projectname_2.jpg
screenshots[] = screenshots/projectname_big.jpg
screenshots[] = screenshots/imgname_whatever.jpg

**// Categories (eventually could replace "packages")**
tags[] = media
tags[] = fields
tags[] = user-interface
tags[] = full-width (for themes)
tags[] = 960px (for themes)

**// Maintainers**
maintainers[] = @mrxxxxxx
maintainers[] = @mryyyyyyy

**// Theme colors**
colors[] = greenish
colors[] = red

**// Recommended**
recommends[] = i18n
recommends[] = l10n

I'm thinking that starting to encourage this in project info files would only be of benefit, as it would in no way affect Backdrop core, and provides useful data for building BackdropCMS.org project pages and collating stats.

[klonos]

👍 to the whole lot!

...just singular instead of plural for consistency. So tag[] = ... and maintainer[] = ...

[quicksketch]

...just singular instead of plural for consistency. So tag[] = ... and maintainer[] = ...

We do already have dependencies[] = however.

Regarding maintainers, would we want to use exclusively GitHub usernames? It's tying us into a particular provider (even more than already). Although single sign-on with GitHub is planned for BackdropCMS.org, I don't think we can really guarantee BackdropCMS.org user names match GitHub user names.

[klonos]

We do already have dependencies[] = however.

Maybe then that needs to change too 😛 ...point is choose one: either singular or plural and be consistent about it.

Regarding maintainers, would we want to use exclusively GitHub usernames?

We could allow emails or website URLs too I guess. These have the advantage that they are not tied to a specific protocol/site.

[klonos]

...or have it as maintainer[] = email:[email protected], maintainer[] = github:@someone, maintainer[] = url:www.somesite.com, maintainer[] = backdrop:someusername etc.

[docwilmot]

...or have it as maintainer[] = email:[email protected], maintainer[] = github:@Someone, maintainer[] = url:www.somesite.com, maintainer[] = backdrop:someusername etc.

That sounds reasonable.

More curious though, when can we start this? I'm just thinking that I could put this in all my contrib modules/themes/layouts right now and core wouldnt be any wiser; so no API change, no problem, how can we get this done?

[klonos]

Yeah, I think we are ok with starting to implement straight away. Additions will simply be ignored - no errors. When core "gets wiser", it will know what to do with these lines. But it would be good to get some sort of official approval to go forth with this + draft a guide (or add to any existing one) that lists which properties are currently supported in .info files and explanation/examples of their usage.

[klonos]

...we don't have an equivalent of https://www.drupal.org/developing/modules/7 or Writing module .info files (Drupal 7.x) that breaks down supported properties and states which are required and which are optional but good practice. Do we?

[quicksketch]

Writing module .info files (Drupal 7.x) that breaks down supported properties and states which are required and which are optional but good practice.

There is a section on .info files at https://api.backdropcms.org/modules.

[docwilmot]

At this stage, this would be a bit useless, unless it was actually being used by BackdropCMS and its Project Module. Project release nodes there would need fields corresponding to these tags to be able pull these tags into Project Browser module or the Project display pages. So its in the hands of @quicksketch.

[jenlampton]

...just singular instead of plural for consistency. So tag[] = ... and maintainer[] = ...

These things are arrays (see the [] ?) because they can take multiple values. They should be plural. That means colors[] not color.

Things that take a singular value should be singular, type = module, and source = url, etc.

Otherwise, I like this :) 👍 good work all!

[sentaidigital]

Quoting myself from backdrop/backdrop-issues#37:

In particular, I'd like to see "suggests" and "supports" module tags in the info files.

"Suggests" would note other modules that greatly enhance the usability of this one, but isn't strictly speaking required. For example, Better Select converts standard select boxes to checkboxes, and would include "suggests[] = checkall" in the info file.

"Supports" would be for modules that provide enhancements to other modules. For example, if a PayPal module included a hook_views_data() to make the PayPal transaction data available to Views, it would say "supports[] = views". Again, Views is not required for this module to work.

@docwilmot put "recommended" on his list, which is fine instead of "suggests". Actually, it's better. The shape of Supports and Suggests are too close to each other. (Google "reading word shape" for why.) "Recommends" will be easier to find quickly.

[Gormartsen]

@docwilmot I did a research on the code side. First moment is that on backdropcms.org we still run old project module or repo does not represent actual state of the website. It is matter, because new version work over hook_githubapi_payload() instead of handling Github web hook by itself.

hook_githubapi_payload() allow you to act on push, release and other events.

Project module do next stuff:

• On push it update readme inside project node
• on release - check release to match guidance and upload properly created release zip file

So if you want to handle extra tags and assign them to Node the best place to do so is here:

https://github.com/backdrop-contrib/project/blob/11f6d9d98a791c0f891dd8141bee50dfb0257bfd/project_github/project_github.pages.inc#L304

If updating project module is not accepted, another way is create module to handle hook_githubapi_payload and update project node with data when release happen for example.

[docwilmot]

Thanks @Gormartsen. As I suspected, I don't think this is something I can do myself. But good to know how it could be done.

[Gormartsen]

There is extra info about it. You can read log here: https://gitter.im/backdrop/backdrop-issues/archives/2016/05/26 I gave extra explanation how to implement it.

If somebody decide to code it, basically you need next skills:

how to create (and delete - on module uninstall phase) programatically field and attach it to node
how to update node programatically to save new field values
how to get info file from github and parse it (copypaste from readme … almost. few changes )

[docwilmot]

thanks @Gormartsen. I probably won't be looking at this any time soon, but good to have the log.

[docwilmot]

I think our project list is now large enough to need categorization. I just tried finding an ecommerce module; Paypal doesnt show up when you search "commerce", and Simple Cart doesnt show if you search "paypal".

[jenlampton]

@docwilmot I have added the first few project fields in #487, and turned this issue into a meta. As you recommended all the new fields are hidden for now.