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

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

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

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