🤝 Contributing

🚀 Getting Set Up

🍴 Fork and Clone

# Fork the repo on GitHub, then:
git clone https://github.com/<your-username>/logitune.git
cd logitune

💻 Development Environment

make build
make setup-hooks
make test-all

🪝 Pre-Push Hook

make setup-hooks

Tip

This copies scripts/pre-push into .git/hooks/. It runs all three test tiers (C++, tray, QML) before allowing a push.

🌿 Branch Workflow

# Create a feature branch from master
git checkout master
git pull
git checkout -b feature/my-feature
# Make changes, commit, push
git add <files>
git commit -m "feat: add DPI shift button action"
git push -u origin feature/my-feature
# Open a PR against master

🎨 Code Style

💻 C++

🎨 QML

📄 Header Files

#pragma once // Always use pragma once (not include guards)
#include "..." // Project includes first
#include <...> // System/Qt includes second
namespace logitune {
class MyClass : public QObject {
 Q_OBJECT
 Q_PROPERTY(int value READ value NOTIFY valueChanged)
public:
 explicit MyClass(QObject *parent = nullptr);
 int value() const;
signals:
 void valueChanged();
private slots:
 void onSomethingHappened();
private:
 int m_value = 0;
};
} // namespace logitune

📝 Commit Message Format

<type>: <description>
[optional body]
[optional footer]

🏷️ Types

📋 Examples

feat: add DPI shift button action
Hold a button to temporarily lower DPI for precision aiming.
Implemented as ButtonAction::DpiShift with configurable target DPI.
feat: Flatpak packaging, devcontainer for GitHub Codespaces
fix: thumb wheel direction — clockwise should zoom in
Read defaultDirection from HID++ GetInfo to normalize
clockwise = positive in software.
refactor: extract TrayManager, fix battery initial value
test: add profile switch behavior tests for display vs hardware profile

📐 Multi-topic Commits

feat: thumb wheel overhaul — defaultDirection, invert, command queue, reconnect
Thumb wheel:
- Read defaultDirection from HID++ GetInfo to normalize clockwise=positive
- Add thumbWheelInvert as a proper profile field with UI toggle
- Add horizontal scroll injection (REL_HWHEEL) for scroll mode
HID++ command queue:
- New CommandQueue sends commands sequentially with 10ms pacing
- Eliminates HwError from flooding device during profile switches

✅ PR Checklist

Important

All PRs must pass the CI pipeline before merging. The pre-push hook helps catch failures early.

🗺️ Where to Find Things

🏛️ Key Design Decisions

Caution

These are intentional choices — please don't "fix" them:

Tip

For more details on these decisions, see Architecture.