Andrey Kruchinkin
7a78bf43ce
Репозиторий собирает переносимые библиотеки, которые до сих пор жили копиями внутри прошивок: одни и те же st7789, keypad, menu и eeprom лежали в KONOR_ds18b20 и OpticalTester побайтово одинаковыми и расходились при первой же правке на месте. CONTRIBUTING описывает критерий отбора (ядро без HAL, регистров, ОС и динамической памяти; всё аппаратное — в порте), обязательный состав README библиотеки и формат коммитов.
87 lines
5.0 KiB
Markdown
87 lines
5.0 KiB
Markdown
# Как добавлять и править библиотеки
|
||
|
||
## Что попадает в этот репозиторий
|
||
|
||
Библиотека принимается, если её ядро:
|
||
|
||
* собирается любым компилятором C99 (для Python — на чистой stdlib);
|
||
* не включает заголовки микроконтроллера, HAL, CMSIS и SDK;
|
||
* не обращается к регистрам и не заводит своих прерываний;
|
||
* не пользуется динамической памятью;
|
||
* не держит глобального состояния: всё живёт в структуре вызывающего,
|
||
поэтому в одной прошивке поднимается сколько угодно экземпляров.
|
||
|
||
Всё аппаратное выносится в **порт** — таблицу обратных вызовов. Хороший размер
|
||
порта: от трёх до шести функций. Если их получается пятнадцать, граница
|
||
проведена не там.
|
||
|
||
Код, привязанный к плате, остаётся в проекте. Если его хочется перенести —
|
||
не копируйте, а сначала отделите платформу; заметку о том, что именно мешает,
|
||
допишите в раздел «Что сюда не попало» корневого README.
|
||
|
||
## Раскладка библиотеки
|
||
|
||
```
|
||
c/<имя>/
|
||
README.md обязательно
|
||
<имя>.h, <имя>.c ядро
|
||
ports/<платформа>/ пример порта, если он есть
|
||
tests/ хостовые тесты, если они есть
|
||
```
|
||
|
||
Имена каталогов — строчными, слова через дефис (`eeprom-ft24c256`).
|
||
|
||
## README библиотеки
|
||
|
||
Обязателен для каждой. Минимум:
|
||
|
||
1. одна строка о том, что библиотека делает;
|
||
2. чем она не является — от чего не зависит, чего внутри нет;
|
||
3. схема слоёв: приложение → ядро → порт → платформа;
|
||
4. таблица файлов с зависимостями;
|
||
5. контракт порта — прототипы обратных вызовов;
|
||
6. быстрый старт: рабочий фрагмент на 10–15 строк;
|
||
7. в каких проектах уже используется.
|
||
|
||
Описание пишется для того, кто видит библиотеку впервые и решает, подойдёт ли
|
||
она ему, — не для того, кто её написал.
|
||
|
||
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/<имя>`; вливание — после того, как хостовые тесты библиотеки прошли.
|