Home Explore Help
Register Sign In
tkachenko
/
Building
0
0
Fork 0
Files Issues 0 Pull Requests 0 Wiki
Tree: 39708e98e7
Branches Tags
Building
/
.template
/
development
/
docs
/
adr
/
0008-vscode-onboarding.md

0008-vscode-onboarding.md 3.9 KB
History Raw

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-шаблона.