Contributing

Thanks for improving miband-bot. This project is intentionally small: keep changes practical, testable and clear for self-hosted users.

Local Setup

python3 -m venv .venv
.venv/bin/pip install -r requirements-dev.txt -e mi-fitness-python

Run checks before opening a pull request:

.venv/bin/python -m py_compile fitness_bot.py miband_sync.py $(find miband_tracker -name '*.py' | sort)
.venv/bin/python -m pytest
.venv/bin/python -m pytest mi-fitness-python/tests/unit
.venv/bin/ruff check .
.venv/bin/python -m pip check
docker compose build

Secrets

Never commit real files from:

secrets.env;
data/;
token*.json;
status*.json;
SQLite databases or CSV exports.

Use secrets.env.example in documentation and tests.

Code Style

Prefer the existing Python style and small focused modules.
Keep user-facing Telegram text clear and concise.
Add tests for behavior changes.
Keep Russian UI text valid; Ruff RUF001/RUF002/RUF003 are ignored because Cyrillic strings are intentional.
Do not mass-format vendored mi-fitness-python unless the change is specifically about updating that vendor copy.

Reverse Engineering Etiquette

This project talks to unofficial Xiaomi Fitness APIs. Contributions must stay focused on legitimate personal use:

do not add features for accessing other people's data without permission;
do not publish real credentials, account ids, request signatures or private exports;
document fragile API assumptions when adding reverse-engineered behavior;
make optional/best-effort features fail gracefully when Xiaomi changes an endpoint.

Vendored SDK

mi-fitness-python is kept in this repository as a vendored source copy. See VENDORED.md before changing it. When updating the vendor copy, document the upstream source, version or commit, and any local patches.

1.8 KiB Raw Blame History