Yesterday, we released Easier Excerpts 1.1.0 into the WordPress plugin repository.
In short, this update includes a lot of updates to the code of the plugin without a lot of user-facing functionality. But it does lay the foundation for future updates to this plugin along with how we’re going to be building plugins that we’ll be releasing moving forward.
Easier Excerpts 1.1.0
Though we cover a bit more about the plugin itself in the official blog post, I thought I’d cover more technical details of the changes in this post.
The official post contains the following statement:
Far too often, installing plugin updates is a set of unclear notes about what’s new and is a gamble as to if they will break when they are installed.
The changelog is also available for review in the WordPress Plugin Repository. Though I’m not a fan of changelogs that contains messages like:
Bug fixes and performance improvements
I also know that highly technical changelogs are just jargon to the end user. This may sound a little weird given that this latest update includes many technical details.
But I’m okay with that given that it’s the first plugin, and we’re working on defining an approach for how we’ll be moving forward with this plugin as well as our future plugins.
The gist of the changes are that:
- We’ve begun using Composer for our dependencies which, for this version, include PHPUnit.
- We’re using WP-CLI and associated tools for writing server-side unit tests for the plugin.
- There are code-level improvements for making it easier to test and easier to read.
For the typical end-user, these types of changes will not impact the performance of the plugin, nor will it introduce any new visual element.
It will, however, make it possible for us to add features in the future in a way that won’t cause problems with pre-existing features. That is, unit testing allows us to write new tests and new code all the while running tests that we’ve previously written to make sure that nothing breaks with the new code.
Furthermore, using dependency management and command-line level scripts via WP-CLI allows us to continue making sure the plugin includes only the files that are needed but allows us as well as other developers to set up the environment needed for testing and for forking the plugin if needed.
If you’re a developer and are interested in setting this up, you can see the instructions for how to do this by following the instructions on this page.
Finally, this is the approach that we’re planning to take with plugins that are both free and premium. Speaking of which, we have a few free plugins scheduled for release before releasing our first premium plugin. Naturally, I’ll cover all of this in a future blog post.
For now, though, the updates for Easier Excerpts are available in the repository and also show the approach that we’ll be taking with future work.
Hey Tom,
You seem to use this plugin as a benchmark for your future products, so I wanted to take a quick minute and make a few suggestions (would have submitted PRs, but the code seems to be private on GitHub).
Re. Composer:
Yay! Composer is one of the greatest things that has happened for PHP, and I applaud all WordPress projects that try to bring this wonderful package manager into the WP world, too.
However, for publicly released plugins, I would strongly recommend that you only
require
packages that are under your own control. For the uninitiated here on the blog, Composer is meant to have 1vendor
folder per SITE, where it manages its dependencies. If you use it with plugins, most users will end up with 1vendor
folder per PLUGIN, so eventually multiple ones. As PHP classes can only be loaded once, the first plugin using a package will win, and any other plugins might get the wrong version and produce unexpected behaviour. No issues for development dependencies, though. You seem to only use Composer for development dependencies so far, so this plugin here is just fine.Also, as you have a
composer.json
file, you should consider filling out some useful meta information like the package name, and set the"type"
to"wordpress-plugin"
. This will make sure that the plugin gets installed in the correct location if someone is pulling it in within a site-wide Composer installation.I’d also recommend using Composer’s autoloader (eventually with a fallback to provide PHP 5.2 compatibility for WordPress: https://bitbucket.org/xrstf/composer-php52), but that is totally optional.
Re. JavaScript:
You ship both the unminified & minified version of your JavaScript file. I would recommend checking the
SCRIPT_DEBUG
constant and enqueueing the unminified version if it is true: https://pippinsplugins.com/use-script_debug-enable-non-minified-asset-files/ .Although this plugin has very simple and straight-forward functionality, it is obvious that you’ve put a lot of thought into it, and I hope that people examining your code will be able to appreciate how much effort goes into high-quality code, as opposed to quickly hacked-together plugins that cause all sorts of issues down the line.
Looking forward to the next plugin you’ll release! :)
You’re right. I’m not sure if we’ll open the repository on GitHub or not since the target audience is mainly bloggers (and those less technical). Those who are interested in the code can grab it from the repository (obviously :).
Yes — this is something I’ve wanted to begin including in public projects for some time now. It’s just taken an effort such as this to actually get it done. This plugin is kind of the foundation and approach as to what we’re going to be doing with future work, too.
Ultimately, it’s not so much about having a
vendor
directory at the site-level, but it’s about having the necessary tools to spin up PHPUnit and other tools (that will eventually come) whenever someone wants to work on the plugin hence the reason none of that is actually included with the repository. Though, I think you can tell that’s already how I’ve got it set up :).Smart. There are plenty of additional tags I want to add and improvements I want to make regarding the use of Composer but I had to take a pragmatic stance on “when is this shippable?” and “what can be improved?” And you’re seeing the result of trying to strike that balance.
I think this is a good move. I don’t use 5.2 on many (if any) projects I work on, but with widespread use in terms of hosts with plugins or what others may have on their own site, I can’t guarantee any of that. So I think it’s a good move.
This is another once of those things that I’ve sat on the fence about doing. I’m familiar with
SCRIPT_DEBUG
from working with Core and with themes for clients, and I typically don’t bother removing the unminified files from what I ship (because I don’t see them as bloat in something this small) but I’ve never had anyone specifically ask for this potential flag to be integrated into the code.But if I’m working to make this approach as high quality as possible, I think it makes sense to incorporate that. What we’re doing in smaller plugins should be reflected in larger plugins, too.
Bingo. The goal is to have as much quality and testing around even the smallest of functionality so should something arise, I’m able to diagnose my own work and say “Ah, yes I accidentally release the bug that destroyed the header and footer of your site” versus “No, that was Alain’s work that did that.” ;)
Thanks for this comment. Definitely going to be adding this to the roadmap for the next 1.X release of the plugin with props to you for the suggestions.
I’ve been using Composer extensively in all kinds of scenarios for some time now, and it greatly enhances any PHP work.
If you’re mainly looking into automating your development workflow and on-boarding, you might want to take a look at https://github.com/php-composter/php-composter , which is a system to automate
git
hooks through Composer.It is still a very young project, and there are some minor kinks to be ironed out before there will be a first stable release. But it has already proven to be useful to me, and I will shortly release some more actions to go with it.
As you already provide the unminified version, you might as well make debugging life for yourself and your clients easier.
Stop quoting my wife!
Cheers!