shade/MeshCore-Posadmesh
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 3 Wiki Activity
Files
main
MeshCore-Posadmesh/AGENTS.md
T
shade 26b724c0f0 feat: manual Gitea build workflow, release publishing, README and docs update 
- добавлен ручной workflow Gitea Actions (.gitea/workflows/build-mqtt-firmwares.yml):
  сборка MQTT-прошивок на сервере и публикация релиза
- добавлен posadmesh-tools/publish-gitea-release.sh для выгрузки собранных файлов
  в релиз Gitea (идемпотентно, фильтр по треку)
- README: происхождение проекта переписано (форк EastMesh, доработка энтузиастов
  из Сергиева Посада, ориентация на meshcoretel.ru), добавлены раздел
  «Отличия от upstream MeshCore» и журнал «Изменения в проекте»
- убраны упоминания Австралии, ссылки на eastmesh.au и региональные материалы;
  руководство по прошивке переведено на файлы релизов и esptool.py
- posadmesh-build.sh: вывод PlatformIO очищается от \r — на Windows групповые
  команды сборки не находили ни одной цели; companion-команды удалены,
  добавлены build-mqtt-firmwares и list-mqtt
- release-notes.yml: треки repeater-mqtt*, запись 2026.10.0 дополнена удалением
  companion и исправлением сборки, companion-wifi помечен как снятый с выпуска
- AGENTS.md: правило дописывать изменения в README
- .gitignore: .pio-home
2026-10-11 17:20:05 +03:00

237 lines
11 KiB
Markdown
Raw Permalink Blame History

# AGENTS.md
## Назначение
Слой PosadMesh поверх upstream MeshCore.
**По умолчанию:** сохраняем поведение upstream.
Изменяем код только для чётко ограниченных возможностей PosadMesh:
- `*_repeater_mqtt`
- MQTT-аплинк/брокер
- веб-панель репитера
- документация, релизы, автоматизация
## Принципы
- Минимальные точечные изменения
- Предпочитаем дополнять, а не менять код upstream
- Избегаем посторонних рефакторингов
- Сохраняем паритет с поведением upstream
## Ограничения
### Upstream
- Не менять постороннюю логику MeshCore
- Не менять семантику CLI без явной необходимости
- Не вносить ломающие изменения в существующие таргеты
### Документация (обновлять в том же PR, когда это возможно)
| Изменение | Файл |
| --------------------- | ----------------------------- |
| CLI | `posadmesh-docs/custom-cli.md` |
| UI/поведение веб-панели | `posadmesh-docs/web-panel.md` |
| Релизы | `release-notes.yml` |
| Руководство по прошивке | `posadmesh-docs/releases.md` |
### Контроль веб-панели
Если правите `examples/simple_repeater/MyMesh.cpp`, обновите также `posadmesh-docs/custom-cli.md`.
## Инструменты
- Использовать `uv` + PlatformIO через `uv run`
- Не рассчитывать на глобально установленный `pio`
### Политика сборок
Сборки дорогие. Избегать без необходимости.
НЕ собирать для:
- только документация / HTML / CSS
Предпочитать:
- локальные сборки, запускаемые пользователем
- рассуждения вместо выполнения
Собирать только если:
- изменение высокого риска
- нужно проверить поведение прошивки
### Команды
```bash
uv sync
uv run pio run -e <env>
uv run pio device monitor --port <port> --baud 115200
uv run --group docs zensical serve
uv run --group docs zensical build
```
Не рассчитывайте, что `pio` установлен глобально.
## Частые команды
Показать список таргетов сборки:
```bash
bash posadmesh-build.sh list
```
Собрать один таргет:
```bash
uv run pio run -e heltec_v4_repeater_mqtt
uv run pio run -e T_Beam_S3_Supreme_SX1262_repeater_mqtt
uv run pio run -e heltec_v4_repeater_mqtt_espnow
uv run pio run -e T_Beam_S3_Supreme_SX1262_repeater_mqtt_bridge
```
Сборка с релизными метаданными:
```bash
export FIRMWARE_VERSION=v1.15.0
export POSADMESH_VERSION=v2026.5.1
bash posadmesh-build.sh build-firmware heltec_v4_repeater_mqtt
bash posadmesh-build.sh build-firmware T_Beam_S3_Supreme_SX1262_repeater_mqtt
```
Прошить таргет:
```bash
uv run pio run -e heltec_v4_repeater_mqtt -t upload --upload-port /dev/tty.usbmodemXXXX
uv run pio run -e T_Beam_S3_Supreme_SX1262_repeater_mqtt -t upload --upload-port /dev/tty.usbmodemXXXX
```
## Ключевые файлы
- `posadmesh-build.sh` — обёртка сборки PosadMesh
- `build.sh` — обёртка сборки upstream MeshCore, сохранена ради чистоты слияний
- `platformio.ini`
- `variants/posadmesh_mqtt/platformio.ini`
- `examples/simple_repeater/MyMesh.cpp`
- `src/helpers/mqtt/MQTTUplink.cpp`
- `posadmesh-docs/*.md`
- `RELEASE.md`
- `release-notes.yml`
## Принадлежность workflow
Репозиторий живёт на <https://git.meshinfo.ru/shade/MeshCore-Posadmesh>.
Собственные workflow:
- `.gitea/workflows/build-mqtt-firmwares.yml` — ручная сборка MQTT-прошивок на сервере Gitea Actions (`workflow_dispatch`): собирает группу или один таргет, умеет создавать релиз Gitea и загружать в него файлы. Публикация использует секрет репозитория `GITEA_TOKEN`.
Кроме workflow прошивки собираются локально через `posadmesh-build.sh`, а теги и релизы создаются в веб-интерфейсе git.meshinfo.ru. Выгрузка собранных файлов в релиз — через `posadmesh-tools/publish-gitea-release.sh`.
Workflow upstream MeshCore в `.github/workflows/` остаются под исходными именами файлов ради чистоты слияний. Не адаптируйте их под поведение PosadMesh; держите их близко к upstream. Они не используются для релизов PosadMesh.
## Требования к синхронизации документации
Если вы меняете что-либо из перечисленного, обновляйте документацию в том же PR, когда это возможно:
- Любые изменения в проекте:
- дописать запись о них в раздел «Изменения в проекте» файла `README.md`
- Команды веб-панели:
- обновить `posadmesh-docs/custom-cli.md`
- Пользовательское поведение, разделы, элементы управления или диагностика веб-панели:
- обновить `posadmesh-docs/web-panel.md`
- Добавления в CLI PosadMesh или изменения семантики:
- обновить `posadmesh-docs/custom-cli.md`
- Подготовка релиза/тега:
- обновить `release-notes.yml`
- Руководство по прошивке и файлам релиза:
- обновить `posadmesh-docs/releases.md`
## Замечания по MQTT-репитерам
Сборки `*_repeater_mqtt` могут включать локальную HTTPS-веб-панель на поддерживаемых таргетах ESP32.
Эксплуатационные рекомендации уже отражены в документации:
- использовать для первичной настройки и диагностики
- после этого предпочитать `set web off` для максимального запаса heap
## Границы продукта
Проект собирает и поставляет только MQTT-прошивки (`*_repeater_mqtt`, `*_repeater_mqtt_espnow`, `*_repeater_mqtt_bridge`). Связанные с этим правила:
- текущая официальная версия MeshCore — `v1.15.0`
- линия companion-прошивок удалена из проекта: окружения `*_companion_radio_*` и код `examples/companion_radio` остаются в upstream-оверлеях, PosadMesh их не собирает и не документирует
- не придумывайте отдельные номера версий PosadMesh для треков, которых нет в `release-notes.yml`
## Процесс релиза
Текущие форматы тегов:
```bash
git tag repeater-bridge-espnow-v1.15.0
git tag repeater-mqtt-espnow-v2026.5.1
git tag repeater-mqtt-bridge-v2026.7.0
git tag repeater-mqtt-v2026.5.1
```
Правила:
- теги `repeater-bridge-espnow` используют версию upstream MeshCore напрямую
- теги `repeater-mqtt-espnow` используют версию релиза PosadMesh в теге
- теги `repeater-mqtt-bridge` используют версию релиза PosadMesh в теге
- теги `repeater-mqtt` используют версию релиза PosadMesh в теге
- переменная `FIRMWARE_VERSION` при локальной сборке задаёт базовую версию upstream для релизных сборок треков `repeater-mqtt`, `repeater-mqtt-espnow` и `repeater-mqtt-bridge`
- переменная `POSADMESH_VERSION` при локальной сборке задаёт версию релиза PosadMesh
- если версия релиза upstream MeshCore изменилась, обновите `FIRMWARE_VERSION` при сборке и в документации
Типичный порядок выпуска:
1. Обновить `release-notes.yml` в ветке `develop`.
2. Смерджить релизный PR из `develop` в `main`.
3. Собрать нужные прошивки — локально или ручным workflow в Gitea Actions — с подходящими `FIRMWARE_VERSION` и `POSADMESH_VERSION`.
4. Создать нужный тег или теги релиза на целевом коммите в `main`.
5. Запушить теги в git.meshinfo.ru и создать релиз в его веб-интерфейсе.
## Синхронизация с upstream
Когда просят подтянуть изменения из upstream MeshCore:
- тянуть из `meshcore-dev/MeshCore:dev`
- начинать с локальной ветки `develop`
- создать временную интеграционную ветку от `develop`
- влить upstream `dev` в эту временную интеграционную ветку
- разрешать конфликты так, чтобы сохранить изменения, специфичные для PosadMesh
- влить готовую интеграционную ветку обратно в `develop`
Не вливайте upstream напрямую в `main`.
## Границы области работ
НЕ делать (без явной просьбы):
- переименовывать треки
- менять форматы тегов
- расширять CLI без обновления документации
- менять семантику CLI upstream
- вводить новые схемы версионирования
## Сообщения коммитов
Используйте краткие общепринятые префиксы:
- `feat:` новая функциональность
- `fix:` исправления ошибок
- `docs:` изменения документации
- `chore:` обслуживание, инструменты, нефункциональное
- `refactor:` изменения кода без изменения поведения
Держите сообщения короткими и по делу.
## Правило принятия решений
Если изменение не является явно специфичным для PosadMesh, не меняйте код.
При сомнениях предпочитайте не менять ничего или запросить уточнение.
Reference in new issue View Git Blame Copy Permalink