From de26dd690d845a6afd561386d639ab0125ac28a4 Mon Sep 17 00:00:00 2001 From: Ewout ter Hoeven Date: Fri, 30 Aug 2024 12:01:22 +0200 Subject: [PATCH 1/3] Contribution: Add "I have no idea where to start" section A section for people who would like to contribute but don't know where to start. It points to a lot of resources in a semi-structured way. --- CONTRIBUTING.md | 33 +++++++++++++++++++++++++++++++++ 1 file changed, 33 insertions(+) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index ffc5d699b10..cb4694c4fc4 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -36,6 +36,39 @@ discuss via [Matrix] OR via [an issue]. - Describe the change w/ ticket number(s) that the code fixes. - Format your commit message as per [Tim Pope's guideline]. +## I have no idea where to start +That's fine! Here's a rough outline where you could start, depending on your experience: + +### I'm a modeller (but not an experienced developer) +You already know how to build Mesa models (if not skip below), and probably have found things Mesa can't do (elegantly). You want to improve that. Awesome! + +First step is to install some proper tools, if you haven't already. +- A good IDE helps for code development, testing and formatting. [PyCharm](https://www.jetbrains.com/pycharm/) or [VSCode](https://code.visualstudio.com/) for example. +- Dive into Git and GitHub. Watch some videos, this takes some time to click. [GitHub Desktop](https://desktop.github.com/) is great. +- [`https://github.dev/projectmesa/mesa`](https://github.dev/projectmesa/mesa) is great for small changes (to docs). + +Learn the tools, talk to us about what you want to change, and open a small PR. Or update an [example model](https://github.com/projectmesa/mesa-examples) (check open [issues](https://github.com/projectmesa/mesa-examples/issues))! + +### I'm a developer (but not a modeller) +Awesome! You have the basics of open-source software development (if not check above), but not much modelling experience. + +First step is to start thinking like a modeller. To understand the fine details about our library and contribute meaningfully, get some modelling experience: +- Go though our [Introductory Tutorial](https://mesa.readthedocs.io/en/latest/tutorials/intro_tutorial.html) and [Visualization Tutorial](https://mesa.readthedocs.io/en/latest/tutorials/visualization_tutorial.html). While going through them, dive into the source code to really see what everything does. +- Follow an ABM course (if possible). + - This MOOC is a nice start: [Agent Based Modeling](https://ocw.tudelft.nl/course-lectures/agent-based-modeling/) +- Go though multiple of our [examples](https://github.com/projectmesa/mesa-examples). Play with them, modify things and get a feel for Mesa and ABMs. + - Check our open [issues](https://github.com/projectmesa/mesa-examples/issues) for the examples. + - If you see anything you want to improve, feel free to open a (small) PR! +- If you have a feel for Mesa, check our [discussions](https://github.com/projectmesa/mesa/discussions) and [issues](https://github.com/projectmesa/mesa/issues). + - Also go thought our [release notes](https://github.com/projectmesa/mesa/releases) to see what we recently have been working on, and see some examples of successful PRs. +- Once you found or thought of a nice idea, comment on the issue/discussion (or open a new one) and get to work! + +### I'm both +That's great! You can just start working on things, reach out to us. Skim to the list above if you feel you're missing anything. Start small but don't be afraid to dream big! + +### I'm neither +Start with creating your own models, for fun. Once you have some experience, move to the topics above. + ## Testing and Code Standards ```{image} https://codecov.io/gh/projectmesa/mesa/branch/main/graph/badge.svg From fc2ca121f987103ef00289b0805d77a62b488385 Mon Sep 17 00:00:00 2001 From: Ewout ter Hoeven Date: Fri, 30 Aug 2024 13:10:15 +0200 Subject: [PATCH 2/3] Update MOOCs with complexity explorer --- CONTRIBUTING.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index cb4694c4fc4..4d1eee96ee6 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -55,7 +55,8 @@ Awesome! You have the basics of open-source software development (if not check a First step is to start thinking like a modeller. To understand the fine details about our library and contribute meaningfully, get some modelling experience: - Go though our [Introductory Tutorial](https://mesa.readthedocs.io/en/latest/tutorials/intro_tutorial.html) and [Visualization Tutorial](https://mesa.readthedocs.io/en/latest/tutorials/visualization_tutorial.html). While going through them, dive into the source code to really see what everything does. - Follow an ABM course (if possible). - - This MOOC is a nice start: [Agent Based Modeling](https://ocw.tudelft.nl/course-lectures/agent-based-modeling/) + - This MOOC on ABM concepts: [Agent Based Modeling](https://ocw.tudelft.nl/course-lectures/agent-based-modeling/) + - This MOOC on practical ABM modelling: [Agent-Based Models with Python: An Introduction to Mesa](https://www.complexityexplorer.org/courses/172-agent-based-models-with-python-an-introduction-to-mesa) - Go though multiple of our [examples](https://github.com/projectmesa/mesa-examples). Play with them, modify things and get a feel for Mesa and ABMs. - Check our open [issues](https://github.com/projectmesa/mesa-examples/issues) for the examples. - If you see anything you want to improve, feel free to open a (small) PR! From 88e47f84649176b5b277d84adbfd6ac28df78e0a Mon Sep 17 00:00:00 2001 From: Ewout ter Hoeven Date: Fri, 30 Aug 2024 16:21:01 +0200 Subject: [PATCH 3/3] Add note --- CONTRIBUTING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 4d1eee96ee6..38899aba02e 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -54,7 +54,7 @@ Awesome! You have the basics of open-source software development (if not check a First step is to start thinking like a modeller. To understand the fine details about our library and contribute meaningfully, get some modelling experience: - Go though our [Introductory Tutorial](https://mesa.readthedocs.io/en/latest/tutorials/intro_tutorial.html) and [Visualization Tutorial](https://mesa.readthedocs.io/en/latest/tutorials/visualization_tutorial.html). While going through them, dive into the source code to really see what everything does. -- Follow an ABM course (if possible). +- Follow an ABM course (if possible). They might be a bit outdated programming language wise, but conceptual they're sound. - This MOOC on ABM concepts: [Agent Based Modeling](https://ocw.tudelft.nl/course-lectures/agent-based-modeling/) - This MOOC on practical ABM modelling: [Agent-Based Models with Python: An Introduction to Mesa](https://www.complexityexplorer.org/courses/172-agent-based-models-with-python-an-introduction-to-mesa) - Go though multiple of our [examples](https://github.com/projectmesa/mesa-examples). Play with them, modify things and get a feel for Mesa and ABMs.