Files

Andrey Kruchinkin 7a78bf43ce chore: каркас репозитория и правила оформления библиотек

Репозиторий собирает переносимые библиотеки, которые до сих пор жили копиями
внутри прошивок: одни и те же st7789, keypad, menu и eeprom лежали в
KONOR_ds18b20 и OpticalTester побайтово одинаковыми и расходились при первой
же правке на месте.

CONTRIBUTING описывает критерий отбора (ядро без HAL, регистров, ОС и
динамической памяти; всё аппаратное — в порте), обязательный состав README
библиотеки и формат коммитов.

2026-08-23 01:14:43 +03:00

5.0 KiB

Raw Permalink Blame History

Как добавлять и править библиотеки

Что попадает в этот репозиторий

Библиотека принимается, если её ядро:

собирается любым компилятором C99 (для Python — на чистой stdlib);
не включает заголовки микроконтроллера, HAL, CMSIS и SDK;
не обращается к регистрам и не заводит своих прерываний;
не пользуется динамической памятью;
не держит глобального состояния: всё живёт в структуре вызывающего, поэтому в одной прошивке поднимается сколько угодно экземпляров.

Всё аппаратное выносится в порт — таблицу обратных вызовов. Хороший размер порта: от трёх до шести функций. Если их получается пятнадцать, граница проведена не там.

Код, привязанный к плате, остаётся в проекте. Если его хочется перенести — не копируйте, а сначала отделите платформу; заметку о том, что именно мешает, допишите в раздел «Что сюда не попало» корневого README.

Раскладка библиотеки

c/<имя>/
  README.md            обязательно
  <имя>.h, <имя>.c     ядро
  ports/<платформа>/   пример порта, если он есть
  tests/               хостовые тесты, если они есть

Имена каталогов — строчными, слова через дефис (eeprom-ft24c256).

README библиотеки

Обязателен для каждой. Минимум:

одна строка о том, что библиотека делает;
чем она не является — от чего не зависит, чего внутри нет;
схема слоёв: приложение → ядро → порт → платформа;
таблица файлов с зависимостями;
контракт порта — прототипы обратных вызовов;
быстрый старт: рабочий фрагмент на 10–15 строк;
в каких проектах уже используется.

Описание пишется для того, кто видит библиотеку впервые и решает, подойдёт ли она ему, — не для того, кто её написал.

Doxygen-комментарии в заголовке README не заменяют, и наоборот: в заголовке — контракт каждой функции, в README — зачем всё это вместе.

Совместимость

Публичный API — это обещание: его ломают осознанно и описывают в теле коммита (что изменилось и что делать проектам). Молчаливое переименование поля структуры ломает чужую сборку через месяц, когда никто уже не помнит почему.

Правки вносятся здесь, а не в копии внутри проекта. Копия, которую поправили на месте, — источник расхождения версий.

Коммиты

Conventional Commits: область — имя библиотеки, текст по-русски, повелительное наклонение, строка заголовка до 72 символов.

feat(st7789): драйвер TFT-панелей ST7789V поверх SPI
fix(menu): курсор не уезжает за последний пункт на пустом экране
docs(keypad): контракт порта и быстрый старт
refactor(pcan): разбор кадра вынесен из обработчика прерывания
test(ds18b20): проверка CRC8 на эталонных scratchpad
chore: правила оформления библиотек

Типы: feat, fix, docs, refactor, test, perf, build, chore.

Один коммит — одно изменение в одной библиотеке. Коммит «поправил всё» невозможно ни прочитать, ни откатить.

Тело коммита отвечает на «почему», а не на «что»: что именно изменилось, видно из диффа.

Ветки

master держится собираемым. Работа идёт в ветках feat/<имя> и fix/<имя>; вливание — после того, как хостовые тесты библиотеки прошли.

5.0 KiB Raw Permalink Blame History Unescape Escape