Discuss: Moving examples to examples repo

[jackiekazil]

A long long long time ago we talked about moving examples over to the examples repo. 
I feel like we should go ahead and do that. The more the examples grow the bigger the main project will get. 

Examples repo: https://github.com/projectmesa/mesa-examples/

People have been submitting issues and PRs against this repo.
So either we kill or officially move. I feel like it makes sense to kill and I would like to prioritize doing this.

What moving looks like...

• Remove from this repo
• Overwrite all date here: https://github.com/projectmesa/mesa-examples/
• Update Readme for mesa-examples
• Review and update any references to examples in the docs of this repo

Thoughts?

[rht]

Previous discussion at #134.

[rht]

Another alternative is to create a separate examples repo, but link it as a submodule inside projectmesa/mesa. Known precedent: NetLogo does it, see https://github.com/NetLogo/NetLogo and look at models folder. But if the examples are going to be updated only for each major release, it doesn't make sense for projectmesa/mesa to track projectmesa/examples. Not sure what the rationale of the NetLogo developers is.

[dmasad]

My main concern with putting examples in a submodule is that submodules are hard to use even for moderately-experienced Git / GitHub users. Since the examples serve as de-facto tests, a contributor making an API change or adding a feature will probably also update the examples. Requiring the contributor to figure out submodules and keep their example branch and core branches in sync introduces a significant barrier to entry and opportunity for confusion and error.

[jackiekazil]

RE: #735 - We need to get this examples move prioritized -- Unless someone else wants to take on, I will take on POC before next dev session. Let me know if there are any concerns/considerations related to how this is done.

If someone feels passionate about taking this on -- feel free to take it -- I probably won't get started or look at until the weekend.

[tpike3]

@jackiekazil No issues here I will add it to the dev notes

[jackiekazil]

RE: #1451 - Time to dust this old ticket off!

Mesa Examples
Discussion centered on accessibility to new users so they can easily run examples. To this end, it seemed to be the best way forward was to put current examples in the example repo and make more user friendy. TODO: Move examples to examples repo and make more user friendly.

• What needs to be considered with doing this before I just pick and move?
  • Two PRs that are merged at the same time?
  • What about any PRs that have changes to examples that might be open.
• We were moving everything right?
• Permissions need to be granted to all maintainers of Mesa & Mesa-Geo

@rht @tpike3 would love to get your thoughts on this.

[rht]

Moving everything sounds good to me. It will make it easier for me to implement #1406, where I can just download the tarball of the GH repo from a URL, instead of having to deal with setup.py's data_files, which is hard to port to pyproject.toml/Poetry.

What about any PRs that have changes to examples that might be open.

The PR conflict is inevitable, it seems. Better sooner than much later.

[jackiekazil]

@rht I think the PR conflict is the reason this has been sitting around since 2020.

[rht]

There are 6 PRs which will have merge conflicts:

• https://github.com/projectmesa/mesa/pull/815/files
• https://github.com/projectmesa/mesa/pull/955/files
• Add El Farol Problem in mesa framework under example folder #1057
• https://github.com/projectmesa/mesa/pull/1223/files
• examples: Initialize Sugarscape ({G1}, {M, T}) #1290
• https://github.com/projectmesa/mesa/pull/1344/files

I have checked all of them. Resolving the conflicts should be manageable.

[Corvince]

It would probably make the most sense to have those PRs merged before doing the transfer. @rht do you think that is feasible? At least the non draft PRs

[jackiekazil]

WIPs

• Move examples from mesa repo to mesa-examples repo.  #1529
• Move examples from mesa repo to mesa-examples repo. mesa-examples#10

Things I did so far in the WIPs:

• In Mesa-examples, default branch was updated from master to main.
• Everyone who is on the maintainer team for projectmesa should now be a maintainer of the examples repo -
  https://github.com/orgs/projectmesa/teams/maintainers
• Spot tested models in fresh environments. Which maybe thinks -- we should create some integration tests... at least a script that chooses like 3 to 5 models to spin up fresh environments with and confirms that everything is running as expected.

[jackiekazil]

@Corvince I haven't looked thru everything -- but maybe we try to merge things that aren't draft or stale? (not sure which of the PRs fall under this -- none of them look like things that would untangled quickly.)

[jackiekazil]

Related: Examples: To pin mesa version or not to pin? #1530

[rht]

@rht do you think that is feasible?

Drafts:

• https://github.com/projectmesa/mesa/pull/815/files ongoing
• https://github.com/projectmesa/mesa/pull/1223/files this is more of a reminder that we need to think more to design directed network space. This could be converted to an issue which links to the original PR
• examples: Initialize Sugarscape ({G1}, {M, T}) #1290 ongoing
• https://github.com/projectmesa/mesa/pull/1344/files this can be closed and converted to an issue/discussion

Actionable:

• https://github.com/projectmesa/mesa/pull/955/files needs testing and doc tweak
• Add El Farol Problem in mesa framework under example folder #1057 needs merge conflict resolution and .ipynb cache clear

[rht]

Note that #1228 is no longer feasible with all the examples being moved to a separate repo. It's still feasible, but either with code duplication, or we leave a few examples in projectmesa/mesa. The use case I had in mind was for super quick demo in a classroom setting, something along the line of from sklearn.datasets import load_digits for MNIST dataset for Scikit-learn. Just to make sure that we leave no stone unturned.

[wang-boyu]

While migrating the examples shall they be separated into individual folders, like the Models Library in NetLogo? Mesa-Geo examples can later be grouped into a gis or geospatial folder.

[rht]

That sounds good to me.

[jackiekazil]

Do we want do to...

examples/
gis/
model1
model2
model3
...

OR

examples/
gis/
other_models/
model1
model2
model3

something else?

[jackiekazil]

Thinking about this -- I feel like maybe we should push the move through, then worry about how to organize the GIS files, so people can start submitting PRs against the new structure.

[rht]

Yes, that makes sense regarding with doing the folder restructuring later.

[wang-boyu]

I was thinking about something like this

examples/
  ├─ social_science/
  │   ├─ schelling/
  │   └─ ...
  ├─ economics/
  │   ├─ boltzmann_wealth_model/
  │   └─ ...
  ├─ gis/
  │   ├─ geo_schelling/
  │   └─ ...
  ├─ ...

which needs going through each existing model and assign it a category.

Thinking about this -- I feel like maybe we should push the move through, then worry about how to organize the GIS files, so people can start submitting PRs against the new structure.

Sure!

[jackiekazil]

Updated Todo list:

• Update examples with recent PRS
• Update license
• Update readme
• Update examples/readme
• Confirm that all existing models work correctly with current pypi mesa without issues.

RE: Folder structure - that is for future.

[jackiekazil]

^^ Everything above is done. I am moving the two PRs related to this to review. There are a few more things that popped up, but I think they should be deferred to after the initial version of this is merged.

Related PRs:

• Move examples from mesa repo to mesa-examples repo.  #1529
• Move examples from mesa repo to mesa-examples repo. mesa-examples#10

Things that still need to happen post merge unless we decide to bump up to pre-merge:

1. Figure out testing strategy for examples and cookiecutter & implement pinning at the same time (see Examples: To pin mesa version or not to pin? #1530)
   [TICKET: https://github.com/Design and implement testing strategy for examples & cookiecutter  #1547]
2. An initial contributing file was added to the examples repo, but it needs more polishing and work
   [TICKET: https://github.com/Add Contributing.md file & edit related files mesa-examples#11]
3. Set permissions correctly in mesa-examples repo
4. Move mesa-geo examples into examples -- Setup folders?
   [TICKET: https://github.com/Move mesa-geo examples into mesa-examples repo mesa-geo#128]
5. Add build / ci checks
   [TICKET: https://github.com/Add build/ci checks to this repo mesa-examples#13]

[jackiekazil]

PRs are merged -- thank you @rht

RE: # 3 above --
I did a review of permissions -- @projectmesa/maintainers have maintain ability. Until I dig more into permissions for the whole project this seems appropriate to me. I will consider item 3 in the previous comment resolved.

RE: 1, 2, 4, 5 --
All these have tickets. --- I added them to my previous comment. I wanted to break these up in discrete tasks so we can close this ticket.

Is there anything else that needs to be ticketed?
Can we close this issue?

[rht]

Agreed on closing.