Как связаны Git-репозиторий, технические Markdown-файлы, эта Wiki и журнал изменений production.

Правила #

1. Исходный код и технические .md-файлы живут в Git (git@github.com:advertech/signage-estimator.git, рабочая копия на сервере — /root/signage-estimator). Git — источник истины.
2. WordPress Wiki — удобный слой для чтения и поиска поверх Git. Она объясняет, как работает система, и ссылается на код и файлы.
3. Значимые технические Markdown-файлы могут публиковаться/синхронизироваться в Wiki. Импортированные статьи содержат блок метаданных (исходный файл, репозиторий, SHA коммита, время импорта) и находятся в разделе «Исходные файлы», а также в тематических разделах.
4. Журнал изменений production пишется только после деплоя в production — никогда не на каждый коммит.
5. Каждая запись журнала содержит SHA коммита, развёрнутого в production.
6. Один production-релиз может включать много коммитов. Между двумя записями журнала в Git может быть сколько угодно коммитов.
7. Старые статьи нельзя молча перезаписывать неверной информацией. Если документ устарел, ставим статус «Устарело» (Deprecated) или «Историческое» (Historical), либо перепроверяем его и обновляем дату «Последняя проверка».

Языки #

• Основной язык Wiki — русский (адреса без префикса). Второй язык — английский (адреса с префиксом /en/); переключатель языка — в правом верхнем углу.
• Большинство Markdown-файлов в Git написаны по-английски. Их русские переводы хранятся в /root/wiki-sign-expert/translations/ru/, английский перевод русскоязычных файлов — в translations/en/.
• Первая строка файла перевода фиксирует, с какой версии оригинала он сделан: <!-- translation-of: <путь> @ <git blob sha> -->. Если файл в Git потом изменился, импорт всё равно публикует статью, но помечает её «⚠ Перевод может быть устаревшим» — пока перевод не обновят.
• Технические идентификаторы (имена классов, полей, эндпоинтов, команды) и названия элементов интерфейса приложения не переводятся.

Импорт Markdown из Git #

Односторонняя синхронизация Git → Wiki, запускается от root на production-сервере:

/root/wiki-sign-expert/import_git_docs.py --dry-run          # предпросмотр
/root/wiki-sign-expert/import_git_docs.py                    # импорт из HEAD /root/signage-estimator
/root/wiki-sign-expert/import_git_docs.py --commit <sha>     # импорт точного развёрнутого коммита

• Содержимое читается из закоммиченного blob (git show <sha>:<путь>), а не из незакоммиченных правок рабочей копии. Репозиторий никогда не изменяется.
• Статьи сопоставляются по пути исходного файла и языку, поэтому повторный запуск обновляет ту же статью, а не создаёт дубликат.
• Список импортируемых файлов, их названия и разделы Wiki — словарь DOCS в скрипте. Чтобы опубликовать новый файл, добавьте его туда и положите перевод в translations/.
• Не редактируйте импортированные статьи в WordPress — следующий импорт перезапишет правки. Меняйте Markdown в Git (или файл перевода). Собственные статьи Wiki (как эта) редактируются в WordPress.
• Файлы с чувствительной информацией о безопасности и инфраструктуре (deploy/DEPLOYMENT.md, SECURITY.md, SECURITY_RECONCILIATION.md) импортируются как закрытые: их видят только вошедшие редакторы.

Порядок релиза #

1. Разработка и коммиты в Git (сколько угодно коммитов).
2. Деплой в production по «Регламенту развёртывания».
3. Зафиксируйте развёрнутый SHA: git -C /root/signage-estimator rev-parse HEAD.
4. Переимпортируйте документацию на этом SHA: import_git_docs.py --commit <sha>; обновите переводы, помеченные как устаревшие.
5. Добавьте одну запись в «Журнал изменений production» для этого релиза (см. «Как написать запись журнала изменений production») со ссылками на затронутые статьи Wiki.