diff --git a/00-principles.md b/00-principles.md index 1a8f4be..2b72828 100644 --- a/00-principles.md +++ b/00-principles.md @@ -31,3 +31,9 @@ ## 9. Уведомления через Synapse Исходящие уведомления (email, Telegram, webhooks) — через хаб Gnexus Synapse. Подробнее: [10-platform/notifications.md](10-platform/notifications.md). + +## 10. Обратная связь в общие ресурсы +Найден нюанс, несовершенство, баг или недоработка в общем ресурсе (ui-kit, клиентские +библиотеки, сервисы-хабы, контракты и протоколы) либо есть толковое предложение по +улучшению — запись об этом делается в проекте самого ресурса, в его документации, с +указанием источника, автора задачи и прочих метаданных. Подробнее: [10-platform/feedback.md](10-platform/feedback.md). diff --git a/10-platform/feedback.md b/10-platform/feedback.md new file mode 100644 index 0000000..9e42d56 --- /dev/null +++ b/10-platform/feedback.md @@ -0,0 +1,59 @@ +# Обратная связь в общие ресурсы + +Общие ресурсы экосистемы — gnexus-ui-kit, клиентские библиотеки (gnexus-auth-client-py, +gn-synapse-client-*), сервисы-хабы (gnexus-auth, Synapse), а также контракты, форматы и +протоколы между сервисами — живут в своих репозиториях. Проблема, найденная потребителем, +не должна оставаться только в потребителе: из следующего сервиса её найдут заново. + +## Правило + +Найден нюанс, несовершенство, баг или недоработка в общем ресурсе — либо есть толковое +предложение по улучшению (в том числе по контракту, протоколу, формату обмена) — **запись +об этом делается в проекте самого ресурса, в его документации**, в подходящем файле. + +У себя (в сервисе-потребителе) — только рабочий обход и короткая пометка со ссылкой на +запись в ресурсе: почему код написан неочевидно, когда обход можно снять. + +## Что указать в записи + +- **Источник** — где нашлось: сервис-потребитель, файл/экран/класс, а также версия или + коммит ресурса, на котором воспроизводится. +- **Автор находки** — кто нашёл: человек или ИИ-агент. +- **Автор задачи** — по чьей постановке шла работа, при которой нашлось (владелец, + задача в трекере): по этому следу восстанавливается контекст обнаружения. +- **Дата** записи. +- **Суть** — симптом и ожидаемое поведение; для бага — шаги воспроизведения. +- **Доказательства** — замеры, скриншоты, вывод команд: без них находку невозможно + ни подтвердить, ни закрыть. +- **Предложение по исправлению** — если есть; оно может быть отклонено, но должно быть + видно автору ресурса. +- **Ссылка на задачу в трекере ресурса** — если она заведена (например, запись в проекте + ресурса в gntodo); задача и запись ссылаются друг на друга. + +## Куда именно + +- Есть подходящий раздел (подводные камни, known issues, ограничения, changelog) — запись + идёт туда. +- Нет — заводится отдельный документ в доке ресурса, на который ссылается его README. +- Исправление уже сделано — запись превращается в строку changelog/релиза, а не удаляется: + потребители должны узнать, что обход можно снять. + +## Пример + +``` +## Иконка .ph.normalize уезжает под базовую линию во флекс-строке +Источник: gntodo, подвал карточки проекта; ui-kit 1.0.0 (коммит e28f382). +Автор находки: ИИ-агент (сессия разработки gntodo). Автор задачи: владелец, веха 0.83. +Дата: 2026-10-10. Задача: GNtodo #241. +Суть: `.ph.normalize{position:relative;top:.15em}` верен для инлайновой строки, но в +флекс-строке (`align-items:center`) опускает глиф на 0.135em ≈ 1.6px ниже базовой линии. +Замер (чернила в скриншоте): с поправкой центр глифа на 1.3px ниже центра цифры, без — 0.2px выше. +Предложение: `vertical-align: -0.15em` вместо `position:relative; top` (на флекс-элемент +`vertical-align` не действует вовсе) либо отдельный класс без поправки. +``` + +## Ссылки + +- [ui.md](ui.md) — UI-ресурс (gnexus-ui-kit) и его дока +- [git.md](git.md) — репозитории проектов и правила коммитов +- [../30-operations/docs.md](../30-operations/docs.md) — что документируется в gnexus-book diff --git a/README.md b/README.md index dcfe052..51aaaa5 100644 --- a/README.md +++ b/README.md @@ -19,6 +19,8 @@ - Разделы написаны по-разному: конвенции (`10-platform/`, `30-operations/`) формулируют правила; справочники (`20-deployment/`) информируют о том, как здесь что устроено, — без предписаний. - Если правило противоречит задаче владельца — владелец прав, но предложи обновить handbook. +- Нашёл нюанс, баг или недоработку в общем ресурсе — фиксируй в проекте самого ресурса, + а не только у себя: [10-platform/feedback.md](10-platform/feedback.md). - Не копируй правила в другие репозитории и промпты — ссылайся сюда. ### Сервисам и документации @@ -36,6 +38,7 @@ - [i18n.md](10-platform/i18n.md) — мультиязычность интерфейса - [mcp.md](10-platform/mcp.md) — MCP и API-токены для ИИ-агентов - [ui.md](10-platform/ui.md) — UI и визуальный стиль + - [feedback.md](10-platform/feedback.md) — обратная связь в общие ресурсы: находки и предложения по ui-kit, SDK, контрактам - [health.md](10-platform/health.md) — health-эндпоинт сервисов - [notifications.md](10-platform/notifications.md) — уведомления через Gnexus Synapse: конвенция интеграции (источник с `syn_*`, конверт v1, webhook-цель) - [secrets.md](10-platform/secrets.md) — секреты