Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
341 lines (244 loc) · 8.23 KB

CONTRIBUTING.md

File metadata and controls

341 lines (244 loc) · 8.23 KB

Contributing to LibrePods

Thank you for your interest in contributing to LibrePods! This project aims to liberate AirPods from Apple's ecosystem, and we welcome contributions of all kinds.

Table of Contents

Code of Conduct

This project adheres to a code of conduct. By participating, you are expected to uphold this code. Please be respectful and constructive in all interactions.

How Can I Contribute?

Reporting Bugs

Before creating bug reports, please check existing issues. When creating a bug report, include:

  • Device Information: Phone model, OS version, AirPods model
  • LibrePods Version: Found in app settings
  • Root Status (Android): LSPosed version if applicable
  • Steps to Reproduce: Clear, numbered steps
  • Expected vs Actual Behavior
  • Logs: Use the troubleshooting feature in the app

Suggesting Features

Feature requests are welcome! Please:

  • Check if the feature has already been requested
  • Explain the use case and expected behavior
  • Consider if it aligns with the project's goals

Code Contributions

All code contributions follow the standard GitHub workflow:

  1. Fork the repository
  2. Create a feature branch
  3. Make your changes
  4. Submit a pull request

See Making Changes for detailed instructions.

Documentation

Improvements to documentation are always welcome, including:

  • README updates
  • Protocol documentation
  • Setup guides
  • Code comments

Translations

Help make LibrePods accessible to more users by contributing translations. See Translation Guide for details.

Development Setup

Prerequisites

Choose the platform you want to contribute to:

Android Development

Requirements:

  • Android Studio Narwhal (2025.1.x) or later
  • JDK 17+
  • Android SDK: API 35 (min) and API 36 (target)
  • Root access with Xposed Framework (LSPosed recommended)

Note: Root is required due to an Android Bluetooth stack limitation. Exception: ColorOS/OxygenOS 16 users.

Linux Development

Requirements:

  • Qt 6 (base, connectivity, multimedia)
  • CMake 3.22+
  • OpenSSL development headers
  • libpulse development headers
  • C++17 compatible compiler
Installation commands for different distributions

Arch Linux / EndeavourOS:

sudo pacman -S qt6-base qt6-connectivity qt6-multimedia cmake openssl libpulse

Debian / Ubuntu:

sudo apt-get install qt6-base-dev qt6-declarative-dev qt6-connectivity-dev \
    qt6-multimedia-dev cmake libssl-dev libpulse-dev \
    qml6-module-qtquick-controls qml6-module-qtquick-layouts

Fedora:

sudo dnf install qt6-qtbase-devel qt6-qtconnectivity-devel \
    qt6-qtmultimedia-devel qt6-qtdeclarative-devel cmake \
    openssl-devel pulseaudio-libs-devel

Building the Project

Android

git clone https://github.com/YOUR_USERNAME/librepods.git
cd librepods/android
./gradlew assembleDebug
adb install -r app/build/outputs/apk/debug/app-debug.apk

Linux

git clone https://github.com/YOUR_USERNAME/librepods.git
cd librepods/linux
mkdir build && cd build
cmake ..
make -j $(nproc)
./librepods

For troubleshooting, see linux/README.md.

Making Changes

1. Fork and Clone

Fork the repository on GitHub, then:

git clone https://github.com/YOUR_USERNAME/librepods.git
cd librepods
git remote add upstream https://github.com/kavishdevar/librepods.git

2. Create a Branch

git checkout -b feat/your-feature-name
# or
git checkout -b fix/bug-description

3. Make Your Changes

  • Write clear, readable code
  • Follow the style guidelines
  • Add comments for complex logic
  • Update documentation if needed

4. Test Your Changes

Android:

  • Build and install the APK
  • Test on a physical device with AirPods
  • Verify no regressions in existing features

Linux:

  • Build and run the application
  • Test core functionality
  • Verify system tray integration

5. Commit Your Changes

git add .
git commit -m "type(scope): description"

See Commit Message Guidelines for format details.

Submitting Changes

Pull Request Process

  1. Push to your fork:

    git push origin your-branch-name

  2. Create a Pull Request on GitHub with:

    • Clear title: type(scope): Brief description
    • Description including:
      • What changed and why
      • Related issue number (closes #123)
      • Testing performed
      • Screenshots for UI changes

  3. Wait for review (Note: Maintainer on hiatus until May 2026)

  4. Address feedback if requested

Pull Request Checklist

  • Code builds without errors
  • Tested on target platform
  • Follows style guidelines
  • Documentation updated (if applicable)
  • Commit messages follow convention
  • PR description is clear and complete

Style Guidelines

Commit Messages

Follow Conventional Commits:

<type>(<scope>): <description>

[optional body]

[optional footer]

Types:

  • feat: New feature
  • fix: Bug fix
  • docs: Documentation changes
  • style: Code style changes (formatting)
  • refactor: Code refactoring
  • test: Adding tests
  • chore: Maintenance tasks

Examples:

feat(android): add German translation
fix(linux): resolve system tray detection
docs: update development setup guide

Code Style

Kotlin (Android)

  • Follow Kotlin Coding Conventions
  • 4 spaces for indentation
  • Meaningful variable and function names
  • Use camelCase for variables/functions, PascalCase for classes

C++ (Linux)

  • Follow Qt Coding Style
  • Use camelCase for variables/functions
  • Use PascalCase for classes
  • Include proper header guards
  • Use C++17 features where appropriate

Additional Resources

Documentation

External Links

Community

Translation Guide

Translations help make LibrePods accessible to users worldwide. Currently supported: 10 languages (Android), 3 languages (Linux).

Android Translations

  1. Create translation directory:

    mkdir -p android/app/src/main/res/values-{LANG_CODE}

  2. Copy base strings file:

    cp android/app/src/main/res/values/strings.xml \
   android/app/src/main/res/values-{LANG_CODE}/

  3. Translate all <string> tags while preserving:

    • Placeholders: %1$s, %d
    • XML entities: \' for apostrophes
    • Technical terms from Apple's official translations

  4. Test:

    cd android
./gradlew assembleDebug
adb shell "setprop persist.sys.locale {LANG_CODE}; setprop ctl.restart zygote"

Linux Translations

  1. Copy template:

    cd linux/translations
cp librepods_tr.ts librepods_{LANG_CODE}.ts

  2. Edit with Qt Linguist (recommended) or manually:

    <message>
    <source>English text</source>
    <translation>Translated text</translation>
</message>

  3. Test:

    mkdir build && cd build
cmake .. && make
LANG={LANG_CODE}.UTF-8 ./librepods

Needed Languages

High-priority: German, Japanese, Korean, Hindi, Arabic, Russian

License

By contributing, you agree that your contributions will be licensed under the GNU GPL v3.0 License.

Thank you for contributing to LibrePods! 🎉