Skip to content

Latest commit

 

History

History
119 lines (77 loc) · 5.17 KB

CONTRIBUTING.md

File metadata and controls

119 lines (77 loc) · 5.17 KB

Contributing to Bluetooth 2 USB

Thank you for considering contributing to Bluetooth 2 USB! We value your effort and are happy to provide guidelines to help you get started. Following these guidelines helps to communicate that you respect the time of the developers managing and developing this open-source project. But don't be too concerned if you're still new to all this. The maintainers are happy to assist and guide new contributors!

Table of Contents

1. Code of Conduct

By participating in this project, you are expected to uphold our Code of Conduct.

2. Getting Started

  • Fork the repository on GitHub

  • Install required packages to your Linux machine:

    sudo apt update && sudo apt install -y git python3.11 python3.11-venv

  • Clone the forked repository and cd into it:

    git clone https://github.com/YOUR-ACCOUNT/bluetooth_2_usb.git && cd bluetooth_2_usb

  • Create a Python virtual environment:

    python3.11 -m venv venv

  • Install dependencies in venv:

    venv/bin/pip3.11 install -r requirements.txt

  • Open the repo in your favorite IDE

  • Make sure that your IDE is using python3.11 from bluetooth_2_usb/venv/bin/, e.g., in VS Code:

    CTRL + SHIFT + P > type Python Select Interpreter > select Enter interpreter path > select Find...

3. Coding Style

We value code readability and consistency. To ensure that your contributions align with the project's coding style, please follow these guidelines:

3.1. Best Practices for Clean and Maintainable Code

Adherence to widely accepted best practices is crucial for creating code that is clean, maintainable, and efficient. Below are some of the general guidelines you should follow, particularly with regard to Object-Oriented Programming (OOP).

3.1.1. General Guidelines

  • Opt for readability over compact code: make sure your code is easy to read and understand.
  • Use meaningful variable and function names.
  • Keep functions small and focused.
  • Document your code properly with comments and docstrings.

3.1.2. Object-Oriented Programming (OOP) Guidelines

  • Use encapsulation by limiting the direct manipulation of object attributes and using methods instead.
  • Employ inheritance wisely to reuse code and create a logical relationship between classes.
  • Leverage polymorphism to allow objects to take on more than one form.
  • Follow the Single Responsibility Principle: a class should have only one reason to change.
  • Make use of design patterns where appropriate.

To learn more about OOP and best practices, consider reviewing:

3.2. Code Formatting with Black

We use Black for code formatting. Before committing any code, please make sure to run Black to keep the coding style consistent:

Install Black:

pip install black

Run Black:

black .

This will automatically reformat your code to conform to the project's coding style. There are also plugins available for many IDEs, e.g. for vscode.

4. Pull Requests

  • Create a new branch for each feature or bugfix you are working on.
  • Commit your changes following the coding style guidelines. Add concise commit messages.
  • Push your changes to your fork.
  • Create a new Pull Request targeting the main branch of the official repository. A short description helps the maintainers reviewing the changes.

5. Reporting Issues

Please use the GitHub issue tracker to report any bugs or to request new features. Make sure to check for existing issues that are related to yours before creating a new one.

Thank you for taking the time to contribute!