The four-year-old typo that nobody can fix 🧟 and more about building developer tools

Source: Dev.to

As the host of Making Software I get to have some pretty real conversations about what it actually takes to build good software. In a recent chat with Raghd Hamzeh (Senior Software Engineer at Okta and core maintainer of OpenFGA), we dug into a side of engineering that doesn’t get enough airtime: what happens when your users are other engineers? If you’ve ever built an API, an SDK, or even just a shared library, you know that developers are the most rewarding—and also the most “vocal”— audience you can have.

1. The “Breaking Change” Itch is Real 😬

Raghd admitted something many of us can relate to: a four‑year‑old typo in a product can drive you crazy. It might be a tiny naming inconsistency, but once it’s there, it stares back at you every time.

We all know the internal battle every maintainer faces: do you break everyone’s build just to satisfy the need for a clean API? Probably not. It’s a powerful reminder that decisions made in Month 1—like how a parameter is passed—become the legacy you live with in Year 5.

2. Stop building “Alien” SDKs 👽

While working on the Ruby SDK for OpenFGA, I ran into this head‑on. Rubyists are opinionated (I should know, I’m one of them).

When building multi‑language tools, you constantly balance two things:

• Consistency: Making sure the Go SDK and the Python SDK behave the same way.
• Idiom: Making sure a Ruby developer doesn’t feel like they’re writing Java code with extra steps.

Raghd’s take? You won’t get it perfect 100 % of the time. Sometimes you have to prioritize the long‑term health of the platform over a “perfectly idiomatic” implementation so the project stays maintainable for the team behind it. That tension never fully goes away—you just get better at navigating it.

3. The “AI” file that’s actually for humans 🤖

With the rise of AI, many repos now include agents.md files. Raghd had a spicy take: write that file for your human contributors first.

If you want people to help you build your open‑source dream, lay out your expectations clearly:

• How should commits be structured?
• What does the core architecture look like?
• Should contributors open an issue before submitting a PR?

Documenting these “non‑code” decisions up front saves an enormous amount of friction. It turns “This PR isn’t what we wanted” into “Here is the blueprint we’re all following.”

Full episode

Check out the full episode of Making Software here: Link to episode