Files
SHiNE-server/docs/CONTRIBUTING_DOCS.md
T

4.2 KiB

Как поддерживать документацию

При каждом изменении

  1. Определите затронутые компоненты по карте архитектуры и прочитайте их локальные AGENTS.md.
  2. Если меняются наблюдаемое поведение, операция API, формат данных, конфигурация или способ запуска, обновите профильную документацию в том же наборе изменений. Для DM проверьте также документы о доставке, технических вставках и файлах; для Solana — формат PDA и инструкции инициализации.
  3. Если изменился состав компонентов или поток данных, обновите ARCHITECTURE.md; если появился новый раздел, обновите этот каталог. Публичный README меняйте при изменении возможностей, статуса или способа запуска.
  4. Запустите python3 scripts/check_docs.py из корня репозитория: он проверяет локальные ссылки в документах и соответствие индекса зарегистрированным WS-операциям. Затем проверьте точность команд/путей вручную. Сравните утверждения с конкретными файлами кода или конфигурации. Непроверенное обозначьте как «требует сверки», планы — как «планируется».
  5. В описании изменения укажите, какие документы обновлены и что проверено. Если документацию менять не требуется, кратко объясните почему.

Особые связки: изменение формата блоков требует обновления профильного файла в 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.