pybricks-api/CONTRIBUTING.md

Project: pybricks-api

Acceptable changes:

• Fixing typos, spelling, grammar, etc.
• Clarifying existing documentation.
• Improving code completion/intellisense.

Other more substantial changes should be discussed first by opening an issue on GitHub. Proposals for new APIs should be discussed in the pybricks-micropython repository since that is where the new features will actually be implemented.

Commit messages:

• Commit messages have a one-line subject, a blank line and a multiline body:

    prefix: Subject of the change.
  
    body...
  

• Use a prefix to categorize the change:

  • Use the import path as the prefix whenever possible. Examples:
    • pybricks.tools: Add StopWatch class.
    • pybricks.tools: Reorganize RST files.
    • pybricks.tools.StopWatch: Fix return type.
    • pybricks.tools.wait: Add example of waiting.
    • pybricks.pupdevices: Fix all sensor class ports.
    • umath.sin: Fix spelling of Hypotenuse.
  • If an import path makes no sense, just use the file path without extensions:
    • .vscode/settings: Fix file associations.

• The subject briefly describes what was changed. Use a short full sentence as in the examples above.

• The body describes why the change was made, e.g. The word "sensor" was spelled incorrectly.

Development environment:

Prerequisites:

• VS Code (optional but recommended)
• Git
• Python 3
• Poetry

Information on installing prerequisites can be found on the pybricks-micropython wiki.

Initial setup:

git clone --recursive https://github.com/pybricks/pybricks-api
cd pybricks-api
poetry install

Build docs:

# Linux
poetry run make -C doc html SPHINXOPTS=-tmain
xdg-open doc/main/build/html/index.html

# macOS
poetry run make -C doc html SPHINXOPTS=-tmain
open doc/main/build/html/index.html

# Windows (PowerShell)
poetry run doc\make.bat html SPHINXOPTS=-tmain
Invoke-Item doc\main\build\html\index.html

Linting:

poetry run flake8  # check Python
poetry run doc8  # check Restructured Text