36 lines
2.9 KiB
Markdown
36 lines
2.9 KiB
Markdown
# ADR-0009: Один main.typ, видимая документация и явная приватная сборка
|
||
|
||
**Дата**: 2026-08-31
|
||
**Статус**: Принято
|
||
|
||
> Часть решения об отдельной private build task заменена условным import из [ADR-0010](0010-private-folder-and-employees.md). Один `main.typ` и видимая публичная документация остаются действующими.
|
||
|
||
## Контекст
|
||
|
||
Проверка шаблона на реальных отчётах показала, что авторы ожидают менять компанию, стадию, режим и список глав в одном файле. Три корневых entrypoint-файла и скрытая пользовательская справка создавали лишний выбор. Одновременно Typst 0.15 не умеет безопасно проверять существование private path.
|
||
|
||
## Рассматриваемые варианты
|
||
|
||
1. **Сохранить `document.typ` и три entrypoints** — технически чисто, но пользователь должен понимать разделение ролей четырёх файлов.
|
||
2. **Один `main.typ` и tracked private placeholders с заменой** — просто, но реальная подпись становится изменением уже отслеживаемого файла.
|
||
3. **Один `main.typ`, public `docs/`, internal placeholders и private task** — минимальная поверхность без риска добавить реальный media в Git.
|
||
|
||
## Решение
|
||
|
||
Выбран третий вариант:
|
||
|
||
- `main.typ` содержит `company-id`, `document-mode`, metadata и `#include`;
|
||
- `docs/` видим и содержит executable examples;
|
||
- examples одновременно являются источниками задачи выбора типа;
|
||
- обычная сборка использует internal placeholders;
|
||
- задача приватной сборки проверяет `private-assets.zip`, копирует PNG в `.private/` и передаёт `--input private-assets=true`;
|
||
- прежний ADR-0007 считается устаревшим.
|
||
|
||
## Последствия
|
||
|
||
**Становится проще**: первый запуск, переключение режима, поиск примеров, выбор типа и выпуск с приватными изображениями.
|
||
|
||
**Становится сложнее**: main-файлы четырёх примеров частично повторяют setup-код; PowerShell tool становится security boundary для ZIP.
|
||
|
||
**Закрывает дверь на**: отдельные root entrypoints для режимов, скрытую public-документацию и замену tracked placeholders реальными файлами.
|