I recently submitted my first free theme to WordPress.org.
Kent is a theme I made for wordpress.com. It’s been code reviewed by the team there and is in use on a few hundred sites. I was considering selling it on Creative Market, but instead decided to add it to wordpress.org and try to use it to build some brand awareness for my premium themes.
Since the theme had been reviewed by the wordpress.com team I knew the code was solid but unfortunately the review didn’t go quite as smoothly as I had imagined.
Theme Check Errors
I first attempted to submit the theme on the 1st of July. However it failed on the theme tags. I was aware of the theme tags because they also use them on wordpress.com – however as I found out – the allowed tags are different between .com and .org.
The only reference I could find to the allowed tags for wordpress.org was a short comment on the theme development page on the codex that said to find the theme search filter on wordpress.org and use the tags there. I have since found the correct list of allowed tags in the Theme Review Handbook and updated the Codex to point to the right place.
Submission Successful
Once the tags were correct I got an email saying I had been entered into the queue. I then heard nothing for 4 weeks – until I was given a reviewer. Reviewers have 7 days to submit the review – before it gets handed to another reviewer. Unfortunately my reviewer waited until the 7th day before they submitted my review. I was a little disappointed with this since I could see themes that were submitted after mine being reviewed. Thankfully there were only a few small bits of feedback (including a bug) one of which was about links in the theme that pointed to my site.
Disallowed Links
One of the things that was commented on was that I had a link in the footer of the theme. This is standard practice – and is allowed, but I wanted to check the docs to be sure. The Theme Review Handbook documentation for theme links, however, is lacking. It currently has 2 sentences on it, neither of which say what urls are allowed.
A bit more Googling and I found the following page on the theme review blog which has a comprehensive set of rules. Unfortunately the page also says it’s deprecated and you should use the new one that has no useful information on it.
Submitting Changes
Once I knew what I had to change I was able to make the changes quite quickly and then had to work out how to submit them.
There was nothing saying how to upload changes, however I am used to updating plugins on wordpress.org – so my first instinct was to look for an svn repository. There’s one linked in the trac ticket so I assumed I should use that – however that’s wrong, it didn’t work. So next up I uploaded the changes to the ticket.
I then got a message from the reviewer saying the theme should be uploaded through the theme uploaded – the same way it was submitted initially (on this page). The theme upload page is designed for those uploading a theme for the first time. I had considered re-uploading the theme through this page – however I assumed that if I did I would be put to the back of the queue and have to start again.
Thankfully it worked and after a bit more back and forth I got the all clear.
Review Passed
Awesome – my theme was reviewed, I just had to wait for it to be approved. I had assumed this would be fairly quick – however I have since found out you have to wait for a senior reviewer to check over the theme before setting it live. This took another 4 weeks – but my theme, Kent, is now live. Yay! 🙂
Theme Review Feedback
I should preface this with the fact that I know it’s a free service and many of the people involved are doing these reviews in their free time for no pay. As such I intend the feedback to be seen as constructive. My intention is to give feedback from the perspective of a first time submitter – in the hope that the process can be improved for others.
- When a theme is uploaded it goes through the Theme Check plugin. Notes are added about problems but there are no explanations as to how to fix the issues. I think adding adding links to the relevant places on the Codex/ Theme Handbook would help people to fix their issues more quickly.
- The Theme Review Handbook has a few problems. Firstly it seems to be targeted at reviewers – not developers – so it could be made more generic so that developers have a clearer understanding of what’s needed. Secondly – it’s not complete (as the theme links example shows), removing the deprecated notice from content that is still useful and then linking to the old docs from the handbook would be a good stop gap and help people to find what they are looking for more easily.
- One of the things I found a bit frustrating is that there was a lot of waiting, and not knowing. A simple automated email – once a week – telling me my position in the queue(s) would have done a lot to alleviate that.
- Adding an obvious link on the Theme Review Trac that clearly shows where to upload changes/ updates to the themes would have saved me a good bit of time.
- I don’t think the initial review should have taken a week. Once we got going the reviewer was polite and prompt – but he was clearly busy when he first accepted it. I think changing the initial review time to 24 hours would be a lot better for everyone. I can’t see a reason for someone to accept a theme for review and then not review it – if someone doesn’t have the time, they should wait until they do.
Conclusion
I’ve now submitted the first update to Kent – my WordPress.org theme – and I have plans to submit a couple more themes. The process was convoluted but not impossible and with a few, mostly small, tweaks could be made a lot smoother to ease the process for everyone.
Was it good/ useful/ a load of old rubbish? Let me know on Mastodon, or BlueSky (or Twitter X if you must).
Link to this page
Thanks for reading. I'd really appreciate it if you'd link to this page if you mention it in your newsletter or on your blog.