On 12 October we put a free WooCommerce plugin on WordPress.org. By 18 November it had been downloaded 272 times. A paid version of it now exists — and 195 of those 272 downloads happened before any surface anywhere mentioned that it did. Not a weak upsell. No upsell: the word Pro appeared zero times in the plugin, zero times on its directory page, and the paid product had no page of its own on our site either.

The fix took two commits on two days and cost nothing. What it cannot do is reach those 195.

The checklist ran at the wrong moment

We do have a habit here, and on paper it works. Our other two free plugins named their paid version in the first revision of their readme, the day each went into the directory. Nobody had to be convinced that a free plugin should say a paid one exists.

The difference is that for those two, the paid version already existed when the free one shipped. For this one it did not. The Pro was built afterwards — and nothing in the process goes back and reopens the free plugin’s already-published pages when that happens. The checklist fires at launch. A product that arrives later arrives after the only moment anyone was looking.

Here is the actual sequence, from the directory’s own history rather than memory:

DateWhat changedDownloads so far
12 Oct 2026free plugin goes live on WordPress.org—
16 Nov 2026Pro gets a page; the free plugin’s code mentions it (v1.0.6, “tell people the Pro exists”)195
18 Nov 2026the WordPress.org readme mentions it (r3809746)245

Downloads are the cumulative sum of the directory’s own per-day stats API through 18 November 2026, read on 19 November. The readme dates come from svn cat at each historical revision of trunk/readme.txt on plugins.svn.wordpress.org — the public record of what the page said, not what we remember writing. The code date is the commit that first contains the Pro URL.

Two days separate the code knowing and the page saying, and 50 downloads fall in that gap. That is the small half. The large half is the 195 before either, and the reason the two halves are different sizes is that the code change needed a release and the readme change needed nothing at all. A readme-only commit on WordPress.org does not bump a version, cut a release or enter the review queue. It was the cheapest of the three fixes and it went last.

The check that would have caught it, and costs nothing

For each free plugin, grep its own source for the paid product’s URL, then grep every public surface for the same string. The surfaces are small and countable: the directory readme, the product page, and the plugin’s own admin copy. If the URL appears in the code and not on the readme, the plugin is selling something its audience cannot see.

grep -rl "rebelstudiossoftware.com/checkout-brasil-pro" .      # the code knows
grep -c  "checkout-brasil-pro" readme.txt                      # 0  <-- the page does not

The paragraph that went up as r3809746 names what Pro does and what it does not do — it validates a state registration number against the published rule for each of the 27 states, and it does not issue an NF-e. Stating the limit is not modesty; a page that only claims is a page a Brazilian shop owner has read a hundred times before.

What a free plugin page is for

We had been treating the readme as documentation, which is why ours were honest, thorough and silent about money. It is not documentation. It is the only page in the entire funnel that a free user is guaranteed to see, it is the page that WordPress search ranks, and it is the page where somebody decides whether this plugin is a dead end or the start of something maintained. A readme with no paid version in it is not restraint. It is a shop with the till in the back room.

None of which argues for nagging. The notice in the plugin is one line, sitting beside the field whose limit it describes; the readme section is one paragraph in the Description and it says what the paid version cannot do. Both are easier to defend than the state we were actually in, which was a product with a price and no public mention of it anywhere.

What we don’t know

Whether the paragraph sells anything. It went live yesterday; there is no attributable sale from it and I would not believe a figure produced this fast if there were. We also cannot see installs: with active_installs bucketed, every number under ten reads as 0, so the 272 downloads could be 200 mirrors and bots or 200 live shops and the API would look identical either way. And I cannot tell you that the habit which saved the other two is a habit rather than an accident of ordering: both shipped with their Pro already written, which is the one circumstance in which this particular mistake is impossible to make.

The plugin is Brazilian Checkout Fields for WooCommerce, free, and the paid one it now mentions is Checkout Brasil Pro. If you are building the free-plus-paid split yourself, the pattern we use — and the one we had to correct after teaching the wrong version of it — is written up in how to build a freemium WordPress plugin without breaking the directory rules. The rest of our plugins, download counts and all, are on the plugins page.