How not to update a WordPress plugin

The meaning of this post’s title is twofold: 1) how, as a WordPress user, to avoid having a plugin show up in the built-in updater; and 2) how, as a developer, you probably should not approach releasing a major update to your plugin that is incompatible with earlier versions.

The scapegoat here is Elliot Condon’s excellent Advanced Custom Fields, which has become one of my essential go-to plugins for building highly customized WordPress websites for my clients. I don’t mean to pick on Elliot Condon. He’s clearly a tremendously talented developer and I have a ton of respect for his work and what it has allowed me to do in my work.

But I do feel that he handled the 4.0 release of Advanced Custom Fields poorly. I’m not sure the fault is really his, however, as it is just as much or more the fault of how the built-in updater in WordPress works. (Especially since at least some of the changes he made in version 4 were done solely to conform to changes in the official WordPress plugin requirements.)

Here’s the problem: WordPress has a central Plugin Directory that makes it easy to install and update approved plugins. Perhaps too easy. Because if an update of a plugin is made available, and it’s newer than the version you have installed, it appears as an option in the updater. Yes, there are links to information about the update, which you really should read before doing anything else, but it’s all too easy with a few clicks to just run the update and move on.

Most of the time, it just works. Which can be dangerous. Because users — even “experts” like me — come to assume it will always “just work.”

As it happens, the version 4.0 release of Advanced Custom Fields was made available while I was on a weeklong vacation out west with my family, with only my iPad (and SLP’s MacBook Air) along for the ride. And, based on my own recommendations, a client with a relatively newly-launched website went ahead and ran the update. This particular site is heavily dependent on ACF, and the update broke it.

The official ACF website offers a migration guide that makes it (somewhat) easy to convert your existing version 3 implementation to work with version 4. But it’s not a “click-it-and-you’re-done” kind of process. It takes time, and you need to know what you’re doing. Which is nothing like the general experience of using the built-in WordPress updater.

I was able to temporarily solve the problem for this website by rolling back to an earlier version (which required some hunting to locate, given the limited Internet access I had with hotel WiFi). Which leads to my first tip:

How to prevent a WordPress plugin from updating

How does WordPress know when a plugin has an update available? Well, it’s easy for it to check the Plugin Directory to see what the latest version of any given plugin is. But how does it know which version you have installed? Also easy. Each plugin’s main PHP file includes a comment block at the top, with information WordPress parses both to display in the Plugins area of the admin interface and for added functionality (e.g. knowing when there’s an update available). For Advanced Custom Fields, the comment block looks like this:

/*
Plugin Name: Advanced Custom Fields
Plugin URI: http://www.advancedcustomfields.com/
Description: Fully customise WordPress edit screens with powerful fields. Boasting a professional interface and a powerfull API, it’s a must have for any web developer working with WordPress. Field types include: Wysiwyg, text, textarea, image, file, select, checkbox, page link, post object, date picker, color picker, repeater, flexible content, gallery and more!
Version: 3.5.8.2
Author: Elliot Condon
Author URI: http://www.elliotcondon.com/
License: GPL
Copyright: Elliot Condon
*/

This is essentially a set of key/value pairs. Version is what WordPress reads to see which version you’re running, and compares it against the master version in the Plugin Directory to see if updates are available.

So how do you keep it from running the update? Simple: Change the version number to something higher. I like to prepend it with “999” so I still know what the “real” version number is that I’m running, like this: 999.3.5.8.2. This way the WordPress updater thinks the major version is “999”, which is almost certainly higher than whatever the real current version is.

Simply change this version number, save the PHP file on your server, and you’re done. The updater will never trigger for this plugin (as long as its real version number is less than 999). You may also want to update Description with an explanation of what you’ve done.

Bear in mind this is a temporary solution. You really should do whatever you need to do to get your site compatible with the latest version, then restore the original version number and let the updater do its magic.

How, as a developer, not to create this mess for your users

I have submitted a few, very simple, plugins and themes to the official WordPress repositories, so I have a bit of experience with this, but I’m no expert on the process. However, what is clear to me is that if you submit changes to a plugin as an update, the built-in updater will pick it up and make it available to any users who have an older version installed. This is dangerous. If your new version includes such radical changes as to make it incompatible with earlier versions, you have to assume that most users will not read your notes, and will believe they can just run the updater with no problems… especially if you’ve made a habit of releasing frequent incremental updates to the plugin in the past that “just worked.”

The only real solution I see to this is to submit the new, incompatible version to the Plugin Directory as an altogether new plugin, instead of an update to the existing plugin. The risk here is that you lose visibility. Your download count and ratings/reviews reset to zero, and anyone who’s using an older version may never know about the new version. So, it’s bad for marketing.

But an incompatible update breaking sites for unsuspecting users is bad for marketing too. It’s going to cause your ratings to take a hit, cause a lot of bad publicity, and turn off your loyal users. The migration is going to be work for them anyway; making them do it after they clean up a mess created when they unsuspectingly ran the update is even worse.

A few specifics as pertains to Advanced Custom Fields

Again, I don’t mean to pick on Elliot Condon for his work with Advanced Custom Fields. I will continue to be a loyal (and, yes, paid) user of this plugin. It’s brilliant. Nonetheless, it’s created a hassle for me this week. After returning from my trip, the first work-related thing I did was go through every client site that’s running ACF and apply my “version 999” trick so those clients won’t run the updater until I have a chance to migrate their sites to version 4.

The biggest challenge I had in rolling back was simply getting my hands on the old version. Sure, I had it on some of my other sites, but I access almost every client site via SSH/SFTP, and the hotel I was staying at had port 22 blocked. Luckily the site I needed to fix was one of the few I access via regular FTP, and port 21 was open. But I still needed to get a copy of version 3.x to reinstall on that client’s site.

As I found along the way, the WordPress Plugin Directory hides old versions under the “Developers” tab, where every previous version can be downloaded as a ZIP file or checked out with Subversion. Previous versions of ACF are available here.

A childhood fantasy (almost) realized: 100 Atari games in my pocket

Owners of 1980s technology intellectual property are in an unenviable position. Their IP has very little value beyond historical significance or nostalgia. No one (well, I hope no one) is going to use an Apple IIe computer for serious productivity work these days, but that doesn’t diminish its importance in computing history, nor the strong positive memories its once loyal users may still hold onto.

There are few properties from the ’80s whose value is more purely historical and nostalgic than those bearing the brand of Atari. Sure, there’s still a company today named Atari, and it still makes modern video games for modern consoles, but this Atari shares only its name with the hallowed institution founded in Sunnyvale, California in 1972. The name and all of the properties that go with it have been sold and re-sold and re-re-sold so many times over the intervening years that any minute connection to the past, beyond the games themselves, has been lost.

So, what is a modern company that owns all of this (relatively speaking) useless IP to do? Trying to cash in on it is obvious, but doing it right is a huge challenge. The biggest hurdle is the very historical significance and nostalgia that give these games any lingering value in the first place. The only people who are really going to want to play Combat or Yars’ Revenge or — ah-hem — Math Gran Prix on an iPhone are people who either owned (and played the hell out of) these games as kids 30 years ago, or their kids, who harbor a morbid curiosity about this old crap their parents like for some reason. In order to satisfy these customers, the company that now calls itself Atari needs to achieve perfection in recreating the experience people remember. Not just the graphics and the sounds and the program mechanics of the games, but the feel… the essence of what it meant to play video games in the days when Ronald Reagan was president, pastels were popular in men’s fashion, and MTV still showed music videos.

Yesterday Atari released Atari’s Greatest Hits as a universal app for iOS devices. (To the non-nerd[s] in my audience: that means the same app works on iPhone/iPod touch and iPad.) The game comes free with arcade Pong, and 99 other classic (and not-so-classic, but… well… old) Atari games, both from the arcades and for the Atari 2600 VCS, available as in-app purchases. The games are sold in packs of four for 99 cents, or the entire set can be downloaded for $14.99. Let’s be serious: anyone who cares about this at all should just get it over with and download the works, immediately.

So did Atari live up to my unrealistic expectations? Read on after the screenshot gallery to find out.

First impressions

It’s clear from the moment you load Atari’s Greatest Hits on your iPhone or iPad that a great deal of attention and care went into putting this package together. And yet, it just doesn’t quite hit the mark. The graphic design of the menu interface bears plenty of superficial nods to the vintage Atari experience: plenty of use of Bauhaus font (the font Atari used with the original 7 cartridges released with the Atari VCS in 1977), lots of browns and oranges, and of course the carousel navigation that uses the original cabinet and/or game box art to help you select a game to play. But despite fonts and colors, this doesn’t look ’80s, and it certainly doesn’t sound ’80s. The entire time you’re on the menu, loud 21st century techno music booms from your speaker. To be fair, I like this kind of music, and the music they chose is decent. But it’s a distracting anachronism.

I compare this to the Williams Pinball Collection that came out a few years ago on the modern consoles. Its interface looks like an arcade, with the pinball tables lined up along the wall, and over the din of a dozen pinball machines blasts licensed ’80s popular music. (The song that stands out for me is the quite-possibly-perfect Loverboy hit “Workin’ for the Weekend.”) This is what I would have liked (if not downright expected) in a properly executed Atari collection.

Lamentations about “what could have been” aside, it is truly great to see the original game box art and arcade cabinets on the menu, and the menu itself is intuitive and fun to navigate. And it’s great that each game also includes a full high-resolution scan of the original instruction manual, which also explains why a collection of 100 games, most of which were only about 4 KB each on the original cartridges, could add up to a 68 MB download on iOS.

The sound and the fury

There was almost no question for me which game I would try first: Yars’ Revenge. I logged hundreds of hours (sometimes in a single game, it seemed) playing this game in the ’80s, long past the date when I should have moved on to the NES or PC games. Any true Atari retro experience needs to deliver a perfect rendition of Yars’ Revenge for me to consider it a success.

I started the game, picked my favorite game variation (Game 6), and then… WHAAAAA!!! Playing the game on my iPad, I was assaulted by hideous distorted grinding noises. I tried a few other games and confirmed that all of the 2600 games had horribly distorted sound. (It also didn’t help that Yars’ Revenge gets most of its intensity from a constant droning buzz, making this quite possibly the worst game I could begin this experience with.)

Fortunately, later in the evening I loaded the game onto my iPhone 3GS, and found absolutely no sound issues with the 2600 games, even Yars’ Revenge. So I’m not sure if this is a general issue with the game on the iPad, or if it was an isolated problem that could have been resolved with a reboot. I’ll follow up on that when I know more.

Playing the game

With my worries about sound allayed, I was able to focus my attention on the quality of the game experience. All of the games are presented in a relatively small area of the screen, with ample space above and below devoted to on-screen controls. There have been some complaints in App Store reviews about the games not using the full display, but I think those complaints are misguided. These Atari games in their original form were so low-res that even when shrunk down to a little less than half the size of an iPhone screen, they’re still easily viewable. Plus, displaying the games in full-screen mode would mean you’d need to obscure part of the display with your fingers in order to control the game. Unacceptable.

The developers and designers who worked on this collection put considerable thought into translating the original game controls to on-screen counterparts that do not necessarily mimic the original feel, but that usually (but not always) contribute to a satisfying game experience.

A good pair of games to consider in reviewing the merits of these control systems are the arcade versions of Asteroids and Tempest. Both games translate quite well to the iOS experience. They look fantastic (all of the vector games, in particular, come through well here), and are just as fun to play as ever. With Tempest, the original control mechanism was a flywheel-like spinner. That is replaced with a thumbwheel that reminds me of the volume controls on old transistor radios. It’s way different from the original control, but it feels surprisingly natural and it’s very easy to adapt to this type of play.

Asteroids, on the other hand, does not benefit from this new alternate control mechanism, at least for the way I like to play the game. (I should probably note that I own an actual Asteroids cocktail table, so I’m very accustomed to the arcade controls.) The default control mechanism is a combination rotate/thrust “disc,” not unlike the disc controller on an old Intellivision. (Intellivision controls on an Atari game? Blasphemy!) Some people may prefer this, but I found it absolutely unusable, mainly because of my preferred Asteroids playing style: I don’t thrust all over the screen. I stay in one spot and just rotate, and I move around only when absolutely necessary. The disc control makes it nearly impossible, for me at least, to rotate without thrusting. Luckily, Asteroids (and apparently most of the arcade games, though I haven’t tried them all yet) offers multiple control schemes, including the original arcade-style five-button configuration. This worked well for me on the iPad, but I didn’t try it yet on the iPhone, and I imagine size could be an issue there, not to mention just holding the iPhone while fiddling with five on-screen buttons at the bottom of the display.

A few other miscellaneous game notes:

No licensed games. This was a no-brainer for me, but apparently (based on reviews on the App Store) it’s confusing to some users. This collection only consists of games Atari owns the rights to. That means games that were licensed for the original Atari 2600 won’t show up here, not even if Atari developed those games. You won’t find arcade classics like Pac-Man, Space Invaders, Defender or Berzerk, and you won’t find licensed movie properties like Superman, Raiders of the Lost Ark or E.T. And you definitely won’t find games that were originally released by other game companies like Activision, Imagic or Parker Brothers. Although… one wonders. Atari licensed Pitfall! and River Raid from Activision for inclusion on the plug-and-play Atari Flashback 2 console a few years back. Maybe a similar license could be in the works. It wouldn’t be difficult for Atari to offer additional in-app purchases of more games in the future.

I think the funniest instance of licensing issues popping up here though is the matter of Pong Sports. Back in the ’80s Atari manufactured the 2600 and a number of its games under special branding for sale at Sears stores, and there were three Sears exclusive titles (Steeplechase, Submarine Commander and Stellar Track), all of which are included here. And then there’s Pong Sports. Atari released this game as Video Olympics, and sold it as Pong Sports in Sears stores. But here it’s called Pong Sports, presumably because they couldn’t get the rights to use the word “Olympics” this time around.

Unreleased and homebrew games. If you’re not a hardcore Atari fanatic, you probably don’t realize that in recent years a number of unreleased prototype games have come to light as downloadable ROMs to play in computer-based Atari 2600 emulation software. And a rabid homebrew community has developed as well, creating brand new games for the system. This collection includes a few of these prototype and homebrew games, such as the Atari 2600 version of Tempest and an unreleased game called Save Mary. I find it funny that Atari had to, of course, come up with box art for these games for the menu interface, and they went with some really low-quality homemade art for most of them. But Save Mary is the weirdest… it uses the cover art that originally went with the Atari 2600 BASIC Programming cartridge.

It’s also funny… and probably an intentional joke… that for these games, the manual scans that are displayed are not for the games (since they don’t have instruction manuals) but for the Atari 2600 console itself. Somewhat of an Easter egg, I think.

God (or is it the devil?) is in the details

Atari got a lot of things right with this collection, but there is definitely room for improvement. Here are a few things that come to mind, some of which I’ve already mentioned.

License some great ’80s music for the menu. The aforementioned Loverboy hit would certainly be great, but really just about any music that was in heavy rotation on MTV circa 1983 would work. Personally I’d love to hear plenty of Duran Duran and Men at Work.

Alternate control schemes for the 2600 titles. Here’s the one thing that I think would make the biggest difference in creating an authentic Atari 2600 experience: position the on-screen controls to better mimic the feeling of holding an old CX-40 joystick. The space is already there; they’d just need to rearrange the controls. Move the fire button to the upper left where the pause button is; move the d-pad to the lower right where the fire button is; and move the pause button to the lower right where the d-pad is. Holding a square-ish device in the left hand and pressing a button with one’s left thumb while using one’s right hand to control movement is the natural way of the Atari 2600 experience. Ideally the d-pad would be tweaked a bit as well… it’s a little too restrictive feeling. A lot of iOS games with a virtual d-pad allow you to place your thumb anywhere in a general region of the screen and that instantly becomes the “zero” position of the d-pad. I suspect (or at least hope) that, given the nature of iOS apps, Atari will continue to refine the controls in future updates.

Better “cabinet art.” I have to be honest… I can live with the graphic design of the main menus, but the graphics framing the game itself while in play are downright ugly. Better to have it look like an actual vintage TV set like VH1’s (yes, VH1’s) Intellivision collection for iOS. And I’d prefer that the on-screen buttons look exactly like the real buttons on the arcade cabinets and console controllers, without the unnecessary added visual junk. It also seems like they phoned in the design of the on-screen slider for the paddle-based games. (Why doesn’t it at least look like the control they developed for Tempest?)

Final thoughts

I could nitpick details only an OCD Atari junkie will notice, much less care about, but in the end there’s only one thing I can say about this collection. Back in the early days of the App Store, Atari released a few of its classic arcade games as standalone apps, each consisting of both the original and a new version with modernized graphics and sound: Centipede, Super Breakout, Missile Command. Then they disappeared, and were gone for ages. A month or two ago, they reappeared, but with only the modernized portions. For ages I’ve been speculating that Atari had a massive collection app in the works, and finally yesterday it arrived. I was absolutely giddy. And while it will probably never fully live up to my expectations, it’s damn close. I’ve dreamed ever since I first got my Atari 2600 console in 1982, when I was 8 years old, that one day I’d be able to carry the experience around in my pocket. And now I can… almost. It’s not perfect, and it couldn’t be. But I’ll take it anyway.

When nothing really isn’t nothing

I’ve spent the better part of the past two work days trying to figure out a weird scenario where a few elements in a heavily CSS-based page layout are inexplicably shifting a few pixels to the right. It is generally happening in pages that have content in the left column, whereas pages that do not have content in the left column are displaying normally. However, there are a few pages with empty left columns that still don’t display correctly. Comparing the source code, I discovered that some of the empty left columns nonetheless contain comment tags and those comment tags are what seems to be making the difference. But strangely, it’s the pages that have left column content or have completely empty left columns that are breaking, whereas the only ones that are not breaking are the ones where the left column block contains only comment tags.

Once again, the mysterious Microsoft voodoo amazes and confounds me.