test/.template/development/docs/adr/0008-vscode-onboarding.md

ADR-0008: Версионируемая рабочая область VS Code и обучение автора

Дата: 2026-08-31
Статус: Принято

Контекст

Основные пользователи шаблона пишут документы, но могут никогда не работать с кодом, Git и Typst. Устные инструкции и личные настройки редактора не воспроизводятся в новом форке. Одновременно каталог .vscode/ не должен отвлекать автора от текста.

Часть расширений доступна в публичном Marketplace, а Typst Typewriter и Zotst распространяются внутри компании как локальные VSIX. Запись идентификатора расширения в рекомендациях VS Code не распространяет сам установочный пакет.

Рассматриваемые варианты

1. Не хранить настройки редактора — корень формально проще, но каждый сотрудник вручную повторяет настройку и получает различное поведение.
2. Настроить всё глобально на рабочих станциях — удобно на одном компьютере, но не переносится вместе с форком и требует администрирования.
3. Версионировать .vscode/ и скрыть его в проводнике — настройки синхронизируются через Git, оставаясь вне повседневной области автора.
4. Положить локальные VSIX в шаблон — обеспечивает автономную установку, но смешивает бинарные пакеты с исходниками и затрудняет централизованное обновление.

Решение

Выбран вариант версионировать .vscode/, но скрывать его из Explorer:

• extensions.json содержит десять согласованных идентификаторов, включая два внутренних;
• settings.json включает автосохранение, языки проверки орфографии, TODO-маркеры и защитные настройки Git;
• tasks.json предоставляет обычную и приватную сборку, выбор одного из четырёх публичных примеров и компиляцию учебного каталога;
• внутренние VSIX хранятся в корпоративном хранилище, а README объясняет их установку;
• README и видимый docs/ обучают Git в терминах истории документа, контрольных точек и параллельных версий.

Последствия

Становится проще: первый запуск, одинаковая среда во всех форках, живой предпросмотр, проверка русского текста и совместная работа через Git.

Становится сложнее: изменения .vscode/ требуют такого же review, как изменения шаблона; сопровождающий должен отдельно публиковать совместимые VSIX.

Закрывает дверь на: неявные обязательные глобальные настройки и распространение внутренних бинарных расширений внутри Git-шаблона.