Вход для ИИ: сопровождение документации¶
Перед правками прочитайте эту страницу, архитектуру, историю и затрагиваемый код. Корневой AGENTS.md направляет сюда.
Источник истины¶
- Проверьте
git status, ветку/HEAD,version.txt,bgNPC.VERSIONвsh_init.lua. Сохраняйте посторонние изменения. - Просмотрите теги/коммиты до запрошенной версии и последующие изменения рабочей ветки. Отделяйте релиз от доработок после тега; не выдавайте dev-поведение за опубликованное в Workshop.
- Контракты определяют код и порядок загрузки. Планы, старые комментарии, MODLOG и прежняя документация требуют проверки по реализации.
- Проверяйте определение функции, всех вызывающих, 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, а не любой локальный коммит.