# Выпуск прошивок

Репозиторий живёт на <https://git.meshinfo.ru/shade/MeshCore-Posadmesh>. Прошивки собираются локально через [`posadmesh-build.sh`](./posadmesh-build.sh) или на сервере ручным workflow Gitea Actions; теги и релизы создаются в веб-интерфейсе git.meshinfo.ru.

## Сборка на сервере (Gitea Actions)

Ручной workflow [`.gitea/workflows/build-mqtt-firmwares.yml`](./.gitea/workflows/build-mqtt-firmwares.yml) запускается из веб-интерфейса: **Actions → Build MQTT firmwares → Run workflow**.

Параметры запуска:

- `firmware_version` — версия upstream MeshCore для метаданных (например `v1.17.1`);
- `posadmesh_version` — версия релиза PosadMesh (например `v2026.10.0`);
- `group` — что собирать: `all` (все MQTT-таргеты), `uplink`, `espnow`, `bridge` или `single`;
- `target` — имя окружения PlatformIO, если `group=single` (например `heltec_v4_repeater_mqtt`);
- `publish` — `true`, чтобы создать релиз Gitea и загрузить в него файлы (`false` по умолчанию — только артефакты сборки);
- `tag` — тег релиза при `publish=true` (например `repeater-mqtt-v2026.10.0`).

Для публикации в репозитории должен быть задан секрет `GITEA_TOKEN` (personal access token с правом `write:repository`).

Требования к раннеру: Linux с Docker, интернет, `python3` ≥ 3.11, `git`, `curl` и не меньше 20 ГБ свободного места — PlatformIO скачивает тулчейны ESP32 при первой сборке (шаг кэша `~/.platformio` ускоряет последующие запуски). Полная сборка всех MQTT-таргетов идёт долго, поэтому удобнее запускать по группам.

## Ручная выгрузка в релиз

Если прошивки собраны локально (каталог `out/`), файлы можно загрузить в релиз Gitea скриптом:

```bash
GITEA_TOKEN=<token> posadmesh-tools/publish-gitea-release.sh \
    repeater-mqtt-v2026.10.0 out "Repeater MQTT v2026.10.0"
```

Скрипт создаёт релиз, если его ещё нет, и повторный запуск не дублирует уже загруженные файлы. Адрес инстанса и репозиторий можно переопределить переменными `GITEA_URL` и `GITEA_REPO`.

Тег удобнее создать заранее на нужном коммите (см. порядок выпуска ниже): тогда релиз привяжется к существующему тегу. Если тега нет, Gitea создаст его сам от HEAD ветки по умолчанию — для релизов этого лучше избегать.

Каждый трек публикуется в свой релиз: соберите группу (`uplink`, `espnow` или `bridge`) и выгрузите её файлы под тегом этого трека. Каталог `out/` очищается в начале каждой сборки, поэтому в релиз попадут файлы только одной группы.

## Версии сборки

- `FIRMWARE_VERSION` — версия upstream MeshCore, на которой основана сборка (например `v1.15.0`)
- `POSADMESH_VERSION` — версия релиза PosadMesh (например `v2026.5.1`)

Обе задаются переменными окружения перед запуском сборки:

```bash
export FIRMWARE_VERSION=v1.15.0
export POSADMESH_VERSION=v2026.5.1
bash posadmesh-build.sh build-firmware heltec_v4_repeater_mqtt
```

## Теги релизов PosadMesh

Один или несколько тегов следующих форматов помечают релиз соответствующего трека:

- `repeater-bridge-espnow-v1.15.0`
- `repeater-mqtt-espnow-v2026.5.1`
- `repeater-mqtt-bridge-v2026.7.0`
- `repeater-mqtt-v2026.5.1`

В `repeater-bridge-espnow-v1.15.0` используется версия upstream MeshCore.
В `repeater-mqtt-espnow-v2026.5.1` используется версия релиза PosadMesh.
В `repeater-mqtt-bridge-v2026.7.0` используется версия релиза PosadMesh.
В `repeater-mqtt-v2026.5.1` используется версия релиза PosadMesh.

Соответствие тегов и треков:

- `repeater-bridge-espnow-v*` — прошивка ESP-NOW-моста репитера
- `repeater-mqtt-espnow-v*` — прошивка MQTT-репитера с ESP-NOW
- `repeater-mqtt-bridge-v*` — прошивка MQTT-репитера с MQTT-мостом
- `repeater-mqtt-v*` — прошивка MQTT-репитера

Сборка выполняется локально для нужного таргета; тегов на одном коммите может быть несколько.

## Итоговая версия прошивки

- `repeater-bridge-espnow` использует версию из тега как `FIRMWARE_VERSION`
- `repeater-mqtt-espnow` использует `FIRMWARE_VERSION` upstream MeshCore, а версию PosadMesh из тега — как `POSADMESH_VERSION`
- `repeater-mqtt-bridge` использует `FIRMWARE_VERSION` upstream MeshCore, а версию PosadMesh из тега — как `POSADMESH_VERSION`
- `repeater-mqtt` использует `FIRMWARE_VERSION` upstream MeshCore, а версию PosadMesh из тега — как `POSADMESH_VERSION`

Итоговая строка версии зависит от трека:

- `repeater-bridge-espnow`: `v1.15.0-<commit>`
- `repeater-mqtt-espnow`: `v1.15.0-posadmesh-v2026.5.1-<commit>`
- `repeater-mqtt-bridge`: `v1.15.0-posadmesh-v2026.7.0-<commit>`
- `repeater-mqtt`: `v1.15.0-posadmesh-v2026.5.1-<commit>`

Пример:

- тег: `repeater-mqtt-v2026.5.1`
- переменные: `FIRMWARE_VERSION=v1.15.0`, `POSADMESH_VERSION=v2026.5.1`
- итоговая версия сборки: `v1.15.0-posadmesh-v2026.5.1-abcdef`

## Типичный порядок выпуска

1. Обновите `release-notes.yml` в ветке `develop` — добавьте записи о релизе, которые должны войти в помечаемый тегом коммит.
2. Откройте и смерджите релизный PR из `develop` в `main`.
3. Соберите нужные прошивки локально с подходящими `FIRMWARE_VERSION` и `POSADMESH_VERSION`.
4. Создайте нужные теги релиза на целевом коммите в `main`.
5. Запушьте теги в git.meshinfo.ru.
6. Создайте релиз в веб-интерфейсе git.meshinfo.ru и приложите собранные файлы из `out/`.

Если `release-notes.yml` должен отражать помеченный тегом релиз прошивки в репозитории, внесите это изменение до PR в `main`, чтобы помечаемый коммит уже содержал соответствующие примечания к релизу.

Пример:

```bash
export FIRMWARE_VERSION=v1.15.0
export POSADMESH_VERSION=v2026.5.1
bash posadmesh-build.sh build-repeater-mqtt-firmwares

git tag repeater-mqtt-v2026.5.1
git push origin repeater-mqtt-v2026.5.1
```

## Поддерживаемые теги

- `repeater-bridge-espnow-v1.15.0`
- `repeater-mqtt-espnow-v2026.5.1`
- `repeater-mqtt-bridge-v2026.7.0`
- `repeater-mqtt-v2026.5.1`