micropython-lib/CONTRIBUTING.md

Contributor's Guidelines & Code Conventions

micropython-lib follows the same general conventions as the main MicroPython repository. Please see micropython/CONTRIBUTING.md and micropython/CODECONVENTIONS.md.

Raising issues

Please include enough information for someone to reproduce the issue you are describing. This will typically include:

• The version of MicroPython you are using (e.g. the firmware filename, git hash, or version info printed by the startup message).
• What board/device you are running MicroPython on.
• Which package you have installed, how you installed it, and what version. When installed via mip, all packages will have a __version__ attribute.
• A simple code snippet that demonstrates the issue.

If you have a how-to question or are looking for help with using MicroPython or packages from micropython-lib, please post at the discussion forum instead.

Pull requests

The same rules for commit messages, signing-off commits, and commit structure apply as for the main MicroPython repository. All Python code is formatted using black. See tools/codeformat.py to apply black automatically before submitting a PR.

There are some specific conventions and guidelines for micropython-lib:

• The first line of the commit message 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.

• Although we encourage keeping the code short and minimal, please still use comments in your code. Typically, packages will be installed via mip and so they will be compiled to bytecode where comments will not contribute to the installed size.

• All packages must include a manifest.py, including a metadata() line with at least a description and a version.

• Prefer to break larger packages up into smaller chunks, so that just the required functionality can be installed. The way to do this is to have a base package, e.g. mypackage containing mypackage/__init__.py, and then an "extension" package, e.g. mypackage-ext containing additional files e.g. mypackage/ext.py. See collections-defaultdict as an example.

• If you think a package might be extended in this way in the future, prefer to create a package directory with package/__init__.py, rather than a single module.py.

• Packages in the python-stdlib directory should be CPython compatible and implement a subset of the CPython equivalent. Avoid adding MicroPython-specific extensions. Please include a link to the corresponding CPython docs in the PR.

• Include tests (ideally using the unittest package) as test_*.py. Otherwise, provide examples as example_*.py. When porting CPython packages, prefer to use the existing tests rather than writing new ones from scratch.

• When porting an existing third-party package, please ensure that the source license is compatible.