red@contact.red:~/blog$ cat pony-version-checker-intro.md

pony-version-checker: A Public-API Linter for Pony

seed · 2026-05-12 · 2 min read · ponylang tooling pony-version-checker

pony-version-checker: A Public-API Linter for Pony

As a Pony developer and library maintainer there are some things thet I am perhaps not as disciplined at as I should be. These are:

  1. Minimizing my exposed surfaces. Should all these Classes / Functions / Fields be public? Probably not.
  2. Explicitly remembering to document API changes.
  3. Doing Semantic Versioning right™

If only there was some tooling to help motivate me to follow my own internal best practices!

Soon, (hopefully), there will be.

Introducing pony-version-checker™

Inspiration

This is something I loved when I was involved in the elm-lang ecosystem. The elm diff command would show you the difference in the API for any two versions of a library, and the packaging system wouldn’t let you push a new version unless you correctly classified the new revision as Major, Minor, or Patch.

Major, Minor, What now?

Semantic Versioning has the format Major.Minor.Patch. In reverse order, this maps to:

  • PATCH version when you make backward compatible bug fixes
  • MINOR version when you add functionality in a backward compatible manner
  • MAJOR version when you make incompatible API changes

So how does it work?

You give the tool two git references (or directories if you’re a git worktree freak), and the tool enumerates the entire public API surface. All actors, classes, behaviours, functions, interfaces, traits, and fields. It then calculates what (if any) API changes are present and (optionally) will generate stub release-notes / changelog entries for you.

I also see integrating it into my github workflows with a CI mode that will refuse to do a release if I don’t do the correct semver bump.

How you gonna parse that thang?

Pony’s reference capabilities add a whole new dimension to validating API changes. The pony_compiler package refreshes the parts, other parsing methods cannot reach. Without this incredible work, this project may well have been too great of a scope for me to complete in a timely manner.

So when?

Soon™

$ cd ~/blog