On keeping our examples healthy — and why it matters more than we think

[abhinavk0220]

The quiet cost of letting examples drift

I have been spending time lately going through the examples in this repo — running them, reading the code, tracing bugs — and I keep coming back to the same thought: these examples are often the first thing a new user ever runs in Mesa.

Not the docs. Not the API reference. The examples.

Someone discovers Mesa, clones the repo, picks a model that sounds interesting, types solara run app.py — and if it crashes, or throws a wall of deprecation warnings, or silently misbehaves, that moment is lost. That person may not come back.

I don't say this to be dramatic. I say it because I genuinely believe the health of these examples is load-bearing for the health of the community.

---

What I found in Bank Reserves

I was looking at the Bank Reserves model — a classic, one of the originals — and found a few things that had quietly fallen behind as Mesa evolved:

• agent_portrayal was still returning a plain dict, the old pre-Mesa-4 pattern that now triggers deprecation warnings at runtime
• The visualization was using make_space_component, while the rest of the ecosystem has moved to SpaceRenderer + AgentPortrayalStyle
• The README still referenced MultiGrid and ModularServer — APIs that no longer exist in Mesa 4.x

None of these are catastrophic bugs. But together they send a message to anyone reading the code: "this is old, this is not how things are done anymore." That is not the message we want to send.

I opened PR #461 to address these. The fix itself is small. But the intention behind it is something I feel strongly about.

---

What I think we owe new contributors and learners

When someone is learning Mesa, they read the examples the way a student reads a textbook. They trust what they see. If the textbook has errors, they internalize the errors. If the textbook uses outdated idioms, they carry those idioms forward into their own models.

Keeping examples current is not just maintenance. It is an act of care toward everyone who will ever learn from them.

I am also aware that this is hard to keep up with. Mesa is moving fast — the 4.x migration was significant — and the examples repo is large. No one can watch everything. That is exactly why I think it is worth naming the problem explicitly: we need a culture where examples are treated as first-class citizens, not afterthoughts.

---

A question for the community

Would it be useful to do a systematic pass through all examples and flag which ones have:

• Deprecation warnings when run
• References to removed APIs in code or README
• Missing rng parameter (batch run failures)
• Outdated README feature lists

I am happy to help drive that effort. Not as a sprint, but steadily — one example at a time, the way good maintenance actually works.

Would love to hear thoughts from maintainers and fellow contributors. And if you have spotted other examples that need attention, please share below — let us build a shared picture of where the gaps are.

— Abhinav

[Tushar1733]

yeah come to think of it, I've encountered similar problems earlier so i audited all the examples manually in my local machine. mostly checking for deprecations, outdated APIs, and runtime issues.
I’ve compiled the findings of 20 examples into a document. Happy to share it here if that would be useful.

Also open to aligning with any broader effort if we decide to do a systematic pass.