Mesa Examples self- and peer-review guidelines

[EwoutH]

For reviewing PRs to mesa-examples. Also useful as a self-review guide before requesting review.

For GSoC contributors: self- and peer-review is a PR requirement. It’s an essential part of post-LLM open-source development, you will learn a lot from it (and that’s sometimes hard work!)

How to review

Start at the top of the checklist and work down — big picture first, details last. There's no point nitpicking variable names if the model duplicates an existing example or uses deprecated APIs.

Run the model locally. Does it work? Does the visualization make sense? Read the README: could someone unfamiliar with the model understand what it does and why it's here? Only then dig into the code. You'll often learn more from reviewing than from writing, so take it seriously even if the model isn't in your area.

Both for self- and peer-review, use the features of the GitHub interface. See Reviewing proposed changes in a pull request.

A review should take place on a deep level. Basically:

• run the model, play with it, explore interesting behavior. Ask questions about that, discuss it and write it down as pointers that users can observe and play with.
• ask question / make comments on function and code-level.

The former is more important than the latter.

Stuff you could review (roughly in order)

Does it belong?

• No significant overlap with an existing example, or if there is, the overlap is justified?
• The model is well-scoped: the simplest model that demonstrates its idea
• It showcases Mesa features not already well-covered by other examples
• It showcases interesting ABM mechanics, dynamics or phenomena

Is it correct and current?

• Uses current Mesa APIs (no deprecated schedulers, manual unique_id, dict portrayals, etc.)
• Runs and visualizes out of the box

Is it clean?

• Minimal: no dead code, unused imports, or unnecessary complexity
• Clear naming; logic readable without deep domain knowledge
• README explains what it does, what it demonstrates, and how to run it (concise, links to references for theory)
• PR follows the template, commits are clean, no unrelated changes