mirrors
/
micropython
mirror of https://github.com/micropython/micropython.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Update the contributor guidelines to include some workflow hints and updated links.

Jim Mussared 2022-08-30 16:23:44 +10:00
parent 07254c8fc2
commit 770dee947b
1 changed files with 43 additions and 34 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

77
ContributorGuidelines.md

@ -1,51 +1,60 @@
# Code of Conduct
Please read the [MicroPython Code of Conduct](https://github.com/micropython/micropython/blob/master/CODEOFCONDUCT.md) before contributing to the MicroPython project.
# Getting started
We welcome all types of contributions, across a wide variety of different domains.
* The core Python virtual machine and runtime
* The built-in standard library
* The "MicroPython Library" (see https://github.com/micropython/micropython-lib)
* Ports to different architectures and microcontrollers
* Board definitions
* Documentation
* Developer tools and workflow
* Community management
There's information about [getting started with MicroPython development](https://docs.micropython.org/en/latest/develop/gettingstarted.html) in the official documentation. For more assistance, the [discussion forums](https://github.com/micropython/micropython/discussions) and the [Discord server](https://github.com/micropython/micropython/wiki/ContributorGuidelines) are a great way to ask questions and connect with other MicroPython developers.
It's often a good idea before starting a piece of work to get some feedback from the community or the project maintainers, to ensure that your effort will not be wasted. Raising an issue with `"RFC: "` as the start of the title is a good way to do this.
MicroPython itself is written in C, but most of the support tooling and build infrastructure, as well as drivers and libraries are written in Python. In general, if it's possible to implement something in either C or Python, we prefer Python. It is possible to extend MicroPython in C++, but no C++ code is used in the main repository.
# 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.
## Bug fixes
When submitting a fix, please include a detailed description of how the bug occurs, ideally with reproduction steps, and what boards/ports/devices it effects.
Here are more specific examples:
Bug fixes can sometimes have unintended and complicated interactions with other features and an the "obvious" fix might not always be the "correct" fix. It might take a bit of backwards-and-forwards discussion to resolve this.
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.
## New features
When it comes to adding features to MicroPython, it's important to remember that MicroPython is named "micro" for a reason. We don't want to compete with CPython or replace it, rather to try to find the right subset that makes sense for the embedded world. We support devices with as little as 128kiB of flash and 16kiB of RAM. Even the Unix port can be used to run MicroPython on truly minimal Linux systems with just 4MiB or even 2MiB of flash.
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.
In many cases, features can be enabled conditionally for a given target (i.e. boards with lots of flash or RAM, or the Unix/Windows ports). The continuous integration will check any new changes to ensure that our "minimal" ports do not increase in size.
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.
To give you an idea of how highly we value code size, the MicroPython team will spent hours of effort just to save 10's of bytes from a given feature. This unfortunately means that the code is more complicated, but it's a worthwhile trade-off.
# Where to contribute
## Ports
We welcome ports to new architectures and microcontroller families. However, not all ports can be accepted into the main repository as each port is a significant maintenance overhead for the core team. It is straightforward to maintain an "out-of-tree" port using MicroPython as a submodule.
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 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.
## Board definitions
Each port contains a set of board definitions. Each one of these boards will be compiled automatically and published on the [downloads page](https://micropython.org/download/). Board definitions will typically also require a thumbnail image to be added to the [MicroPython media repository](https://github.com/micropython/micropython-media) via a PR.
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 .
# Sending pull requests
But note that even micropython-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 MicroPython library". micropython-lib is not intended to become the single destination (or an outright dump) of all modules MicroPython. 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.
Before sending a PR, please ensure that your code and commits meet the [code conventions](https://github.com/micropython/micropython/blob/master/CODECONVENTIONS.md). We have automated tools to assist with finding and fixing code style issues, see the code conventions documentation for more information. In addition, ensure that your code matches the style of the surrounding code and the project in general. If you have questions about this or are looking for guidance on a particular style question please either mention this in the PR or reach out on the forums or Discord.
Summing up, you have 3 choices where to contribute with MicroPython development:
The MicroPython project adheres to a strict linear git history, with no merge commits. All PRs must rebase cleanly. Please prefer to break up your work into small commits. It's always easier to squash them later than to split them.
* MicroPython core
* micropython-lib
* Maintain your own module or port, as a part of the general MicroPython community
When you submit a pull request, please make sure that it's understood why you are proposing this change: what problem it addresses, how it improves MicroPython, and what the potential downsides are (e.g. code size). Detailed commit messages are an easy way to achieve this, and additionally the PR description and comments can be used to provide a more informal summary and justification.
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.
All code must be your own work or suitably licensed. Please see the information about signing off your commits in the [code conventions](https://github.com/micropython/micropython/blob/master/CODECONVENTIONS.md#git-commit-conventions).
# How to contribute
## Continuous Integration
Please make sure you read previous sections to understand MicroPython 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.
All PRs will trigger GitHub Actions to run the continuous integration (CI). This checks that all ports compile in a variety of configurations, and runs the full test suite against the Unix and Windows port, as well as emulated hardware. If you are unsure why a test is failing, please indicate that in the PR comments.
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:
## Updating PRs
* [Project tickets](https://github.com/micropython/micropython/issues)
* [Development forum](http://forum.micropython.org/viewforum.php?f=3)
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 MicroPython (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 MicroPython, and adding just one or few won't make a big difference. (So, just keep *porting*, by patching existing code to use facilities MicroPython 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 MicroPython can run Django ;-).
When updating a PR, either due to review feedback or to fix CI issues, you should update your branch locally and then force push it to your GitHub branch that the PR was created from. When updating your branch, this typically involves either editing the commits directly via rebase, or adding new commits then "fix"-ing them into the existing commits during a rebase. Please fetch the upstream and rebase your branch on `master` before pushing.