[go: nahoru, domu]

Page MenuHomePhabricator

Merge new fields in extension.json into Composer's composer.json
Open, LowPublic

Description

Developers have already been using Composer's composer.json to enable composer to install their packages. This has worked relatively well. There is the problem of end users without shell access, but I hope that tools like NoConsoleComposer can address this.

The recent work on extension registration requires extensions to have another json file: extension.json. The problems this introduces have been discussed on wikitech-l.

Composer should be enhanced to understand the information that extension.json provides so that developers only have to maintain a single .json file.

Event Timeline

MarkAHershberger raised the priority of this task from to Needs Triage.
MarkAHershberger updated the task description. (Show Details)
Legoktm renamed this task from Merge new fields in extension.json into Composer's package.json to Merge new fields in extension.json into Composer's composer.json.Feb 16 2015, 5:37 PM
Legoktm updated the task description. (Show Details)
Legoktm set Security to None.

This tasks feels premature and is only going to fragment discussion yet again. AIUI, werdna's complaint on wikitech-l was about poor communication about things moving (which I agree with and take responsibility for), rather than problems with introducing a separate json file.

I'm confused as to what you mean when you say "fragment discussion yet again."

I've heard from other extension developers who have already worked to incorporate composer.json into their extensions that they really don't want to have to maintain two of these files with some duplicated information.

I don't think it is premature to say we need to avoid reinventing the wheel when a version of MW incorporating the "new, improved" wheel hasn't been released.

We can avoid creating a proprietary MW extension.json file and work to adapt existing tools to our needs.

I'm confused as to what you mean when you say "fragment discussion yet again."

I think @Legoktm is rightly pointing out that there is discussion of this very topic on going on his Improving extension management RFC. As a matter of fact this task seems to be pretty directly related to your comments at on the Talk page there. I think that discussion of this is healthy and welcome but having yet another place to hold the same discussion seems unlikely to lead to productive integration of the opposing viewpoints.

I think that discussion of this is healthy and welcome but having yet another place to hold the same discussion seems unlikely to lead to productive integration of the opposing viewpoints.

Got it.

Would you agree that this task could be something we might decide we want done after the discussion there has come to a conclusion?

If so we could table this until that RFC has come to a conclusion.

Would you agree that this task could be something we might decide we want done after the discussion there has come to a conclusion?

Unification of MediaWiki's needs for extension registration and the end user's needs for package acquisition could be an outcome. Or the outcome could be just as likely that the amount of duplication in these two concerns is different enough that unification is not recommended. I really think its too soon to jump in either direction as anything other than a proof of concept or strawman proposal.

This seems deeply misguided to me. Composer is a library management tool; composer.json deals with data related to that, such as repository location, library dependencies, post-install scripts, autoloader generation. It is largely application-agnostic; its knowledge about MediaWiki is limited to "this script needs to be run after a new library was installed"; it is needed to install extensions but not needed to run them. extension.json, on the other hand, deals with extension configuration (or, if you like, extension capability discovery); it is entirely MediaWiki-specific; it is not interesting for the installation process but needed for running the code. These are orthogonal concerns; coupling them would be a poor architectural decision.

You are basically arguing for <ExtensionName>.php to be migrated into composer.json. That does not make any sense whatsoever.

At least: name, description, homepage, author and license should not be duplicated between the two.

At least: name, description, homepage, author and license should not be duplicated between the two.

Description and name in extension.json is currently i18ned through the extension's i18n JSON files. And gets the full support of TWN.

If we are to merge the two it's going to have to be composer's method of defining them that gets compromised. Dropping i18n support in extension metadata just so we don't have to duplicate name and description would be unacceptable.

At least: name, description, homepage, author and license should not be duplicated between the two.

Description and name in extension.json is currently i18ned through the extension's i18n JSON files. And gets the full support of TWN.

If we are to merge the two it's going to have to be composer's method of defining them that gets compromised. Dropping i18n support in extension metadata just so we don't have to duplicate name and description would be unacceptable.

Of course I'm in favor of i18n, composer's method is redundant.

Of course I'm in favor of i18n, composer's method is redundant.

Composer's method is used by Composer (or more specifically Packagist) to display author etc. data in package listings. MediaWiki's method is used by MediaWiki to display author etc. data in Special:Version. In no way are they redundant. Let's not go into http://xkcd.com/927/ territory.

Just for the record, I don't really mind whether an extension contains an extension.json or not as long no one force me to introduce yet another MW dependency (meaning to require a extension.json then I'm certainly against it).

I came to the conclusion that for the repositories I'm involved extension.json brings no benefit nor does maintaining information in two files (composer.json and extension.json) is time well spent. For us composer.json has functional relevance but extension.json has not therefore I can't see any motivation to actually maintain such a file.

I came to the conclusion that for the repositories I'm involved extension.json brings no benefit nor does maintaining information in two files (composer.json and extension.json) is time well spent. For us composer.json has functional relevance but extension.json has not therefore I can't see any motivation to actually maintain such a file.

But you'll maintain that same information in ExtensionName.php?

A point of extension.json was supposed be to replacing some of the stuff in ExtensionName.php (like the extension credits) with a non-php file that can be safely read without executing PHP.

Though I do admit it needs something like the maintenance script and boilerplate we had for the JSON i18n conversion that provided older versions of MW with access to the data without duplicating it.

Though I do admit it needs something like the maintenance script and boilerplate we had for the JSON i18n conversion that provided older versions of MW with access to the data without duplicating it.

See https://www.mediawiki.org/wiki/Manual:Extension_registration#Migrating

From the improving extension management RFC meeting, we have these items:

  • adding compatability data to extension.json: probably fine (TimStarling, 21:33:17)
  • on having our own extension update system which uses composer classes -- I think we have consensus (TimStarling, 21:34:17)
  • use composer for lib dependencies. use bryan's merge-dependencies thingy or something similar. (DanielK_WMDE_, 21:35:16)
  • on dependencies between extensions -- I don't think there is consensus on whether to specify those dependencies in extension.json or composer.json (TimStarling, 21:36:55)

There was some discussion during the meeting about being able to refer to composer.json from extension.json if it contains the information already in order to reduce duplication.

Tim's final note above makes it look like there is no resolution for this task.

I would suggest that we fall back to reading composer.json if it exists and an extension.json does not exist. This would allow us to gather basic author and name information for display on Special:Version.

There was some discussion during the meeting about being able to refer to composer.json from extension.json if it contains the information already in order to reduce duplication.

I would suggest that we fall back to reading composer.json if it exists and an extension.json does not exist. This would allow us to gather basic author and name information for display on Special:Version.

First note,
Could someone go over what data they think should be referable from composer?
No-one seems to have bothered to say what they think should be read from composer. So when someone comes up with a reason some property from composer.json shouldn't be read it just gets lost in the murkiness and seems to be conveniently ignored.

From what I've seen so far the scope of what could be referred to is actually pretty narrow.

  • license-name/license would make sense of course.
  • name doesn't make sense, extension.json's "name" and "namemsg" is different and completely unrelated to composer.json's "name" ("Semantic MediaWiki" with recent support for i18n vs. "mediawiki/semantic-media-wiki").
  • description is very questionable.
    • Firstly, referencing it from composer means breaking i18n support for descriptions on Special:Version
    • I remember someone has pointed out that "description" in Extensions and Composer are not actually the same thing, they have different purposes/meanings.
      • This appears to be true in practice. Semantic MediaWiki's composer.json description is very different than the extension description in i18n and can not nor should be combined.
      • In composer the description is a simple string that describes a composer package to the composer ecosystem. Naturally you'd describe it as a MediaWiki extension.
      • In MediaWiki the description is a string supporting WikiText (simple styles like bold, italics, and linking may be used) and is describing extension to someone in the MediaWiki ecosystem. Describing it as an extension is unnecessary and unwelcome and you may want to go into more detail than you would in composer.
  • authors and url/homepage are probably the only other one that makes sense.

Second note,
Every extension we have already exposes name and description, nearly every one of them supporting description i18n. Even if an extension.json doesn't exist this data is in fact already present for basically every extension.
And the directory name makes a better name for an extension than the composer.json name.

So while I might support falling back to reading author, license, and homepage from composer.json. I would like to oppose any fallback at all to composer.json for name and description data.

DanielFriesen writes:

Could someone go over what data they think should be referable from
composer?

I think you did a good job of this. Thanks, especially, for identifying
why description might not work. I suggest that we talk to the SMW devs
about that one.

So while I might support falling back to reading author, license, and
homepage from composer.json. I would like to oppose any fallback at
all to composer.json for name and description data.

I agree with the caveat that I think there may be a way to compromise on
description.

Does anyone else have any input?

I think you did a good job of this. Thanks, especially, for identifying
why description might not work. I suggest that we talk to the SMW devs
about that one.
...
I agree with the caveat that I think there may be a way to compromise on
description.

Since I already had a database listing the name of every extension that uses composer, I played around in the node repl and managed to generate this report of extension descriptions and composer descriptions.
https://www.mediawiki.org/wiki/User:Dantman/Extension_composer_descriptions

The difference doesn't appear to be a SMW specific thing. There are a few extensions there that say different because of minor formatting or some desync between the descriptions. But the mass majority of composer extensions still use a completely different description for each. And where an extension does have issues keeping the two in sync I actually think it would be better to encourage them to just make them completely different and fit the context.

Another note on something I noticed,
https://getcomposer.org/doc/02-libraries.md#specifying-the-version

Composer recommends against specifying a "version" in composer.json when you're using a VCS. Instead it gets that information from tags, etc...

So that's another property that is probably best left in extension.json.

Whatever we decide, note for Documentation: Manual:Extension registration and Manual:Composer.json mention the overlap.

In T89456#1042198, @Tgr wrote:

Of course I'm in favor of i18n, composer's method is redundant.

Composer's method is used by Composer (or more specifically Packagist) to display author etc. data in package listings. MediaWiki's method is used by MediaWiki to display author etc. data in Special:Version. In no way are they redundant. Let's not go into http://xkcd.com/927/ territory.

Of course they can't be deduplicated right now, but some of them (except for name and description, as @DanielFriesen pointed out) are actually redundant between the two .json files.

Of course they can't be deduplicated right now, but some of them (except for name and description, as @DanielFriesen pointed out) are actually redundant between the two .json files.

To be specific. According to my analysis the only redundant properties are "authors", "url"/"homepage", and "license-name"/"license(s)".

Note that in the case of licenses our license-name may need an upgrade.

"name" and "description" are not redundant, "version" should not be specifies in composer,json, and the only other properties I can remember are specific to either extension.json or composer.json.

Of course they can't be deduplicated right now, but some of them (except for name and description, as @DanielFriesen pointed out) are actually redundant between the two .json files.

To be specific. According to my analysis the only redundant properties are "authors", "url"/"homepage", and "license-name"/"license(s)".

Note that in the case of licenses our license-name may need an upgrade.

What do you mean? Both 'schemas' use SPDX codes:

Note that in the case of licenses our license-name may need an upgrade.

What do you mean? Both 'schemas' use SPDX codes:

Multi-licensing. I didn't hear anything about the code that reads "license-name" from extension.json/ExtensionCredits handling an array of license names like composer.json permits. So it and our license display code might need an upgrade to accept license from composer.json without breaking should someone use a perfectly valid array of license names in their composer.json.

Note that in the case of licenses our license-name may need an upgrade.

What do you mean? Both 'schemas' use SPDX codes:

Multi-licensing. I didn't hear anything about the code that reads "license-name" from extension.json/ExtensionCredits handling an array of license names like composer.json permits. So it and our license display code might need an upgrade to accept license from composer.json without breaking should someone use a perfectly valid array of license names in their composer.json.

Supporting arrays for "license-name" sounds easy. Do we have a task for that?

Multi-licensing. I didn't hear anything about the code that reads "license-name" from extension.json/ExtensionCredits handling an array of license names like composer.json permits. So it and our license display code might need an upgrade to accept license from composer.json without breaking should someone use a perfectly valid array of license names in their composer.json.

Supporting arrays for "license-name" sounds easy. Do we have a task for that?

Or we could use SPDX expressions, also supported by npm: