Page MenuHomePhabricator

Allow comments in the extension.json and skin.json files
Closed, DeclinedPublic

Description

Hi could there be some sort of support for comments in the extension.json and skin.json files without causing problems like you can in the .jshintrc file which is a json file but can do comments. Please see https://gerrit.wikimedia.org/r/#/c/209882/

There should also be a global specification on what a wiki developer should do.

Should they put the comments in the json file or should they put them in the README file or should they have them on the mw page.

It is causing patches to sit for a long time because a developer doesent know what to do.

Event Timeline

Paladox created this task.Aug 7 2015, 2:55 PM
Paladox raised the priority of this task from to Needs Triage.
Paladox updated the task description. (Show Details)
Paladox added subscribers: Paladox, Legoktm, Florian, Jdlrobson.
Restricted Application added a subscriber: Aklapper. · View Herald TranscriptAug 7 2015, 2:55 PM
Paladox set Security to None.Aug 7 2015, 2:56 PM
Paladox added a subscriber: kaldari.

You can use a @ at the begin of a string to indicate a comment.

See Vector/skin.json for an example:

	"@note": "When ...",

(Note that it only works on top level, you can't put comments like this in nested objects, only at the top.)

matmarex removed a subscriber: matmarex.Aug 7 2015, 3:03 PM

But big comments with example woulden look nice and would make it a big line.

Comments can also be placed in "config".

Ok. could someone create a global specific for people to follow since there seems to be several places you can put comments but people doint know since there isent any global specific.

Where do you recommend we put the comments in. Do we do it in a readme file or do we do it in extension.json.

Can't we just pipe it through jsmin to remove comments or something?
Why are we discouraging inline documentation in the json file itself?
Douglas himself says this is acceptable:
https://plus.google.com/+DouglasCrockfordEsq/posts/RK8qyGVaGSr

It would solve a lot of problems that people are currently having like where should they put it.

Paladox triaged this task as High priority.Aug 12 2015, 11:24 PM

Putting it as high because this task blocks all task on here that want to convert to extension.json or skin.json.

Where do you recommend we put the comments in. Do we do it in a readme file or do we do it in extension.json.

I wrote down my recommendation on wiki a long time ago: https://www.mediawiki.org/wiki/Manual:Extension_registration#Retaining_documentation
I prefer using a README/on-wiki but people don't like that for whatever reason, so we introduced the @ trick in the JSON file itself.

Can't we just pipe it through jsmin to remove comments or something?

It's already been implemented, we're just not using it: rMW8fea9c619d07: FormatJson::stripComments.

Why are we discouraging inline documentation in the json file itself?

We're not.

Douglas himself says this is acceptable:
https://plus.google.com/+DouglasCrockfordEsq/posts/RK8qyGVaGSr

As I've said elsewhere, the great part about JSON is that you can read it in just about any language, without needing external dependencies. Deviating from the JSON spec causes interoperability issues (e.g. trailing comma issues we had in ConfirmEdit). Here's an actual example where this causes problems:

In various extensions, we read the extension.json file in Gruntfile.js to pass the message directories to grunt-banana-checker instead of hardcoding and duplicating the configuration (which has caused problems in the past when they get out of sync). If we were to introduce comments, we wouldn't be able to use grunt.file.readJSON. Tools like the proposed tardist service would similarly need to implement their own JSON parser instead of being able to use the native library.

Ok thanks. So it recommends the README file.

Is it really impossible for us to keep README files up to date? We manage to keep the RELEASE NOTES up to date pretty well. Personally, I find reading comments inside the json file to be rather painful and I wouldn't expect a wiki site administrator to ever look in there.

I agree to kaldari. I think changing the json comment or a separate README isn't a real problem. And if the reviewer of a change takes a look at config changes can remind to change the README, too. Additionally, we don't have so much config changes, they are fairly rare.

Is it really impossible for us to keep README files up to date? We manage to keep the RELEASE NOTES up to date pretty well. Personally, I find reading comments inside the json file to be rather painful and I wouldn't expect a wiki site administrator to ever look in there.

Yes. One just needs to look at https://www.mediawiki.org/wiki/Extension:MobileFrontend#Configuration_settings
wgMFKeepGoing...?!

Maybe we could take a leaf out of the qqq.json that serves language engineering so well and then enforce that parameters get documented.
e.g. docs/extension.json ?

How is docs/extension.json (from a process point of view) different from a README?

I think you can't really compare the extension doc and a file that needs to go through our code review system :)

Legoktm closed this task as Declined.Sep 19 2015, 12:54 AM
Legoktm claimed this task.

Maybe we could take a leaf out of the qqq.json that serves language engineering so well and then enforce that parameters get documented.
e.g. docs/extension.json ?

Except we don't expect our translators to read or edit the qqq.json file directly, it goes through the UI of Translate. It's on the long term roadmap to i18n-ify configuration settings' documentation, but that's separate from extension.json.


Declining in favor of keeping a separate README (my personal preference) or on-wiki documentation. It is the responsibility of code reviewers to ensure those stay up to date. Technically we allow comments through keys starting with @ in top level and under "config", but my impression of this bug is that it asking for comments that violate the JSON standard, which we will not be implementing for now.

Ok the documentation in the extension registration https://www.mediawiki.org/wiki/Manual:Extension_registration should be updated to say that we recommend you use a README file for adding comments.

@Paladox There's already a note for that:

You can also document configuration on-wiki in your Extension:MyExtension page, and in a README file in the extension's repository.

Legoktm reopened this task as Open.Jan 6 2016, 8:42 PM
Legoktm added a subscriber: Yurik.

@Yurik would like me/us to reconsider this.

Yurik added a subscriber: TheDJ.Jan 6 2016, 8:43 PM

CC: @TheDJ who said "Me too"

Should this task stay open? Two years have passed and it doesn't really seem like we want to do this, as we have Readme files, MediaWiki.org and @-comments in extension registration to fulfill basic needs.

Aklapper raised the priority of this task from High to Needs Triage.Oct 3 2018, 12:01 PM
MGChecker closed this task as Declined.Oct 13 2018, 8:36 PM

I'll be bold and reclose this task as declined. If you disagree, please just reopen it.