ContributorGuidelines

NOTE: These guidelines were initially written by @pfalcon for MicroPython. References to MicroPython may be retained below, but the document fully applies to Pycopy.

What to contribute

MicroPython is named "Micro" for a reason. We don't want to compete with CPython or replace it. We could spend years of development and implement 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 a microcontroller case, the reference MicroPython implementation runs on a pretty big MCU. But we would like to maintain portability to much smaller MCU cores. The theoretical 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 around 100K/4K respectively.

2. It may seem that the "unix" port would not be affected by such stringent requirements, and yet it is, because one of the usecases is running MicroPython on truly minimal Linux systems with just 4 or even 2Mb of flash, half of which is taken by the 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 an assessment baseline. It's our belief that many people use Lua due to lack of a better choice. With MicroPython, there's now a 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 standardized 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 fine-tuned Lua builds.

Where to contribute

We write Pycopy in C not to keep writing code in C. We write it to let us and everyone write code in Python. This should be a 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 might not achieve full CPython compatibility in Pycopy, 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/pfalcon/pycopy-lib .

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

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

• Pycopy core
• pycopy-lib
• Maintain your own module or port, as a part of the general MicroPython community

So, it is worth considering where some change fits better. It may be not immediately obvious either, so may take some discussion, as described in the following section.

How to contribute

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

If you're not sure if some change would go along with Pycopy approach, please discuss this change first. There're following channel(s) of communication:

• Project tickets
• Reddit forum

You may not agree with us on interpretation of a 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) the project aims as stated in the "What to contribute" section, so we may suggest better destination to apply your change/effort to, per the "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 the format of existing commit messages (use "git log" to review them). For considerable changes, we expect a detailed, yet formal and concise description of the change in the commit message. 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 a pull request, please make sure that it's understood why you propose this change: what problem it addresses, how it improves Pycopy (and at the same time, not deteriorates it, taking into account stringent constraints of the "What to contribute" section). Good, detailed commit messages are an easy way to achieve this, and yet sometimes it's better to put informal points, colloquial arguments and big examples in comments to a pull request instead, to keep commit messages concise and focused.

"Django criteria"

As an example of application of previous ideas, (semi-serious) "Django criteria" are introduced regarding adding new features, which are roughly superfluous, not overly important, or rather rare to use:

• If you write your own code, and there's another way to achieve it with other existing features, please just do it this other way.
• If you port existing code, you'll likely find out that a lot of features missing, so adding all of them will be a lot of work, and will bloat Pycopy, and adding just one or few won't make a big difference. (So, just keep porting, by patching existing code to use facilities Pycopy already provides.)
• However, if you tried to run a big, well-known package, like Django, and found that only few features are missing to run it out of the box, without any patching, then we definitely would like to add them to be able to claim that Pycopy can run Django ;-).