Mesa Examples self- and peer-review guidelines
Nobody has claimed this yet.
- Dominant language
- Python
- Stars
- 252
- Forks
- 279
- Avg merge
- 8d 9h
- Merged PRs (30d)
- 2
Description
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](https://github.com/mesa/mesa/issues/3536). 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](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/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
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
No target file or test is named; start by locating the documentation or contributor-guidance entry point in mesa-examples and compare its structure with this issue. Publish the self- and peer-review checklist covering model behavior, API currency, code quality, README content, and PR hygiene.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- python
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 2/5
- Estimated time
- 1-3 hours
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 48/100