Skip to content

Commit fdfc484

Browse files
timmywiltimmywil
committed
feat: add package-manifest page, construct plugin/tags data
1 parent b9bf036 commit fdfc484

16 files changed

+728198
-132
lines changed

‎_data/plugins.json

Lines changed: 244998 additions & 0 deletions
Large diffs are not rendered by default.

‎_data/postsByParent.json

Lines changed: 461395 additions & 0 deletions
Large diffs are not rendered by default.

‎_data/tags.json

Lines changed: 21283 additions & 0 deletions
Large diffs are not rendered by default.

‎content/docs/names.njk

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
---
2+
layout: layouts/base.njk
3+
---
4+
5+
<div class="px-6 py-5 flex flex-col gap-2">
6+
<h1>Naming Your Plugin</h1>
7+
<hr/>
8+
9+
<h2>New plugin releases will not be processed. This page is preserved for historical purposes.</h2>
10+
11+
<div class="flex flex-col gap-2 italic opacity-50">
12+
<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>
13+
<p>
14+
<strong>Plugin names must begin with "jquery." and may only contain letters, numbers, hypens, dots, and underscores.</strong>
15+
</p>
16+
17+
<p>We encourage you to follow a few simple tips as well:</p>
18+
<ul>
19+
<li>Choose a name that is short, but also reasonably descriptive.</li>
20+
<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>
21+
<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>
22+
</ul>
23+
24+
<h2>First Come, First Serve</h2>
25+
<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>
26+
27+
<h2>Transferring Ownership</h2>
28+
<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>
29+
<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>
30+
31+
<h2>Prefixes &amp; Plugin Suites</h2>
32+
<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>
33+
</div>
34+
</div>

‎content/docs/package-manifest.njk

Lines changed: 310 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,310 @@
1+
---
2+
layout: layouts/base.njk
3+
---
4+
5+
<div class="px-6 py-5 flex flex-col gap-2">
6+
<h1>jQuery Plugin Package Manifest Specification</h1>
7+
<hr/>
8+
9+
<p>This document is all you need to know about what's required in your <code>*.jquery.json</code>
10+
manifest file(s).</p>
11+
<p>Manifest files must live in the root of your repository and exist in your tags.
12+
The files must be actual JSON, not just a JavaScript object literal.</p>
13+
<p>
14+
<strong>NOTE: Manifest file names must contain the plugin name, e.g. foo.jquery.json.</strong>
15+
</p>
16+
<hr/>
17+
<h2>Fields</h2>
18+
<h3>Required Fields</h3>
19+
<ul class="flex flex-col gap-1 mb-5 ml-5 list-disc pl-5">
20+
<li>
21+
<a href="#name">name</a>
22+
</li>
23+
<li>
24+
<a href="#version">version</a>
25+
</li>
26+
<li>
27+
<a href="#title">title</a>
28+
</li>
29+
<li>
30+
<a href="#author">author</a>
31+
</li>
32+
<li>
33+
<a href="#licenses">licenses</a>
34+
</li>
35+
<li>
36+
<a href="#dependencies">dependencies</a>
37+
</li>
38+
</ul>
39+
<h3>Optional Fields</h3>
40+
<ul class="flex flex-col gap-1 mb-5 ml-5 list-disc pl-5">
41+
<li>
42+
<a href="#description">description</a>
43+
</li>
44+
<li>
45+
<a href="#keywords">keywords</a>
46+
</li>
47+
<li>
48+
<a href="#homepage">homepage</a>
49+
</li>
50+
<li>
51+
<a href="#docs">docs</a>
52+
</li>
53+
<li>
54+
<a href="#demo">demo</a>
55+
</li>
56+
<li>
57+
<a href="#download">download</a>
58+
</li>
59+
<li>
60+
<a href="#bugs">bugs</a>
61+
</li>
62+
<li>
63+
<a href="#maintainers">maintainers</a>
64+
</li>
65+
</ul>
66+
<h3>
67+
<a href="#name" id="name" class="icon-link toc-link"></a> name</h3>
68+
<p>The <em>most</em> important things in your manifest file are the name and version fields.
69+
The name and version together form an identifier that is assumed
70+
to be completely unique. Changes to the plugin should come along with
71+
changes to the version.</p>
72+
<p>The name is what your thing is called. Some tips:</p>
73+
<ul class="flex flex-col gap-1 mb-5 ml-5 list-disc pl-5">
74+
<li>Don't put "js" or "jquery" in the name. It's assumed that it's js and jquery, since
75+
you're writing a jquery.json manifest file.</li>
76+
<li>The name ends up being part of a URL. Any name with non-url-safe characters will
77+
be rejected. The jQuery Plugins Site is UTF-8.</li>
78+
<li>The name should be short, but also reasonably descriptive.</li>
79+
<li>You may want to check <a href="http://plugins.jquery.com/">the plugins site</a>
80+
to see if there's something by that name already, before you get too attached to it.</li>
81+
<li>If you have a plugin with the same name as a plugin already in the jQuery Plugins
82+
Site, either consider renaming your plugin or namespacing it. For example, jQuery UI
83+
plugins are listed with the "ui." prefix (e.g. ui.dialog, ui.autocomplete).</li>
84+
</ul>
85+
<h3>
86+
<a href="#version" id="version" class="icon-link toc-link"></a> version</h3>
87+
<p>The <em>most</em> important things in your manifest file are the name and version fields.
88+
The name and version together form an identifier that is assumed
89+
to be completely unique. Changes to the plugin should come along with
90+
changes to the version. Version number must be a valid semantic version number
91+
per <a href="https://github.com/isaacs/node-semver">node-semver</a>.</p>
92+
<p>See <a href="#specifying-versions">Specifying Versions</a>.</p>
93+
<h3>
94+
<a href="#title" id="title" class="icon-link toc-link"></a> title</h3>
95+
<p>A nice complete and pretty title of your plugin. This will be used for the page
96+
title and top-level heading on your plugin's page. Include jQuery (if you want) and
97+
spaces and mixed case, unlike <a href="#name">name</a>.</p>
98+
<h3>
99+
<a href="#author" id="author" class="icon-link toc-link"></a> author</h3>
100+
<p>One person.</p>
101+
<p>See <a href="#people-fields">People Fields</a>.</p>
102+
<h3>
103+
<a href="#licenses" id="licenses" class="icon-link toc-link"></a> licenses</h3>
104+
<p>Array of licenses under which the plugin is provided. Each license is a hash with
105+
a url property linking to the actual text and an optional "type" property specifying the type of license. If the license is one of the <a href="http://www.opensource.org/licenses/alphabetical">official open source licenses</a>, the official license name or its abbreviation may be explicated with the "type" property.</p>
106+
107+
{% highlight "js" %}
108+
"licenses": [
109+
{
110+
"type": "GPLv2",
111+
"url": "http://www.example.com/licenses/gpl.html"
112+
}
113+
]
114+
{% endhighlight %}
115+
116+
<h3>
117+
<a href="#dependencies" id="dependencies" class="icon-link toc-link"></a> dependencies</h3>
118+
<p>Dependencies are specified with a simple hash of package name to version
119+
range. The version range is EITHER a string which has one or more
120+
space-separated descriptors, OR a range like "fromVersion - toVersion".</p>
121+
<p>If a plugin that you depend on uses other plugins as dependencies that your plugin
122+
uses as well, we recommend you list those also. In the event that the depended on
123+
plugin alters its dependencies, your plugin's dependency tree won't be affected.</p>
124+
<p>Libraries such as jQuery or underscore, though not plugins, should be listed as
125+
dependencies as well. This gives you the flexibility to specify compatible versions
126+
of each library you depend on.</p>
127+
<p>You must list at least one dependency, <code>jquery</code> (note that it's lower-case).</p>
128+
<h3>
129+
<a href="#description" id="description" class="icon-link toc-link"></a> description</h3>
130+
<p>Put a description in it. It's a string. This helps people discover your
131+
plugin, as it's listed on the jQuery Plugins Site.</p>
132+
<h3>
133+
<a href="#keywords" id="keywords" class="icon-link toc-link"></a> keywords</h3>
134+
<p>Put keywords in it. It's an array of strings. This helps people
135+
discover your plugin as it's listed on the jQuery Plugins Site.
136+
Keywords may only contain letters, numbers, hyphens, and dots.</p>
137+
<h3>
138+
<a href="#homepage" id="homepage" class="icon-link toc-link"></a> homepage</h3>
139+
<p>The url to the plugin homepage.</p>
140+
<h3>
141+
<a href="#docs" id="docs" class="icon-link toc-link"></a> docs</h3>
142+
<p>The url to the plugin documentation.</p>
143+
<h3>
144+
<a href="#demo" id="demo" class="icon-link toc-link"></a> demo</h3>
145+
<p>The url to the plugin demo or demos.</p>
146+
<h3>
147+
<a href="#download" id="download" class="icon-link toc-link"></a> download</h3>
148+
<p>The url to download the plugin. A download URL will be automatically generated
149+
based on the tag in GitHub, but you can specify a custom URL if you'd prefer
150+
to send users to your own site.</p>
151+
<h3>
152+
<a href="#bugs" id="bugs" class="icon-link toc-link"></a> bugs</h3>
153+
<p>The url to the bug tracker for the plugin.</p>
154+
<h3>
155+
<a href="#maintainers" id="maintainers" class="icon-link toc-link"></a> maintainers</h3>
156+
<p>An array of people.</p>
157+
<p>See <a href="#people-fields">People Fields</a>.</p>
158+
<h2>
159+
<a href="#people-fields" id="people-fields" class="icon-link toc-link"></a> People Fields</h2>
160+
<p>A "person" is an object with a "name" field and optionally "url" and
161+
"email", like this:</p>
162+
163+
{% highlight "json" %}
164+
{
165+
"name" : "Barney Rubble",
166+
"email" : "[email protected]",
167+
"url" : "http://barnyrubble.tumblr.com/"
168+
}
169+
{% endhighlight %}
170+
171+
<p>Both the email and url are optional.</p>
172+
<hr>
173+
<h2>
174+
<a href="#specifying-versions" id="specifying-versions" class="icon-link toc-link"></a> Specifying Versions</h2>
175+
<p>Version range descriptors may be any of the following styles, where "version"
176+
is a semver compatible version identifier.</p>
177+
<ul class="flex flex-col gap-1 mb-5 ml-5 list-disc pl-5">
178+
<li>
179+
<code>version</code> Must match <code>version</code> exactly</li>
180+
<li>
181+
<code>=version</code> Same as just <code>version</code>
182+
</li>
183+
<li>
184+
<code>&gt;version</code> Must be greater than <code>version</code>
185+
</li>
186+
<li>
187+
<code>&gt;=version</code> etc</li>
188+
<li>
189+
<code>&lt;version</code>
190+
</li>
191+
<li>
192+
<code>&lt;=version</code>
193+
</li>
194+
<li>
195+
<code>~version</code> See 'Tilde Version Ranges' below</li>
196+
<li>
197+
<code>1.2.x</code> See 'X Version Ranges' below</li>
198+
<li>
199+
<code>*</code> Matches any version</li>
200+
<li>
201+
<code>version1 - version2</code> Same as <code>&gt;=version1 &lt;=version2</code>.</li>
202+
<li>
203+
<code>range1 || range2</code> Passes if either range1 or range2 are satisfied.</li>
204+
</ul>
205+
<p>For example, these are all valid:</p>
206+
207+
{% highlight "json" %}
208+
{
209+
"dependencies": {
210+
"foo" : "1.0.0 - 2.9999.9999",
211+
"bar" : ">=1.0.2 <2.1.2",
212+
"baz" : ">1.0.2 <=2.3.4",
213+
"boo" : "2.0.1",
214+
"qux" : "<1.0.0 || >=2.3.1 <2.4.5 || >=2.5.2 <3.0.0",
215+
"asd" : "http://asdf.com/asdf.tar.gz",
216+
"til" : "~1.2",
217+
"elf" : "~1.2.3",
218+
"two" : "2.x",
219+
"thr" : "3.3.x"
220+
}
221+
}
222+
{% endhighlight %}
223+
224+
<h3>
225+
<a href="#tilde-version-ranges" id="tilde-version-ranges" class="icon-link toc-link"></a> Tilde Version Ranges</h3>
226+
<p>A range specifier starting with a tilde <code>~</code> character is matched against
227+
a version in the following fashion.</p>
228+
<ul class="flex flex-col gap-1 mb-5 ml-5 list-disc pl-5">
229+
<li>The version must be at least as high as the range.</li>
230+
<li>The version must be less than the next major revision above the range.</li>
231+
</ul>
232+
<p>For example, the following are equivalent:</p>
233+
<ul class="flex flex-col gap-1 mb-5 ml-5 list-disc pl-5">
234+
<li>
235+
<code>"~1.2.3" = "&gt;=1.2.3 &lt;1.3.0"</code>
236+
</li>
237+
<li>
238+
<code>"~1.2" = "&gt;=1.2.0 &lt;1.3.0"</code>
239+
</li>
240+
<li>
241+
<code>"~1" = "&gt;=1.0.0 &lt;2.0.0"</code>
242+
</li>
243+
</ul>
244+
<h3>
245+
<a href="#x-version-ranges" id="x-version-ranges" class="icon-link toc-link"></a> X Version Ranges</h3>
246+
<p>An "x" in a version range specifies that the version number must start
247+
with the supplied digits, but any digit may be used in place of the x.</p>
248+
<p>The following are equivalent:</p>
249+
<ul class="flex flex-col gap-1 mb-5 ml-5 list-disc pl-5">
250+
<li>
251+
<code>"1.2.x" = "&gt;=1.2.0 &lt;1.3.0"</code>
252+
</li>
253+
<li>
254+
<code>"1.x.x" = "&gt;=1.0.0 &lt;2.0.0"</code>
255+
</li>
256+
<li>
257+
<code>"1.2" = "1.2.x"</code>
258+
</li>
259+
<li>
260+
<code>"1.x" = "1.x.x"</code>
261+
</li>
262+
<li>
263+
<code>"1" = "1.x.x"</code>
264+
</li>
265+
</ul>
266+
<p>You may not supply a comparator with a version containing an x. Any
267+
digits after the first "x" are ignored.</p>
268+
<h3>
269+
<a href="#sample-manifest" id="sample-manifest" class="icon-link toc-link"></a> Sample manifest</h3>
270+
<p>
271+
<strong>color.jquery.json</strong>
272+
</p>
273+
274+
{% highlight "json" %}
275+
{
276+
"name": "color",
277+
"title": "jQuery Color",
278+
"description": "jQuery plugin for color manipulation and animation support.",
279+
"keywords": [
280+
"color",
281+
"animation"
282+
],
283+
"version": "2.1.2",
284+
"author": {
285+
"name": "jQuery Foundation and other contributors",
286+
"url": "https://github.com/jquery/jquery-color/blob/2.1.2/AUTHORS.txt"
287+
},
288+
"maintainers": [
289+
{
290+
"name": "Corey Frang",
291+
"email": "[email protected]",
292+
"url": "http://gnarf.net"
293+
}
294+
],
295+
"licenses": [
296+
{
297+
"type": "MIT",
298+
"url": "https://github.com/jquery/jquery-color/blob/2.1.2/MIT-LICENSE.txt"
299+
}
300+
],
301+
"bugs": "https://github.com/jquery/jquery-color/issues",
302+
"homepage": "https://github.com/jquery/jquery-color",
303+
"docs": "https://github.com/jquery/jquery-color",
304+
"download": "http://code.jquery.com/#color",
305+
"dependencies": {
306+
"jquery": ">=1.5"
307+
}
308+
}
309+
{% endhighlight %}
310+
</div>

‎content/docs/publish.njk

Lines changed: 44 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,44 @@
1+
---
2+
layout: layouts/base.njk
3+
---
4+
5+
<div class="px-6 py-5 flex flex-col gap-2">
6+
<h1>Publishing Your Plugin</h1>
7+
<hr/>
8+
9+
<h2>New plugin releases will not be processed. This page is preserved for historical purposes.</h2>
10+
11+
<div class="flex flex-col gap-2 italic opacity-50">
12+
<p>Publishing your plugin on the site is a three step process:</p>
13+
<h2>Add a Service Hook</h2>
14+
<p>First, you&#39;ll need to enable the jQuery Plugins service hook on GitHub. On the settings page for your repository, click the Webhooks &amp; Services link, thenclick the Configure services button. Scroll down to find the jQuery Pluginsservice and enable it (there&#39;s no config, just check the Active checkbox andclick the Update settings button).</p>
15+
<h2>Add a Manifest to your Repository</h2>
16+
<p>The jQuery Plugins Registry will look in the root level of your repository forany files named <code>*.jquery.json</code>. You will want to create <code>*yourplugin*.jquery.json</code> according to the <a href="/docs/package-manifest/">package manifestspecification</a>. Use an online JSON verifier such as <a href="http://jsonlint.com">JSONlint</a> to make sure the file is valid. You are now ready to publish your plugin!</p>
17+
18+
<h2>Publishing a Version</h2>
19+
<p>After the service hook is setup and your manifest has been added,publishing your plugin is as simple as tagging the version in git and pushingthe tag to GitHub. The service hook will notify the plugins site that anew tag is available and the plugins site will take care of the rest!</p>
20+
<div class="syntaxhighlighter bash nogutter">
21+
<table>
22+
<tbody>
23+
<tr>
24+
<td class="gutter">
25+
<div class="line n1">1</div>
26+
<div class="line n2">2</div>
27+
</td>
28+
<td class="code">
29+
<pre><div class="container"><div class="line"><code>$ git tag 0.1.0</code></div></div><div class="container"><div class="line"><code>$ git push origin --tags</code></div></div></pre>
30+
</td>
31+
</tr>
32+
</tbody>
33+
</table>
34+
</div>
35+
<p>The name of the tag <strong>must</strong> be a valid <a href="http://semver.org/">semver</a> value, butmay contain an optional <code>v</code> prefix. The tag name must also match theversion listed in the manifest file. So, if the version field in the manifestis &quot;0.1.1&quot; the tag should be either &quot;0.1.1&quot; or &quot;v0.1.1&quot;. If the manifest fileis valid, the version will be automatically added to the plugins site.</p>
36+
<p>The registry <strong>does not support re-processing tags that it has already seen.</strong>Therefore, we strongly suggest that you <strong>do not overwrite old tags</strong>. Instead,update the version number tag in the manifest, commit, and create a new tag tofix any errors you&#39;ve encountered. </p>
37+
<p>For example, you&#39;ve pushed version <code>v1.7.0</code> of your plugin, but there is an <a href="/error.log">error detected</a> in the manifest. If you fix the error, delete,re-create, and push another <code>v1.7.0</code> tag, the registry <strong>will not</strong> detect it.You will have to create and push <code>v1.7.1</code>.</p>
38+
<h2>Troubleshooting</h2>
39+
<p>If you have problems with your plugin not publishing you should check the <a href="/error.log">error log</a> for hints on what the problem might be.</p>
40+
<p>If you still encounter trouble getting this process to work with your plugin, pleasejoin the IRC channel <a href="irc://freenode.net:6667/#jquery-content">#jquery-content</a> on <a href="http://freenode.net">freenode</a>. If you can&#39;t seem to connect with someonein the IRC channel, please feel free to email us at <a href="mailto:[email protected]">[email protected]</a>.</p>
41+
<h2>How long should the process take</h2>
42+
<p>When everything works, this process is pretty close to instant. There arecaches in place, etc, but in general, if you haven&#39;t seen your plugin getupdated on the site within 5 minutes, there is a good chance something wentwrong. Going into your Web Hooks settings and hitting the &quot;Test Hook&quot; button(once) may help if you recently pushed a new tag.</p>
43+
</div>
44+
</div>

‎content/index.njk

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@ layout: layouts/base.njk
33
---
44

55
<div class="text-center bg-[url(/img/dark-grey-tile.png)] p-8 lg:py-12">
6-
<h1 class="text-white">The jQuery Plugin Registry</h1>
6+
<h1 class="text-white lg:text-6xl">The jQuery Plugin Registry</h1>
77
</div>
88

99
<div class="flex flex-col lg:flex-row-reverse">

‎_data/options.json renamed to ‎dump/json/options.json

File renamed without changes.

‎_data/postmeta.json renamed to ‎dump/json/postmeta.json

File renamed without changes.

0 commit comments

Comments
 (0)