ContributorGuidelines

What to contribute

MicroPython is named "Micro" for a reason. We don't want to compete with CPython or replace it. We could spend year of development and do everything what CPython can do, just in 50% of size. It's not worthy an aim. If you want all CPython functionality, you can use CPython right now. What we try to achieve with MicroPython is being order(s) of magnitude smaller than CPython, to use Python (the language) where CPython could not be used at all. This necessitates being a CPython subset, making compromises for what can go into MicroPython core, and then stay orthodox about these compromises.

Here are more specific examples:

1. For microcontroller case, reference MicroPython implementation runs on a pretty big MCU. But we would like to maintain portability to much smaller MCU cores. The theorhetical minimum requirements we'd like to maintain are 128K ROM/8K RAM. Note that those are "raw hardware" requirements. In real-world case, part of ROM and RAM may be used for RTOS/supervisor, and that lowers requirements to 100K/4K respectively.

2. It may seem that "unix" port would not be affected by such stringent requirements, and yet it is, because one of the usecase is running MicroPython on truly minimal Linux systems with just 4 or even 2Mb of flash, half of which is taken by kernel, remaining half by support utilities, and only mere hundreds of Ks are available for MicroPython, user apps and data. So, every byte is still accounted for.

3. MicroPython is not the only small, embeddable language, so we need to stay competitive in this niche. Well-known small language is Lua, and we take it as assessment baseline. It's out belief that many people use Lua due to lack of better alternative. With MicroPython, there's now good alternative. But we don't want people to reject MicroPython because it's "much bigger" than Lua. Note that it's necessarily bigger, because Python provides more standardize and well-defined functionality. But we want to stay at "somewhat bigger", and not "much bigger" mark. Actually, we want to maintain "minimal" MicroPython configuration, which achieves sizes comparable, or better, than typical non-finetuned Lua build.

Where to contribute

We write MicroPython in C not to keep writing code in C. We write it to let us and everyone write code in Python. This should be good rule of thumb - anything which can be written in Python, should be written in Python, unless there're really good reasons to write it in C.

So, while we cannot achieve full CPython compatibility in MicroPython, we want to have as complete as possible, CPython-compatible standard library written in Python, there's a separate project for that: https://github.com/micropython/micropython-lib .

But note that even micropython-lib has its pretty well defined scope: it's for Python standard library modules, plus, as an exception, to modules we consider to be part of "standard MicroPython library". micropython-lib is not intended to become single destination (or outright dump) of all modules MicroPython. Instead, we would like to achieve the same model as used by Python in general: there's a community, with multitude of modules maintained by individual members of it.

Summing up, you have 3 choices where to contribute with MicroPython development:

• MicroPython core
• micropython-lib
• Maintain your own module or port, as part of general MicroPython community

How to contribute

Please make sure you read previous sections to understand MicroPython philosophy and approach. We expect contributors will be aligned with them in general, because otherwise it would be hard to understand why specific change is proposed at all.

If you're not sure if some change would go along with MicroPython approach, please discuss this change first. We have 2 channels of communication:

• Project tickets
• Development forum

You may not agree with us on interpretation of specific feature, so please share your point of view, and be prepared to elaborate and argue it - we're here to listen, and discussion is the way to run projects. But at the same time please keep in mind that we necessarily have to be conservative to achieve (and not lose on the way) project aims as stated in "What to contribute" section, so we may suggest better destination to apply your change/effort to, per "Where to contribute" section.

We accept changes using Github pull requests, as the most seamless way for both ourselves and contributors. When you make commits for a change, please follow format of existing commit messages (use "git log" to review them). For considerable changes, we expect detailed, yet formal and concise description in of the change in commit messages. If you make 2 or more considerable changes, they should go in separate commits. The same applies to unrelated changes - for example, don't put formatting changes and actual code changes in one commit.

When you submit pull request, please make sure that it's understood why you propose this change: what problem it addresses, how it improves MicroPython (and not deteriorates, taking into account stringent constraints of "What to contribute" section). Good commit messages are good way to achieve this, but sometimes it's better to put informal points, colloquial arguments and big example in comments to pull request instead.