Uploading a Child Theme to the WordPress.org Theme Directory

I wanted to give a short overview of my experience uploading a child theme to the WordPress.org Theme Directory. I’m sure a decent amount of this advice is documented somewhere, and most of it was first-time-don’t-know-what-I’m-doing user error, but hopefully this might help someone avoid the goofy situation I experienced.

When I first zipped and uploaded Mercury, my child theme for the WordPress P2 theme, I was presented with a ton of errors and a “fail” notice from the automated theme checking system.

Most of the errors had to do with missing theme files. This made sense because it was a child theme and wouldn’t contain most of the files the checker was looking for. The problem was it wasn’t obvious (to me at least) that those errors were okay to ignore.


The only error that really seemed to matter was the one at the bottom, with a notice that said “There is no theme called ‘p2-wpcom’ in the directory. For child themes, you must use a parent theme that already exists in the directory.” For some reason, I took “directory” to mean my extracted .zip folder I was uploading, and not the Theme Directory.

You see, for some reason I’d followed a link somewhere to download P2 from http://theme.wordpress.com/themes/p2/, rather than the standard link at http://wordpress.org/themes/p2. The downloaded file I had extracted to a folder named “p2-wpcom” rather than just “p2”, and so that’s what my child theme was using as its parent template name. Because “p2-wpcom” wasn’t in the Theme Directory, I was receiving the doesn’t exist error.

Since I thought the original message was referring to my extracted .zip folder, I simply added the whole parent theme folder “p2-wpcom” in my .zip archive, and re-uploaded. The errors and warnings about missing files went away, the notice at the top said “pass,” but the notice at the bottom about the missing parent theme persisted.

I ended up renaming the “p2-wpcom” theme folder to just “p2” (remember I didn’t know that’s what it was actually supposed to be named yet), and referenced that name in my styles.css file, and the upload seemed to go through. A ticket was made and the Theme Review Team started their review.

Of course they were confused, since I was trying to reference a parent theme name that didn’t exist, and had uploaded the entire parent theme alongside my child theme. To my surprise though, “salsaturation“, the team member that did the review, was super helpful and responsive in helping me get things right. Thank you!

The whole process took over three weeks, though. Even though I fixed the errors they found on the same day, I think the theme team is just overwhelmed with volume. Updated themes, new themes, rejected themes, child themes, etc. I imagine it’s a lot to manage.

So that’s it. After the review and some bug fixes, my first child theme was approved. Mercury is now available in the WordPress Theme Directory and on GitHub.

Leave a Reply

Your email address will not be published. Required fields are marked *