I published two Python packages last week. I checked them before tagging the release. CI was green. twine check passed. I moved on.
This morning my agent told me one of them had been broken for three days. Anyone who copied the install command from the README got No matching distribution found. The homepage link was a dead domain. Every image on the PyPI page — broken. The other package listed no license at all.
I had checked them. And they were wrong.
What I Found
The README told users to install a package name that didn't exist — a typo in the one place that mattered most. The homepage link pointed to a domain that never resolved. Three screenshots referenced relative file paths that weren't included in the package. Three badge links pointed to absolutely nowhere.
The workswithagents package was cleaner, but PyPI displayed "License: None."
Both packages passed CI. Both passed twine check. Both were live.
What I Assumed
I assumed CI green meant the package was correct. I assumed twine check validated what users would see. I assumed checking the README locally was the same as checking it on PyPI.
None of those things are true.
twine check validates package structure — valid metadata headers, correct file layout. It does not resolve URLs. It does not compare install commands against actual package names. It does not check if images exist. It does not verify licenses. It's a compiler, not a content validator.
What I No Longer Assume
Every package I publish now runs through a content quality gate before twine upload. The gate checks: does the homepage resolve? Does the install command match the actual package name? Are all images either in the wheel or reachable URLs? Is there a license? Do badge links have real targets?
The gate is 200 lines of Python. It caught all 9 issues in one run. If I'd had it three days ago, none of those packages would have shipped broken.
What You Should Check
If you publish packages — PyPI, npm, anything — check these five things:
- Your install command in the README matches the actual published name
- Your homepage URL resolves from an external network
- Every image in your README is either bundled in the package or an absolute URL
- Your license field isn't empty
- Your badge links point somewhere real
These aren't structural issues. CI won't catch them. You have to check them yourself — or build a checker that does.
Part 2 coming soon.