How to Format Pull Request With Examples

[flucco]

I have been coding for a long time but am new to contributing anything to a project like this on Github, so I have what is probably a very basic question. I just wanted to clarify this before I made a pull request.

I have a pretty simple bug fix for a visualization issue with PropertyLayers in HexGrids. The issue is here. The fix is simple -- it's a transpose operation in one line of code. I have a good sense of why it works that I'm prepared to explain in detail.

I have created a modified version of the Sugarscape example that shows the bug and works with the change I made (I'm going to add a few more test cases to my repository before I actually submit a pull request, specifically one that works for a model with different width and height). My question is, where do I put this example in my pull request? Should I add it to the examples in the Mesa code as part of my changes, or should I just link in the pull request to my repository with the examples?

Basically, I'm not totally sure what the standard is for demonstrating that what I did works..

[EwoutH]

Thanks for reaching out! You're doing great already with a detailed bug report (#2859) and PR (#2864), already following many parts of our guidelines. The detailed explanation, proof with an example and screenshots are more than enough, and really appreciated!

We like PRs to be atomic:

An atomic PR (Pull Request) is a code change that is intentionally small, focused, and complete in itself, addressing a single logical unit of work that can be understood, reviewed, and merged independently. The term "atomic" comes from the idea that the change is indivisible—it contains the minimum set of modifications needed to implement one specific feature, fix one bug, or make one refactoring, without mixing in unrelated changes. This approach makes code reviews faster and more effective since reviewers can focus on one clear objective, reduces the risk of introducing bugs because changes are easier to test and reason about, and simplifies the process of rolling back changes if issues arise. Atomic PRs contrast with large, multi-purpose PRs that bundle numerous changes together, which become difficult to review thoroughly and can create bottlenecks in the development workflow.

Your PR already makes one change, so that's great! Now it's just a question of cleaning it up from a Proof of Concept (like you have now) to a clean change that directly and only fixes the bug.

If you want to talk directly to us, make sure you join our Matrix chat! https://matrix.to/#/#project-mesa:matrix.org

I'm curious, in what context are you using Mesa?

[flucco]

Thank you! I think everything should be up to standard now.

To answer your curiosity question, my work is in biological modeling. I ran across this issue because I was using a HexGrid to model a sheet of epithelial cells, and a PropertyLayer to model bacterial spread through those cells. Hexagonal grids are a common way to model epithelial cells because each cell has 6 neighbors, rather than 4 in a square grid, which is a better approximation of how epithelial cells usually pack together.

[EwoutH]

That’s quite cool! At which institution are you doing that?

sheet of epithelial cells

Do you find a 2D space sufficient for this? Our would a 2.5D (multiple layers) or 3D grid be better? We do support those, but for the latter visualization is limited.

[flucco]

That’s quite cool! At which institution are you doing that?

I work at Northwestern.

sheet of epithelial cells

Do you find a 2D space sufficient for this? Our would a 2.5D (multiple layers) or 3D grid be better? We do support those, but for the latter visualization is limited.

The 2D space works for my specific purposes, but it really depends on what you're modeling and what questions you're trying to answer. 2D is a good fit for what I'm doing because I'm modeling a single layer cell culture made in a lab, rather than something in the human body. Also, I'm not really focused on the internal spatial structure of the cells.

The 2.5D model is interesting, I haven't heard of that in a biological context but I'm sure it's been used before.