Skip to content
Browse files

Added documentation on plugin names and name reserveration process. F…

…ixes #7.
  • Loading branch information...
1 parent 1cb9748 commit ac29e225fa3e05921de2e8b2970850d2e015d12b @scottgonzalez scottgonzalez committed
Showing with 82 additions and 1 deletion.
  1. +26 −0 pages/names
  2. +56 −1 src/wordpress.js
View
26 pages/names
@@ -0,0 +1,26 @@
+Naming Your Plugin
+
+<p>Before you can list your plugin on this site, you'll need to choose a name for your plugin. The name is a unique identifier that distinguishes your plugin from all other plugins. This is different from the title of your plugin, which you can think of as the display name.</p>
+
+<p><strong>Plugin names must begin with "jquery." and may only contain URL-safe characters.</strong></p>
+
+<p>We encourage you to follow a few simple tips as well:</p>
+<ul>
+ <li>Choose a name that is short, but also reasonably descriptive.</li>
+ <li>Match your plugin name to your file name, e.g., the jquery.foo plugin would live in a file named jquery.foo.js.</li>

So now everyone has to start prefixing their files with jquery.* just because some guy raises a concern about compatibility with his AMD loader (#22)... WTF, that's just wrong.

No. It's encouraged, not required. This is also a very common convention already, and has been for years, even before AMD.

Common because some copy the naming convention from jquery.ui, where it actually makes some sense because of its authors.

Having everything start with 'jquery.' in an archive of jquery plugins is just overkill. There's no need for that prefix there. I'd even say encouraging dependency declaration in filenames is bad.

That naming convention was popular before jQuery UI even existed. I have no idea why you would think this is related to jQuery UI. I also don't know what the number of authors has to do with the naming of a file.

This is about more than just the plugins site. It's about interop with other code. Also, this has nothing to do with listing dependencies and everything to do with what your code does. Of the million things your JavaScript might do, extending jQuery is just one of them. The naming is to signify that the code is a jQuery plugin, not that it has a dependency on jQuery.

If you are prefixing to indicate a script is a jQuery plugin then what is your definition of a jQuery plugin?

As you explain it your definition of a jQuery plugin is any script that uses jQuery and not just scripts that extend the jQuery namespace. By that same logic people would have to start naming their files jquery.underscore.raphael.history.modernizr.scriptname.

That's why I'm saying you should drop the prefix, all it does is introduce another layer of mess to deal with.

Where did I say that? My exact words were:

Of the million things your JavaScript might do, extending jQuery is just one of them. The naming is to signify that the code is a jQuery plugin, not that it has a dependency on jQuery.

That's the opposite of what you just said my definition is.

That would mean a lot of scripts in the plugin archive shouldn't be considered jQuery plugins. They don't extend the jQuery namespace, all they do is use jQuery.

@rdworth
rdworth added a note

Why would we want to allow something into the jQuery Plugins site that isn't a jQuery plugin exactly?

Maybe because it has been allowed ever since jQuery had a plugin site.

The definition of a jQuery plugin to you guys might be that a scripts extends the jQuery namespace, but most people have come to see a plugin as just a script that uses a javascript framework, as scewed as that might seem. Almost every other framework besides jQuery has plugins that don't extend the framework global, that might be the reason people see it this way and why the plugin archive is stacked with scripts that don't extend the jQuery namespace.

@rdworth
rdworth added a note

Ok, I just re-read this whole conversation and I think I found some clarity. Let us agree
A) Some code uses jQuery and is not a jQuery plugin
B) Some code uses jQuery and is a jQuery plugin
C) Some code extends jQuery and is a jQuery plugin
With that:

  • A does not belong on the jQuery Plugins site
  • B and C belong on the plugins site with the jquery. name prefix because the prefix is about whether or not your code is considered a jQuery plugin, not whether or not your code extends jQuery

I don't agree, people see A. as a plugin. That's why they have been in the plugin site since forever, and why they should remain indexed.

@rdworth
rdworth added a note

If people see A. as a plugin then it is not A it is B. My point is that there is JavaScript code on the internet that makes use of jQuery but is decidedly not a jQuery plugin. If what you have is a jQuery plugin then it most certainly has to use jQuery. That doesn't mean all code that uses jQuery is a plugin. It also doesn't mean that the jquery. name prefix is expressing that dependence on jQuery. And no one is saying anywhere that extending jQuery is a requirement for being considered a jQuery plugin.

@rdworth
rdworth added a note

@davidultra any chance you're conflating name with title? We have no requirement that anyone have jQuery in the title of their plugin. See https://github.com/jquery/plugins.jquery.com/blob/master/docs/package.md#field-title

@rdworth
rdworth added a note

@davidultra said:

The definition of a jQuery plugin to you guys might be that a scripts extends the jQuery namespace

It's not. There's no place to get that from anything we've written. @scottgonzalez 's exact words, again:

Of the million things your JavaScript might do, extending jQuery is just one of them.

What he's saying is a jQuery plugin is JavaScript. It might do one of a million things. Or more than one. (Presumably it has to do at least one thing). One of those many things it might do is extend jQuery. That's nothing it has to do, but it might. The fact that you consider it not just a bit of JavaScript but a jQuery plugin, and you want it listed on the jQuery plugins site means you need to put 'jquery.' in the name. And as @scottgonzalez pointed out, this is a convention as old as jQuery plugins themselves, even if it wasn't one enforced by the previous version of the plugins site. There will be breaking changes. The previous version of the site let you log in with a username and password and upload files. Just because that site always let you do that, doesn't mean the new one will. But there's no room to say that plugins that were listed previously (assuming they were in fact plugins) now no longer have a home.

No, we've been talking about the reasoning behind the prefix in filenames. It seems to be there to indicate that something is a jquery plugin but the definition of a plugin is pretty vague and based on perception. Someone seeing A. as B. shouldn't make it a B, or vice-versa since that would mean the script won't even be indexed.

@rdworth
rdworth added a note

If you want to list something on the jQuery plugins site you have to be willing to call it a jQuery plugin. If you are, it is B. It doesn't matter that someone else may not have written it in that way, or at all. Or maybe they would simply write it as a piece of JavaScript, not as a jQuery plugin, not use jQuery, etc. The point is, not every arbitrary piece of JavaScript that's reusable can or should be listed on the jQuery plugins site. What should be listed on the jQuery plugins site are things that the author considers a jQuery plugin.

Makes sense, that's how it has always worked. But as far as the prefix in filenames goes I'm not a fan of encouraging it. The only times when that makes sense to me is whenever a script does extend the jQuery global, where it is a C. Scripts that don't extend but heavily depend on jQuery and perhaps some other scripts are not something I'd prefix with jquery, even though most people would consider them jquery plugins.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
+ <li>Check the site to see if the name you want is available, before getting your heart set on a name that's already taken.</li>
+</ul>
+
+<h2>First Come, First Serve</h2>
+
+<p>Names are registered on a first come, first serve basis. Registering a name happens automatically the first time you <a href="/publish">publish a release</a> of your plugin. You cannot reserve a name prior to releasing your plugin. Once you've registered a name, you are the sole owner of that name. Nobody else will be able to publish a release using the same name. There is no limit on how many plugins/names a single person may register, but all plugins must be legitimate.</p>
+
+<h2>Transferring Ownership</h2>
+
+<p>While most plugins will only ever have one owner, there are times when the original owner may move on to other projects and wish to transfer ownership to someone else. There is currently no automated process for this, the original owner must contact a <a href="http://jquery.org/team">jQuery team member</a>, prove ownership and indicate who the new owner should be.</p>
+
+<p>In the case of an abandoned plugin where the original owner is no longer active, the jQuery team can choose to change ownership at their discretion. These will indeed be a rare occurrence, likely requiring an event such as _why or Mark Pilgrim's infosuicide.</p>
+
+<h2>Prefixes & Plugin Suites</h2>
+
+<p>Certain prefixes will also be blacklisted for individual plugins. Large projects which include many plugins in a single repository, such as <a href="http://jqueryui.com">jQuery UI</a>, are registered as suites. Each suite is required to have a unique prefix and all of their plugin names must use that prefix. As such, no other plugin may use a name with a suite's prefix. Suites must be manually vetted by the jQuery team.</p>
View
57 src/wordpress.js
@@ -1,4 +1,5 @@
-var mysql = require( "mysql" ),
+var fs = require( "fs" ),
+ mysql = require( "mysql" ),
Step = require( "step" ),
config = require( "./config" );
@@ -459,6 +460,60 @@ var wordpress = module.exports = {
setMeta( info.insertId, "_wp_page_template", "post-receive.php", this );
},
+ // find all documentation pages to create
+ function( error ) {
+ if ( error ) {
+ return fn( error );
+ }
+
+ fs.readdir( path.resolve( __dirname, "../pages" ), this );
+ },
+
+ // read in documentation pages
+ function( error, files ) {
+ if ( error ) {
+ return fn( error );
+ }
+
+ this.parallel()( null, files );
+ var group = this.group();
+ files.forEach(function( file ) {
+ fs.readFile( path.resolve( __dirname, "../pages", file ), "utf8", group() );
+ });
+ },
+
+ // generate documentation pages
+ function( error, files, contents ) {
+ if ( error ) {
+ return fn( error );
+ }
+
+ var group = this.group();
+ contents.forEach(function( content, i ) {
+ var lines = content.split( "\n" ),
+ title = lines.shift();
+ lines.shift();
+ createPost({
+ name: "_" + files[ i ],
+ title: title,
+ content: lines.join( "\n" ),
+ date: new Date()
+ }, group() );
+ });
+ },
+
+ // set page template for documentation pages
+ function( error, pageIds ) {
+ if ( error ) {
+ return fn( error );
+ }
+
+ var group = this.group();
+ pageIds.forEach(function( id ) {
+ setMeta( id, "_wp_page_template", "blank-page.php", group() );
+ });
+ },
+
// clear rewrite rules
function( error ) {
if ( error ) {

0 comments on commit ac29e22

Please sign in to comment.
Something went wrong with that request. Please try again.