TL, DR
MicroPython is a fantastic framework to write code for micro controllers. The procedure to contribute code on GitHub has a few bureaucratic steps which may be hard to get right first. Here the steps you need to follow.
MicroPython
MicroPython is a lean and efficient implementation of the Python 3 programming language that includes a small subset of the Python standard library and is optimized to run on micro controllers and in constrained environments. The project also has a library – micropython-lib – from where users can install packages, similar to PyPI for Python. I wrote some other post on MicroPython, you can find them here.
How to commit code
Set name and mail
If you commit code directly from the GitHub code editor, things may get a bit weird, as the mail and user automatically set there would fail the checks when opening the pull request. You need to use a proper editor (local or GitHub Codespaces), and set your details:
git config --global user.email "youremail@yourdomain.com"
git config --global user.email "youremail@yourdomain.com"manifest.py
All packages must include a manifest.py, including a metadata() line with at least a description and a version. For instance:
metadata(version="0.0.3", description="what does this package do")
package("packagename")Tests or examples
Include tests (ideally using the unittest package) as test_*.py. Otherwise, provide examples as example_*.py.
Format code with Ruff
Ruff and Black are the two mail code formatting tools for Python. Unfortunately, they may behave slightly differently on some cases…and those differences may cause your pull request to fail some automatic checks. Install Ruff and format your code with:
ruff format yourfile.pyCommit message and signature
Contributing guidelines request you to sign off your commit with your real name and a valid email. You can do it with:
git commit -s --author "Your Name <your@email.com>"The commit message also follow specific guidelines:
Each commit message should start with a directory or full file path prefix, so it was clear which part of codebase a commit affects. If a change affects one file, it’s better to use path to a file. If it affects few files in a subdirectory, using subdirectory as a prefix is ok. For longish paths, it’s acceptable to drop intermediate components, which still should provide good context of a change. It’s also ok to drop file extensions.
Besides prefix, first line of a commit message should describe a change clearly and to the point, and be a grammatical sentence with final full stop. First line must fit within 72 characters.
Here some example of good first lines:
py/objstr: Add splitlines() method.
py: Rename FOO to BAR.
docs/machine: Fix typo in reset() description.
ports: Switch to use lib/foo instead of duplicated code.If you are committing a new package, the first line may be something like:
python-ecosys/newpkg: Add the newpkg package.After the first line add an empty line and in the following lines describe the change in a detail, if needed, with lines fitting within 75 characters (with an exception for long items like URLs which cannot be broken). Any change beyond 5 lines would likely require such detailed description. Code attributions should be made here and in the source code if appropriate.
To get good practical examples of good commits and their messages, you can browse the git log of the project.
Pull request
Once you are done with your commit, you can open a pull request on GitHub. The title of the pull request should start with the name of the package, followed by a short description of the commit. Package names are globally unique in the micropython-lib directory structure. For example: shutil: Add disk_usage function.
Related links
Do you like our content? Check more of our posts in our blog!
