Contributing Guide

Relevant source files

The following files were used as context for generating this wiki page:

• README.md
• tools/checkstyle.py
• tools/run_tests.py
• CHANGELOG.md
• tests/test_list.txt
• setup.py
• pyrightconfig.json

This guide provides instructions and best practices for contributing to the picamera2 project. Adhering to these guidelines helps maintain code quality, ensures stability, and facilitates the review process for pull requests. Contributions can range from bug fixes and feature additions to documentation improvements.

The project welcomes pull requests that fix bugs, add features, and generally improve the code. For more involved changes, especially those affecting public APIs, it is recommended to start a discussion with the maintainers first to agree on a way forward.

Sources: README.md:33-45

Getting Started

Branching Strategy

The repository uses a specific branching strategy to separate development from stable releases.

• main branch: Corresponds to the currently released version of picamera2. This branch is for users to refer to for examples and stable code.
• next branch: All development for forthcoming releases happens on this branch. Pull requests should typically be targeted at the next branch.

Sources: README.md:31-32, README.md:35

This diagram illustrates the branching and release flow.

Setting Up the Development Environment

To contribute, you will need to set up a local development environment. This involves cloning the repository and installing dependencies. While picamera2 can be installed via pip, it is recommended to use apt for a consistent environment.

The project dependencies are listed in setup.py and include libraries such as numpy, pillow, and pyqt5 for the GUI components.

Sources: README.md:19-29, setup.py:29-33

Pull Request Guidelines

To ensure a smooth review process, all pull requests (PRs) must follow specific guidelines.

Guideline	Description
Scope	Each PR should be restricted to a single change or feature. Avoid "drive-by fixes" in a larger set of changes.
Commit History	The commit history must be clean and easy to review. This means merging fixup commits, removing reverted commits, and avoiding unnecessary merge commits.
Commit Messages	Commit messages should have a short, descriptive single-line summary, followed by a more detailed explanation.
Automated Tests	All automated tests must be passing before submitting a PR.
Documentation	Documentation, examples, and tests should be updated or added as necessary. Consider adding an entry to the CHANGELOG.md.
Sign-off	The author must agree to donate the work by signing off on their commits.

Sources: README.md:35-58, CHANGELOG.md

The Pull Request Process

The following diagram outlines the recommended workflow for submitting a contribution.

Commit Sign-off

To indicate agreement to donate the work to the project and Raspberry Pi Ltd., commit messages must be signed off. This is done by adding a blank line at the end of the commit message, followed by:

Signed-off-by: Your Name <your.email@your.domain>

Sources: README.md:56-58

Code Quality and Style

The project aims to conform to the Python PEP 8 coding style. To enforce this and other quality checks, a combination of pre-commit hooks and a custom style-checking script is used.

Pre-commit Hooks

The repository provides a pre-commit hook configuration to automatically lint changes before committing. This helps catch style issues early. To install and use it, run the following commands in the root of the repository:

pip3 install pre-commit
pre-commit install

This will install flake8 in a virtual environment and run it on your changes prior to each commit.

Sources: README.md:60-67

The pre-commit workflow is illustrated below:

Style Checking with checkstyle.py

The tools/checkstyle.py script is a comprehensive style and format checker. It can be run on a git revision range, staged changes, or the last commit. It uses a series of checkers and formatters to validate the code.

The script can check:

• Staged changes: python3 tools/checkstyle.py --staged
• The last commit: python3.tools/checkstyle.py HEAD
• A range of commits: python3 tools/checkstyle.py main..next

Sources: tools/checkstyle.py:603-610

Checkers and Formatters

checkstyle.py includes several classes for checking style and formatting code.

The diagram below shows the structure of the style checkers.

The script also applies formatters to ensure consistent code layout.

Formatter Class	Supported File Patterns	Description
CLangFormatter	*.c, *.cpp, *.h, *.hpp	Formats C/C++ code using clang-format.
IncludeOrderFormatter	*.cpp, *.h, *.hpp	Sorts #include statements alphabetically.
StripTrailingSpaceFormatter	*.c, *.cpp, *.h, *.hpp, *.py, CMakelists.txt	Removes trailing whitespace from lines.

Sources: tools/checkstyle.py:461-463, tools/checkstyle.py:471-473, tools/checkstyle.py:504-506

Type Checking

The project uses pyright for static type checking, configured via pyrightconfig.json. This helps catch type-related errors. The configuration is set to "basic" mode and reports various potential issues as warnings.

Sources: pyrightconfig.json

Automated Testing

All contributions must pass the automated tests. The test suite can be executed using the tools/run_tests.py script.

Running Tests

To run the tests, execute the script from the root of the repository:

./tools/run_tests.py

The script accepts several arguments to customize its behavior:

• --dir: Folder where tests are run (default: /home/pi/picamera2_tests).
• --picamera2-dir: Location of the picamera2 repository (default: /home/pi/picamera2).
• --test-list-files: Comma-separated list of files containing tests to run.

Sources: README.md:50-51, tools/run_tests.py:120-127

Test Execution Flow

The run_tests.py script iterates through a list of test files, executes each one, and checks the output for errors.

The test execution process is as follows:

The script considers a test failed if it returns a non-zero exit code, times out (after 90 seconds), or if its output contains the string "error" (case-insensitive), with some specific exceptions.

Sources: tools/run_tests.py:90-107

Documentation and Changelog

When adding new features or making significant changes, please update the relevant documentation. New examples and tests are also highly encouraged. Additionally, consider making an entry in the CHANGELOG.md file to track the changes for the next release.

Sources: README.md:52-53, CHANGELOG.md