Meta: Discussion of jQuery plugin package.json schema #2

Closed
ajpiano opened this Issue Dec 8, 2011 · 32 comments

Projects

None yet
@ajpiano
Contributor
ajpiano commented Dec 8, 2011

If you have comments or concerns about the way we've configured the package.json for jQuery plugins, this here's the place to raise them.

I would love a dummy example for a plugin. Maybe use one of the "official" plugins as a guide.

evmcl commented Dec 8, 2011

I think an optional "demo" URL field, similar to the "homepage" field would be of use. It was certainly handy in the old plugin site to have a direct link to a working demo you could have a look at.

Contributor
jrburke commented Dec 9, 2011

For dependency names, I suggest making sure they follow the file name, not the object name. So, if something depends on jQuery, the dependency should be 'jquery': '>=1.7.0', and not 'jQuery'. Similar for something like Backbone, using 'backbone' will be better. This will fit better with how node and AMD normally find modules -- by looking at the file name.

jrburke commented Dec 9, 2011

What about supporting the package.json in a comment in the JS file itself?

I have opened a similar issue with npm, but basically, it would be nice for your tooling to recognize a comment like so:

/*package.json
{}
*/

This would avoid having to create a separate file for this info, and since it is a comment, it should minify out for deployment.

Contributor
rdworth commented Dec 9, 2011

@jrburke said:

I suggest making sure they follow the file name, not the object name

Yup, although to be pedantic, we'll match it to the plugin name (the name field in the package.json) which will be used to determine the url on plugins.jquery.com. But the filename of course would have other stuff in it, and is not actually required to be specified. Example:

filename: jquery.imageslider.js
object name: jquery.fn.imageSlider
plugin name: imageslider

Contributor
rdworth commented Dec 9, 2011

@matthewlein: Great thinking. As Ralph points out, we no longer use the term "official plugins", but the jQuery core team maintains the color plugin, so I added a package.json for it as a sample at the end of the spec file.

Contributor
rdworth commented Dec 9, 2011

@jrburke said:

What about supporting the package.json in a comment in the JS file itself?

One of the main problems with this is discoverability. What we've achieved to date is that given a GitHub repo url (comes down to username + repo name), we can walk all tags that are valid semvers, and attempt to process the package.json file in the root of each of those. This breaks down pretty mightily when that same metadata might be in the header of any number of files in the repo, and those files could have any name and be at any depth in the folder hierarchy (/src, /lib, /js, etc.). So not only do we not know which file to look inside, there's no way to restrict the repo to only have one manifest (which is a design feature for us).

I read isaacs comments on your issue in npm. I think one distinct difference (to his comment, not your request) is the likelihood that a jQuery plugin would be authored with a filename of index.js and be in the root. This seems quite reasonable for a something like an npm package, but I don't know that it is for a jQuery plugin. Partly because plugins so often are single files, and often thrown into a single folder, so people already given them unique names that support that out-of-the-box, without having to rename, or having to keep every plugin in its own folder. If we had a recommended standard for filenames, it would be jquery.pluginname.js. That would seem to work (as an alternative to index.js, as long as we're searching for a magically-named file) except that we don't know the plugin name until we find it in the package.json. Again, this is a difference from npm, and is a bit by-design. Rather than submit a plugin by specifying a plugin name AND a repo (or a plugin name AND a package.json) we just want to be pointed at that repo. And there's nothing that says that repo name will be useful in determining the exact name of the plugin (and thus, the name of the file that has the package.json in the header).

What I'd recommend is a build step to pull the json out of the file header and put it in a generated package.js in the root. So, much like minified files (for some) this would only be in the tag, not maintained otherwise in the repo, to avoid duplication.

jrburke commented Dec 9, 2011

@rdworth said:

Yup, although to be pedantic, we'll match it to the plugin name (the name field in the package.json) which will be used to determine the url on plugins.jquery.com. But the filename of course would have other stuff in it, and is not actually required to be specified. Example:

filename: jquery.imageslider.js
object name: jquery.fn.imageSlider
plugin name: imageslider

Ideally, for the case above, the package name would be 'jquery.imageslider', and anything that depended on it would name the dependency 'jquery.imageslider'.

My main interest in this is to allow other tools besides the plugin site to install these files into projects, like perhaps being able to use npm or cpm, and I expect at least one other kind of tool like this. If the names match CommonJS/AMD module ID conventions, it makes it much easier/portable.

If that is not possible for some reason, at least making sure that 'jquery' is used for jQuery dependency, and 'backbone' for Backbone.

On the topic of package.json as a JS comment:

One of the main problems with this is discoverability.

My assumption was that there would only be one top-level .js file in the repo, and that would be the plugin. In that case, the file could be inspected for the package.json comment. Of course for larger projects that need a few files or have complex directories, an explicit package.json makes sense. So the tests for package.json info:

  • if package.json use that
  • else if only one .js file at the top level, look in there for package.json comment
  • else error
pupunzi commented Dec 9, 2011

I would suggest to introduce an optional "demo" URL and "documentation" URL fields on the package.json

Contributor

Along with npm and cpm, there's also bpm: https://github.com/bpm/bpm - might be good to get them onboard as well.

@jzaefferer I've mentioned this before, but there is also ender.js - http://ender.no.de/ supports the same package.json format and is specifically designed for client side lib building

What about browser compatibility? With "HTML5" functionality I imagine there might be a lot of this: ie: ">=9".

Contributor

We should definitely not encourage users to build plugins that don't work cross-browser.

@scottgonzalez @benpickles Definitely should not be encouraged, but maybe some kind of object that can contained tested-on browsers so if you do use it on IE6/7 it's a "Here be dragons" situation

I agree, they should be cross-browser. However if a plugin uses canvas or any other new fangled technology that's not compatible with jQuery's browser commitments it might cause unhappiness.

Perhaps the dependency is canvas support rather than browser support (which I suppose would need to be actively maintained), how might this be declared?

Contributor

@tanepiper @benpickles At least to start, I'd much rather see that just written in a description than codified in package.json. I'm hesitant to be specifying a property which a) is unlikely to be used (or at least be accurate) for most plugins and b) encourages tools to be written around filtering plugins for browser support.

Contributor

@benpickles We don't really have plans to specify any dependencies like that. Also, canvas is a pretty bad example, since it can be polyfilled.

pupunzi commented Dec 12, 2011

I think that all of these should be delegated to the specific plug-in developer page as it has been till now;
I would not introduce such dependences on the package.json file at all.

Il giorno 12/dic/2011, alle ore 15.27, Ben Pickles ha scritto:

I agree, they should be cross-browser. However if a plugin uses canvas or any other new fangled technology that's not compatible with jQuery's browser commitments it might cause unhappiness.

Perhaps the dependency is canvas support rather than browser support (which I suppose would need to be actively maintained), how might this be declared?


Reply to this email directly or view it on GitHub:
#2 (comment)

Krinkle commented Dec 21, 2011

Just a random thought when looking over the wiki page - no ability to specify more than one author ? (e.g. co-ownership or maintainers).

Contributor

@Krinkle That is based on npm and it seems to be working for there. One
author, many contributors.

Mottie commented Dec 27, 2011

I'm tossing in my idea for an optional "screenshot" and/or "icon" URL field. I think it would make browsing the plugin database easier to see a recognizable image to go along with the plugin.

Contributor
rdworth commented Dec 29, 2011

Renamed contributors to maintainers in a4c439d. If someone wants the full list of contributors, they can ask git or GitHub.

Contributor
rdworth commented Dec 29, 2011

Discussed with @scottgonzalez . We're going to add the following fields:

  • demo
  • docs
  • screenshot
    Demo and docs will support only absolute urls. Screenshot can be a relative url and the site will pull the file (which will need to be some standard size, like 250x150) so we can serve it up from CDN.
Mottie commented Dec 29, 2011

Will the demo and screenshot fields allow multiple entries, or just one each?

Contributor

They're both single URL fields. The screenshot will be used as a thumbnail, similar to jqueryplugins.com. If you have multiple demos, you should pick either your most compelling demo or a page that lists all of your demos.

Contributor

It's been three months and the discussion has died down. I'm closing this ticket and new tickets should be opened for any specific suggestions that come in.

I've created the following issues that are still open from this discussion:
#21 - Support for plugin screenshot
#22 - Discuss package naming

too many comments to read after the official blog post. So just gonna put my question as plain as possible.

is http://plugins.jquery.com sub-domain gonna come live again or not. it's Jan 4th 2013 today. 2 years of uncertainty.

How can i contribute to http://plugins.jquery.com if i can spare some time get this resource come to life again after office hours ?

OR just gonna remain on GIT and http://plugins.jquery.com is not gonna come again.

Contributor
ajpiano commented Jan 4, 2013

@ronnie-depp yes, it is going to be live again, and it shouldn't be too long. Unfortunately work on relaunching the plugins site got tied up with a lot of other work redesigning and coming up with a new deploy system for all of the jQuery websites (In fact, a lot of the plugins site work catalysed and informed the tools we're using network wide, see: jquery/grunt-jquery-content and scottgonzalez/grunt-wordpress).

To see the current state of the new site, check out http://stage.plugins.jquery.com

If you'd like to help out, the best way to get started is to familiarise yourself with our web-base-template and try to get it running locally. This repository (plugins.jquery.com) and all of our other "content repositories" deploy into a local web-base-template instance (as well as for staging and production environments) using the tools I mentioned above, and once you get this workflow set up locally, you'll be in a position to start working on anything from the site content and design, to the mechanics of how the submission process works under the hood, if you so desire.

We're sorry that the process has taken so long but are glad you are willing to lend a hand, if you can. If you run into trouble, please come find us in the #jquery-content channel on irc.freenode.net and I'm more than happy to help point you in the right direction, or continue inquiring on specific issues (but not this one, as our discussion is obviously not the topic of this particular issue.) Thanks for your interest and concern :)

@ajpiano thanks got an idea. I will get back, after workload gets normal, to tryout plugins.jquery repository locally.
thanks again Adam.

The connection has timed out

      The server at stage.plugins.jquery.com is taking too long to respond.

The site could be temporarily unavailable or too busy. Try again in a few
moments.
If you are unable to load any pages, check your computer's network
connection.
If your computer or network is protected by a firewall or proxy, make sure
that Firefox is permitted to access the Web.

http://stage.plugins.jquery.com/ is acessible this time.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment