Skip to content

ContributorGuidelines

Paul Sokolovsky edited this page Nov 17, 2018 · 16 revisions

These are WIP contributor guidelines.

  1. Golden rule: Please do "git log"/"git log -p" and follow the same approach with your changes. Some specifics:
  2. One changed module/package per commit.
  3. One logical change per commit. E.g., adding new method vs changing formatting should be 2 separate commits.
  4. Every commit message starts with "<module>: "
  5. Each module's setup.py is autogenerated from metadata.txt by make_metadata.py script, so please make manual changes to metadata.txt, not to setup.py. Ideally, metadata.txt and setup.py changes would go into separate commit. If that's too detailed for you, and you make one commit, then include metadata.txt changes, and leave out setup.py changes altogether. (The idea is to keep code vs metadata changes separate, to minimize patch noise.)
  6. Name something test_*.py only if it's a real unittest (which will checks results itself and will fail if there's error). Otherwise if a human should check test results, name it example_*.py.
  7. We follow PEP8, except for over-tight line length limits. Lines up to 90 chars are OK. If there're good reasons, a line can be longer (consider 132 to be hard limit).
  8. For new modules written, please use "" as string delimiters.
  9. Beyond that, follow the style of the surrounding code. For example, if literal strings in a module/function use doublequotes "", use that. If singlequotes '', use that. (Doublequotes is the default style, per above.)

When porting a module from CPython or other 3rd-party source:

  1. Do some research to find suitable source. CPython 3.3 stdlib should still be considered as a base version to take modules from, as more recent versions has some modules bloated, which isn't really good direction for MicroPython. (But still, try to look at different versions and sources beyond CPython (e.g. PyPy) to find the best.)
  2. Start with committing 3rd-party source as-is, clearly stating in the commit message from where it was taken (exact version, preferrably with a URL to tarball, or VCS revision, preferrably with URL to it).
  3. Follow up with your changes as a next commit.
  4. When making your changes, the criteria should be minimizing size of a diff. Change as few lines as possible, within lines, don't change more chars than needed. Prefer commenting out to removal of lines. Don't fix typos, formatting, etc. - if you want them to be fixed, submit patches directly to upstream.
  5. Prefer taking (and porting) tests from CPython rather than duplicating effort and making your own.
You can’t perform that action at this time.