Please review the proposed new repository and leave some comments so Obenland can make all more awesome.
Note: We are aware that some frameworks are current in the repository. We are asking you not submit any NEW at this time.
This isn’t a new ‘rule.’ It’s not a secret one either. It’s not listed in the guidelines specifically because any attempt to lay down each and every reason a plugin shouldn’t be in the repository just ends in people rule-lawyering. Should we have to tell people “Don’t ask users to write to your plugin files”? No. That should be self-evident. A plugin gets replaced when it’s upgraded, so writing to plugin files means the changes get destroyed. And in many ways, that’s our problem here.
The issue is as follows: Having a framework as a plugin is a poor experience for the user. Not the developer. The user. The user understands “I have an add-on for WooCommerce, I probably need Woo.” They do not always understand “I have plugin Slider Joe. Why do I need Advanced Custom Fields?” In addition, by having a library as a plugin, the onus of version compatibility is now on the person least likely to understand it: the user.
The plugin repository is not, currently, a library or framework repository. It’s not meant like the NPM package manager, or even Composer as a way to define what a plugin ‘needs’ in the same ways for a developer to build a project. The plugin repository is, plain and simple, meant for plugins that users will find useful. Plugins that add functionality to WordPress in a directly inter-actable way.
At this time, we are not accepting frameworks as we don’t feel frameworks, boilerplates, and libraries are appropriate for the Plugins Directory. We require that plugins be useful in and of themselves (even if only being a portal to an external service). And while there are many benefits to frameworks and libraries, without plugin dependency support in core or the directory, it becomes another level of hassle for users.
The parade of likely support issues:
And bearing in mind that the framework and plugin developers are different people, that’s another level of coordination/compatibility issues. A developer is (in theory) clever enough to write their plugin in a way that it includes the version of the library they need in a way that will not break everyone else. Of course, you developers know that’s a goal and not an absolute.
Frameworks and libraries should be packaged with each plugin (hopefully in a way that doesn’t conflict with other plugins using the framework or libraries). At least until core supports plugin dependencies.
Making this messier is the fact that once a library is in the repository, you shouldn’t put it in your plugin anymore. Why not? Well what happens if they install a library as a plugin, while having the library inside a plugin already? Which one takes precedent? What happens when they’re out of sync and so on? See the goal up above that isn’t an absolute. It gets even messier.
A library is a library, and should be in the plugin, not separate.
Maybe one day we’ll have proper plugin dependencies, but we simply are not there yet.
Unlike the title might suggest, this post is not about buying a plugin from a commercial author, or the viability of “freemium” plugins in the directory, or app stores, or anything of that sort.
This post is directed squarely at plugin authors.
Question: Who owns your plugin?
The answer is simple: You do. You wrote it. You hold the copyrights on it.
Now hold on a minute (one might say), everything in our directory is GPL or compatible. Isn’t that copyleft? Well, yes, and I’m not going to go into excessive amounts of legalese here (IANAL), but the GPL is built on top of copyright. It actually requires it. So yes, you do own the copyrights to your plugin, even when it’s available for free in the WordPress.org plugin directory.
And yes, that totally means you can sell those rights to somebody else. We won’t stop you. Heck, if you ask, we’ll even help you perform the transfer correctly.
Now, while we’ve talked about this before, it’s worth re-iterating because it has come up a lot recently: your name is on that plugin. If you sell it to some scummy spammer, then your name is likely to get dragged through the mud. Not by us, of course, we don’t name names. But other people do notice bad things happening, and they tell other people, and make posts in our forums, and leave bad reviews… and before you know it, you can get a bad rap for something you didn’t even do.
There have been a lot of reports of various unsolicited emails recently asking plugin authors if they would sell their plugins. Sometimes these are legitimate offers. Not often. Usually it’s from marketing agencies looking to add backlinks.
In a couple of notable cases, some of those plugin authors asked what the person was planning on doing to change the plugin. Surprisingly they responded and told them. Let’s just say that these plans are very much against our guidelines.
In at least one case, the plugin author told this prospective purchaser as much, and the person responded by asking how long it would be in the directory before we shut it down, and how many sites could he get the code to before getting this noticed and thus removed from the directory. He even asked whether it was a manual or automatic process (hint: it’s both).
Yes, this guy was actually that blunt about his plans.
While my evidence is slim, I believe this particular person is a Russian spammer or hacker looking to add malware into the plugins and get this code onto as many sites as possible before we put a stop to him.
What can I say? WordPress is a big target. Some are going to try to abuse the system. We’re used to that. Now you plugin authors will need to get used to it too, because you can be a target for this sort of thing as well.
People offering to buy your plugin are generally spammers. They’re probably using fake email accounts, and offering you false information as well. They may be able to pay you, but understand that what they’re looking for is to buy heaps of unrelated plugins, modify them all with SEO spam like backlinks or potentially even malware, and get our systems to push those things to as many sites as possible before we notice and shut them down hard.
Do you really want to sell your plugin to somebody like that? Do you want your hard work to be abused and to have your good name tarnished?
Think twice before selling your plugin. Know the person you’re selling it to very well. Ignore unsolicited emails from people you don’t know. If they are going to pay you based on the number of “Active Installs”, then just don’t even consider it.
Don’t worry about the plugin review team too much though. We can find and shut these things down very quickly, even in real-time. But it does help us quite a bit if you ignore these types of scammers too. 🙂
But if you do decide to give your plugin to somebody responsible and real and who actually cares about it, make sure they know about the Plugin Directory Guidelines. Because hosting a plugin in the WordPress.org Plugin Directory is a privilege, not a right. We can and will act to remove and stop plugins in our systems from doing bad things, no matter who “owns” them.
Every once in a while, somebody pings me to say that their plugin isn’t showing up properly in the directory. Almost always it’s a problem with the plugin itself having incorrect information somehow. So I thought I’d do a quick post to explain some aspects of the plugin directory, and explain some of the more obvious stuff which a lot of people miss.
First, let’s briefly go over the layout of your plugin in the SVN repository. There’s three directories created by default, and an optional fourth one that you can create yourself.
Trunk: The /trunk directory is where your plugin code should live. The trunk can be considered to be the latest and greatest code. It’s the development version. Hopefully, the code in trunk should always be working code, but it may be buggy from time to time because it’s not necessarily the “stable” version. For simple plugins, the trunk may be the only version of the code that exists, and that’s fine as well.
Tags: The /tags directory is where you can put versions of the plugin at some specific point in time. Usually, you’ll use version numbers for the subdirectories here. So version 1.0 of the plugin would be in /tags/1.0, version 1.1 would be in /tags/1.1, and so forth. Again, not every plugin uses tags for versioning.
Branches: The /branches directory is a place that you can use to store branches of the plugin. Perhaps versions that are in development, or test code, etc. The WordPress.org system does not use the branches directory for anything at all, it’s considered to be strictly for developers to use as they need it.
Assets: The last optional directory doesn’t exist by default (Edit: It does now, older plugins may be missing it, but all newly added plugins will get it by default.) You can create it yourself though. Just make a directory called “assets” next to those other three directories. Assets currently only has one use, which is to store the banner image to be displayed on your plugin page. We may use it for more things in the future. For now, you can just make an image, name it
banner-772x250.jpg, and put it in there. Easy.
Additional Info: Since creating this post, some new files have been added to the assets folder. You can create a
banner-1544x500.jpg now too. This high-resolution banner will be shown to users with high-resolution displays, such as phones or tablets or certain newer laptops. Additionally, screenshots which once lived in the plugin’s own directory can now be moved from there into the assets directory. This allows the screenshots to be shown on the plugin page, but not included in the download of the plugin, reducing file size. It’s recommended to put screenshot files in /assets.
All plugins contain a main PHP file, and almost all plugins have a readme.txt file as well. The readme.txt file is intended to be written using a subset of markdown. The example readme.txt explains most everything pretty well, but there’s a few little tidbits that are worth pointing out.
First is the concept of the “Stable Tag”. When WordPress.org parses the readme.txt, the very first thing it does is to look at the readme.txt in the /trunk directory, and then read that “Stable Tag” line. If the Stable Tag is missing, or is set to “trunk”, then the version of the plugin in /trunk is considered to be the stable version. If the Stable Tag is set to anything else, then it will go and look in /tags/ for the referenced version. So a Stable Tag of “1.2.3” will make it look for /tags/1.2.3/.
Important bit: Everything else is read from this new location. If the Stable Tag is 1.2.3 and /tags/1.2.3/ exists, then nothing in trunk will be read any further for parsing by any part of the system. If you try to change the description of the plugin in /trunk/readme.txt, and Stable Tag isn’t trunk, then your changes won’t do anything on your plugin page. Everything comes from the readme.txt in the file being pointed to by the Stable Tag.
Now let’s get to the plugin information itself. The WordPress.org directory reads the main plugin PHP file to get things like the Name of the plugin, the Plugin URI, and most importantly, the version number. On the plugin page, you’ll see the download button which reads “Download Version 1.2.3” or similar. That version number comes from the plugin’s main PHP file.
Some people get this versoning confused due to the tags system. The Stable Tag points to a subdirectory in the /tags directory. But the version of the plugin is not actually that, it’s the version that is listed in the plugin’s PHP file itself. If you have changed Stable Tag to 1.4 and the plugin still says 1.3 in the PHP file, then the version listed will be 1.3.
Back to the readme.txt. There’s a line called “Contributors”. This line has always been expected to be WordPress.org usernames only. WordPress reads those, gets information about that user, gets their gravatar, name, etc, and makes the authors listing. If you put anything here that’s not a WordPress.org username, then it doesn’t look nearly as good. No picture, no link, just text.
Other information in the readme.txt is read and used at various points on the Plugin listing. The Donate link makes a “Donate to this plugin” link in the sidebar. The “Requires at least” and “Tested up to” fields are used for compatibility checking, even on the WordPress installation itself. Few people get these wrong.
One thing a lot of people get wrong is this line:
“Here is a short description of the plugin. This should be no more than 150 characters. No markup here.”
That bit is serious, and you should read it again. That one line people get wrong more often than anything else. That line of text is the single line description of the plugin which shows up in big letters right under the plugin name, and if it’s longer than 150 characters, it gets cutoff and makes your plugin page look silly.
Markdown allows for easy linking in your readme.txt as well. Just write like this to link a word to a URL:
Videos can be put into your readme.txt too. A YouTube or Vimeo link on a line by itself will be auto-embedded. It’s also possible to embed videos hosted on VideoPress using the wpvideo shortcode. More on that topic here: http://wpdevel.wordpress.com/2010/02/20/plugins-can-now-include-videos-in-their-readme-txt-files/
I don’t think I covered everything, but hopefully that will explain some of the more obscure features of the directory and how it works. If it reduces the number of times people send me the question “why didn’t my version change show up in the directory”, then I think this post was time well spent. 🙂
Matt just announced on the WordPress Blog — and many of you have already noticed — a number of recent changes to the plugin directory, profiles, and the support forums. Now let’s go into detail all of the individual changes, and what it means for plugin developers.
We’re glad to see so many of you use the plugin headers we launched in December. Now, we’ve provided a further refresh. We’ve made authors much more prominent and with bigger Gravatars and better placement, and cleaned up the styles for the ratings, support, and compatibility sections. There’s a great before-after shot in the announcement post.
In the past, creating new support topics for plugins has been special, and not in a particularly good way. It had this specialness by overloading the tags in the support forums to indicate that a thread was about a particular plugin. No longer. We’ve promoted plugins up a notch and given them their own area.
So now, on your plugin pages, you’ll see a “Support” menu in the header, and you’ll see the topics for that plugin in that tab. You’ll also find a submission form at the bottom of that tab, to add new support topics specifically for your plugin. Topics about plugins made from here get a special sidebar with links to the plugin, to the plugin’s FAQ page, and to the list of Support Threads for that plugin.
While this section looks like it’s on the Plugin’s page, it’s not really. These support threads are actually in the same place they’ve always been, in the Support forums. What you’re seeing as far as the look and feel of that view of the support forums is just some clever trickery on our part. 🙂
Akismet, for example, will have it’s “support forums” at this URL: https://wordpress.org/support/plugin/akismet.
You may want to take advantage of this by subscribing to the RSS feed for your plugin: https://wordpress.org/support/rss/plugin/akismet. Email subscriptions are not available for these yet, but we will be adding them this week.
For plugin authors who have been using them, the old convenience views of plugin-committers and plugin-contributors are still there as well. (Committers are managed in on the Admin tab, while contributors are taken from readme.txt.) We’ll be exposing these links in more places, but you can use them with URLs similar to the following: https://wordpress.org/support/view/plugin-committer/Otto42 https://wordpress.org/support/view/plugin-contributor/Otto42. (RSS feeds exist for these as well.)
You’ll notice a new area on the plugin page sidebar showing information about how many topics there are for your plugin, and how many of them have been marked as resolved. These are handy for users to see if questions are likely to get a response.
You have had the ability to mark plugin support threads as resolved for some time now. It’s now really easy — you can mark a thread as resolved while making a post with a simple checkbox. Note that the user who opened the thread can also mark threads as resolved and unresolved. Threads that are marked “Not a support question,” such as suggestions or feedback, are not counted toward these stats and do not need to be marked resolved.
Statistics will be based on a rolling two-month period, based on when the thread was opened. Currently, the statistics cover threads opened in the last two weeks, and will continue to increase until it reaches two months, to allow you some time to resolve existing threads.
You can now make threads “sticky” threads to the top of your plugin’s support forum, just like the other forums on WordPress.org. (You’ll find a link “Stick topic to this plugin’s support forum” in the sidebar.) Threads marked as sticky will show at the top of your plugin’s Support tab. (They won’t be sticky on the regular forums.) We hope you find this handy for posting FAQs or other important information about your plugin.
Every plugin now has a Developers tab where you can find links for browsing the code in Subversion, the development log, and development versions. Here, you can now subscribe to get an email whenever a commit is made to a plugin repository, even if it isn’t yours. (You will of course continue to receive commits for your own plugins.)
As I’m sure you’ve now seen, plugins can now be favorited by logged-in users — and have been more than 2,000 times since we soft-launched this feature earlier in the week! When you favorite a plugin, it gets added to your profile. And if you’ve also rated that plugin, your rating gets shown.
We expect to do a lot more with all of this in the future — favorites, plugins, support, and profiles. Until next time, we hope you enjoy these changes as much as we do!