Перейти к содержанию

Вход для ИИ: сопровождение документации

Перед правками прочитайте эту страницу, архитектуру, историю и затрагиваемый код. Корневой AGENTS.md направляет сюда.

Источник истины

  1. Проверьте git status, ветку/HEAD, version.txt, bgNPC.VERSION в sh_init.lua. Сохраняйте посторонние изменения.
  2. Просмотрите теги/коммиты до запрошенной версии и последующие изменения рабочей ветки. Отделяйте релиз от доработок после тега; не выдавайте dev-поведение за опубликованное в Workshop.
  3. Контракты определяют код и порядок загрузки. Планы, старые комментарии, MODLOG и прежняя документация требуют проверки по реализации.
  4. Проверяйте определение функции, всех вызывающих, realm-ветви, сетевые обработчики, наличие необязательных зависимостей. Префикса sh_ недостаточно для определения поддерживаемой области вызова.

Что обновлять вместе

Изменение Затрагиваемая документация
Сигнатура / результат / алиас Справочник области, страница метода, примеры/уроки; старые URL сохранять.
Поведение / значение по умолчанию / команда Страница системы, настройки/конфиг, при необходимости решение проблем, история.
Структура / загрузка / поток событий Архитектура и эта карта сопровождения.
Новая страница EN/RU, навигация mkdocs.yml, русский пункт, входящие ссылки.
Граница релиза База истории, версия/коммит архитектуры, README и входные страницы.

Точки входа API: reference/server.md, client.md, shared.md. Указывайте владельца состояния и ограничения клиентского снимка. Описывайте nil/NULL, значения аргументов, проверки, побочные эффекты, отмену хуками и смену сущности. Современный API ставьте первым, реальные алиасы помечайте устаревшими; не придумывайте замену отсутствующей функции.

Правила оформления

  • Английский — .md, русский — .ru.md; смысл синхронизировать. Сигнатуры/пути оставлять буквальными.
  • Внутренние ссылки ведут на .md даже в RU: язык выбирает i18n. Сохраняйте имена файлов/URL; вместо устаревшего текста пишите пояснение о миграции.
  • Систему описывать один раз, из остальных мест ссылаться. Настройки — у владельца системы, устройство кода — в архитектуре, исторические отличия — в истории.
  • Предпочитайте небольшие таблицы, минимальные исполнимые примеры и точные контракты. Для задачи документации не добавляйте зависимости и игровой код.
  • Не включайте секреты, приватные машинные пути, временный мост как требование установки, недоказанные заявления о производительности.
  • Не редактируйте генерируемый site/. Игнорируемые планы не являются поставляемыми инструкциями.

Проверки и завершение

При необходимости установите существующий requirements-docs.txt, выполните python -m mkdocs build --strict. Проверьте ссылки, якоря, EN/RU-навигацию, пути и сигнатуры по коду. Просмотрите git diff --check и весь diff. Документационные правки не требуют запуска GMod/физических фикстур; явно укажите, что не проверялось.

Меняйте базовую версию после изучения охваченных изменений. Если пользователь запросил коммит, включайте только нужную документацию/конфигурацию. Push и публикация — отдельное действие; существующий workflow публикует master, а не любой локальный коммит.