bearwave/CONTRIBUTING.md

Contributing to BearWave

BearWave is a KDE-focused desktop internet radio app built with C++/Qt 6, QML, and QtMultimedia.

The project favors:

• stability over feature churn
• minimal dependencies
• readable, conservative code
• Plasma-friendly desktop behavior

Before You Contribute

• Check existing issues before opening a new one.
• Prefer focused pull requests over broad refactors.
• Keep behavior predictable for desktop users.
• Avoid adding dependencies unless there is a clear payoff.

Local Setup

Build from the repository root:

cmake -S . -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build -j"$(nproc)"

Optional local install:

cmake --install build --prefix "$HOME/.local"

If you changed QML:

qmllint src/qml/Main.qml src/qml/components/*.qml src/qml/theme/BearTheme.qml

Run unit tests after backend changes:

ctest --test-dir build --output-on-failure

Change Guidelines

• Follow the existing style in each file.
• Keep changes minimal and scoped.
• Do not block the UI thread.
• Keep network operations asynchronous.
• Preserve MPRIS behavior and user state compatibility.
• When changing resources, register them in src/qml.qrc.

Manual Checks

Please smoke-test the area you changed when possible:

• app launches successfully
• station list loads
• search and filtering behave correctly
• play/pause/stop work
• favorites persist across restart
• resume restores last station and volume
• tray and MPRIS behavior still work

Pull Requests

Useful pull requests usually include:

• a short description of the user-visible change
• any relevant screenshots for UI changes
• exact verification commands that were run
• known limitations or follow-up work