Andrey
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/<имя>`; вливание — после того, как хостовые тесты библиотеки прошли.
|