Перейти до змісту

Як зробити внесок у проєкт

Цей гайд пояснює, як робити внески в JAAM Fusion: від простих правок документації до змін прошивки та веб‑інтерфейсу.

Якщо ви вперше в проєкті — почніть з пунктів "Перед стартом" і "Швидкий процес".

Перед стартом

Де відбувається розробка

Ліцензія

Проєкт ліцензовано під CC BY‑NC‑SA 4.0.

  • Для некомерційного використання — вільно (з атрибуцією та ShareAlike).
  • Для комерційного використання потрібен письмовий дозвіл.

Деталі: файл LICENSE у корені репозиторію.

Типи внесків

Ви можете допомогти в різних напрямках:

  1. Документація (Wiki/MkDocs): виправлення неточностей, доповнення інструкцій, скріншоти.
  2. Прошивка (C++): багфікси, оптимізація, нові функції.
  3. Веб‑інтерфейс:
  4. фронтенд (web/scripts.js, web/styles.css)
  5. UI schema / контроли (web/controls.json, web/ui_schema_*.json)
  6. Якість: відтворювані багрепорти, перевірка на різних платах, логи.

Швидкий процес (PR)

  1. Створіть issue (або оберіть існуючий).
  2. Зробіть fork репозиторію.
  3. Створіть гілку:
  4. fix/... для багфіксів
  5. docs/... для документації
  6. feature/... для нових можливостей
  7. Внесіть зміни, перевірте збірку.
  8. Відкрийте Pull Request:
  9. опишіть що змінено і чому
  10. додайте посилання на issue
  11. додайте кроки перевірки/відтворення

Налаштування середовища

Збірка прошивки

Проєкт збирається через PlatformIO.

Збірка документації

Документація в цьому репозиторії збирається через MkDocs.

Рекомендований швидкий чек (якщо у вас налаштований .venv):

./.venv/bin/python -m mkdocs build -q

Note

Якщо у вас інше середовище Python — використовуйте той інтерпретатор/venv, де встановлено mkdocs.

Правила для документації

Принцип “тільки те, що є в прошивці”

Документація має відповідати реальній поведінці прошивки та UI.

Якщо ви додаєте/оновлюєте сторінку:

  • перевіряйте поля та назви секцій за UI schema (див. нижче)
  • якщо функція “планується”, але не працює — позначайте це явно

Текст посилань

Для внутрішніх посилань використовуйте людяний текст (назву сторінки/розділу), а не .../file.md.

✅ Добре:

  • [Мережа](../web-interface/sections/network.md)
  • [Оновлення прошивки](../web-interface/sections/firmware.md)

❌ Погано:

  • wiki/web-interface/sections/network.md

Де джерело істини для UI

UI генерується з UI schema. Якщо ви змінюєте UI або документуєте його — корисні матеріали:

Як змінювати UI (контроли/схему)

Найчастіший сценарій: додати новий контрол у веб‑інтерфейс.

Коротко:

  1. Додайте/змініть контрол у web/controls.json.
  2. Додайте відповідний mapping у src/JaamWeb.cpp.
  3. Переконайтесь, що налаштування існує в JaamConfig.h / JaamSettings.
  4. Перевірте, що зміна не ламає існуючі секції та сумісність.

Детальний процес: Довідник з додавання UI контролів.

Important

Веб‑ресурси стискаються перед збіркою і вбудовуються у прошивку. Про це детально: Web Assets.

Як робити багрепорт

Щоб issue можна було відтворити й швидко виправити, додайте:

  • версію прошивки
  • тип плати/чип (ESP32 / ESP32‑S3 / ESP32‑C3)
  • що саме підключено (main/bg/service LED, дисплей, сенсори, звук, сирена)
  • скріншот системної панелі та фрагмент логів
  • кроки відтворення

Для користувацьких проблем дивіться також:

Чекліст перед Pull Request

  • Зміна мінімальна й по суті (без зайвих рефакторингів “заодно”).
  • Для прошивки: pio run -e <env> проходить.
  • Для документації: mkdocs build проходить.
  • Тексти посилань у документації — назви сторінок/розділів.
  • У PR є пояснення “що/навіщо” і (за можливості) скріншоти/логи.

Потрібна допомога?