If you’re building a WordPress plugin… even a small one, especially a free one… these are things I wish someone had told me to set up from the very start.
None of them are hard. All of them compound.
1. Start logging a db version in the wp_options.
Add a {your_plugin}_db_version option from day one. You might not need it yet. But at some point, you will absolutely need to run a script on update (migrating data, renaming a meta key, restructuring a table). This option is your safety net. Without it, you have no truly reliable way to know what version a site was on before the update ran. Future you will be very grateful.
2. Have a sales site. Even if your plugin is free.
I don’t mean a landing page. I mean a real site with docs. Put your documentation there and secure it behind a free signup. We use Paid Memberships Pro for this (obviously), and it works incredibly well for this exact use case.
You start capturing email addresses from your free user base from day one. That audience is gold and you have no way to reach them without it.
We take it a step further with our Limit Post Views Add On as a leaky paywall. Bots can crawl and index the doc pages (hello SEO), but real humans get one free view and then hit the signup wall. Free to sign up, zero friction, and now you have a direct line to your users.
3. Use a .github folder with issue and PR templates.
I’m writing this assuming you’re open sourcing your code and your repos are public on GitHub. Not everyone does this (even some of the biggest names in WordPress who claim a GPL v2 or v3 license aren’t putting their repos public).
But that’s another conversation I have big opinions on….
What I mean is giving users a structure when they log an issue or submit a pull request. Define your issue types. Create PR templates. It keeps the garbage out and helps you triage faster. When someone has to fill in a structured template (steps to reproduce, expected vs. actual behavior, environment details) you get useful information instead of “it’s broken, please fix.”
And maybe lazy people just using GitHub for support will feel overwhelmed and skip it.
4. Prefix everything aggressively.
Functions, hooks, meta keys, CSS classes, REST routes… all of it. From day one. This isn’t about being neat, it’s future-proof (yet again). We learned the hard way that passing an unprefixed level parameter caused a conflict with another plugin. Now everything is pmpro_level, pmpro_this, pmpro_that.
The cost of prefixing is almost zero. The cost of a naming collision in production is a support nightmare you can’t easily undo.
5. Make your README.md a showcase, not a manual.
Your GitHub README is a first impression. Add an image. Make it fun. Show people how to contribute, how to report bugs, where to find docs. But don’t turn it into a how-to guide. You don’t want to maintain docs in multiple places. Keep the README as a marketing and onboarding space. Let it sell the project and point people in the right direction.
6. Stop overcomplicating where your JS and CSS load.
This one has gotten so overhyped. “Your plugin should only load its assets on its own screens.” Sure, in theory. But guess what: you have almost no control over what “your screens” are anymore.
Search results? That’s your screen now if your content can show up there. A Query Loop block in core pulling in your CPT? That’s your screen too. A shortcode someone dropped into a random page? Yep.
Meanwhile, CDNs and object caching mean your assets load once in a user’s experience, get cached, and are quick to load from that point on. There are much bigger things to worry about than conditionally loading your stuff.. Unless you can be absolutely sure it should only run in one place. And most of the time, you can’t.
These aren’t revolutionary. They’re boring. But boring is what keeps a plugin maintainable when you’re 18 years in and have tens of thousands of sites depending on you.
