Contributing

Thanks for considering contributing!

The following is a set of guidelines for contributing to the repository. These are guidelines, not hard rules.

Contributions of all kinds are welcome: bug reports, new features, documentation improvements, tests, examples, etc.

Questions

Generally questions are better suited in GitHub Discussions.

Please do not use issues for questions. Most of them don’t belong there unless they provide value to a larger audience.

Don’t know where to start ?

If you want to contribute but aren’t sure how to begin, here are some ways to get involved:

  • Visit Issues to reproduce bugs, provide additional details, or suggest fixes.

  • Review Pull Requests to help with code reviews, testing, and feedback.

  • Participate in Discussions.

  • Improve existing documentation, add examples, or clarify explanations.

  • Add new scripts in examples/ to showcase library usage.

  • Write tests for untested features and increase coverage.

  • Refactor code, improve type hints, and maintain consistency.

  • Implement new features or small improvements.

You can also check ongoing work and ideas in the Repository Projects.

Starting with small contributions is encouraged, every little improvement helps.

Community

Have an idea, want to discuss a potential feature, or just want to follow along with where the project is heading ? Join the conversation in the #bikeshedding channel on our Discord server.

GitHub Discussions as an alternative to Discord, is also a great place to propose ideas, share feedback, or ask questions.

Getting Started

  1. Fork the repository.

  2. Clone your fork locally:

    git clone https://github.com/<your-username>/OBDII
cd OBDII

  3. Create a new branch for your work:

    git checkout -b my-feature-branch

  4. Create a Virtual Environment (recommended):

    Linux/macOS

    python3 -m venv .venv
source .venv/bin/activate

    Windows

    py -3 -m venv .venv
.venv\Scripts\activate

  5. Install the library with the [dev,test,docs,sim] extra options:

    pip install -e .[dev,test,docs,sim]

    The -e (editable) flag lets you modify the source code, with changes taking effect immediately without reinstalling the library.

Bug Reports

Report bugs via Issues.

Include the following to help us resolve them quickly:

  • Search for existing issues to avoid duplicates.

  • Provide a clear and descriptive title.

  • Describe the steps to reproduce the issue, ideally with a minimal code snippet.

  • Expected vs. actual behavior, what you thought would happen vs. what happened.

  • Environment details, Python and library version, OS, OBDII device model, and install method.

  • Full traceback and/or logs if applicable.

Incomplete bug reports may require follow-up questions and could be closed if not clarified.

Pull Requests

Before opening a pull request, please make sure that:

  • Ideally the code follows the existing style.

  • Each PR is focused on a single issue or feature.

  • You reference related issues (e.g., “Fix #123”).

Before implementing a large feature or a breaking change, consider discussing it first in the #bikeshedding channel on Discord, this helps avoid wasted effort and ensures alignment with project goals.

Code Formatting and Linting

This library uses ruff for code formatting and linting.

Install the development dependencies with:

pip install -e .[dev]

To check and fix linting issues, run:

  1. Check for linting issues

    ruff check obdii --diff

  2. Automatically fix issues

    ruff check obdii --fix

To format your changes, run:

  1. Preview formatting issues

    ruff format obdii --diff

  2. Automatically format code

    ruff format obdii

Testing

This library uses pytest for testing.

Install the testing dependencies with:

pip install -e .[test]

Tests are located in the tests/ folder.

Before opening a pull request, make sure that all tests pass:

pytest

Project Documentation

This library uses Sphinx for documentation. If you add or change features, please updates the documentation accordingly.

Install the documentation dependencies with:

pip install -e .[docs]

Sources are located in docs/source/.

To build and view the documentation locally, run:

sphinx-autobuild docs/source docs/build/html -a -n -T --keep-going

Reference Documentation

When implementing features, you can refer to the official ELM327 PDF, starting from page 8. This document outlines standard behaviors, AT commands, protocols, etc.

Other technical references exist, but are behind paywalls and are not currently available. See this and this for more details.

Your contributions make OBDII better and more reliable for everyone!