4.2 KiB
Как поддерживать документацию
При каждом изменении
- Определите затронутые компоненты по карте архитектуры и прочитайте их локальные
AGENTS.md. - Если меняются наблюдаемое поведение, операция API, формат данных, конфигурация или способ запуска, обновите профильную документацию в том же наборе изменений. Для DM проверьте также документы о доставке, технических вставках и файлах; для Solana — формат PDA и инструкции инициализации.
- Если изменился состав компонентов или поток данных, обновите
ARCHITECTURE.md; если появился новый раздел, обновите этот каталог. Публичный README меняйте при изменении возможностей, статуса или способа запуска. - Запустите
python3 scripts/check_docs.pyиз корня репозитория: он проверяет локальные ссылки в документах и соответствие индекса зарегистрированным WS-операциям. Затем проверьте точность команд/путей вручную. Сравните утверждения с конкретными файлами кода или конфигурации. Непроверенное обозначьте как «требует сверки», планы — как «планируется». - В описании изменения укажите, какие документы обновлены и что проверено. Если документацию менять не требуется, кратко объясните почему.
Особые связки: изменение формата блоков требует обновления профильного файла в Blockchain/ и Blockchain/CHANGELOG.md; изменение серверных операций — профильного файла в API/ и индекса операций; изменение синхронизации Solana users — Solana/SOLANA_USERS_SYNC_MODULE_DESIGN.md и ../deploy/SOLANA_USERS_SYNC_SERVER_SETUP.md; изменение экранов ESP32 — спецификации устройства и скетча. В журнале блокчейна не требуйте хэш ещё не созданного коммита: фиксируйте дату и суть изменения, а ссылку на коммит добавляйте после его появления, если она нужна.
Источники и статусы
- Реализовано — подтверждено кодом; укажите модуль и, если полезно, проверенный сценарий.
- Тестовый контур — работает только с тестовыми значениями, ключами или namespace; не обещайте production-поведение.
- Планируется — проектное решение, ещё не являющееся контрактом.
- История/архив — полезно для контекста, но не для новых интеграций.
Когда документы противоречат друг другу, сначала проверяйте код и тесты, затем правьте обе стороны противоречия. Точные форматы держите в профильной спецификации; обзорные файлы должны ссылаться на неё, а не копировать таблицы байтов или адреса. Для решений, меняющих протокол или требующих согласия на деплой, действуют ограничения из корневого и локальных AGENTS.md.