# Wishpad: documentation workflow

Документ фиксирует правила ведения документации Wishpad после начала реализации.

## Source Of Truth

Canonical documentation repository: `wishpad-docs`.

- `docs/SPEC.md` хранит продуктовые решения, MVP scope, технические решения верхнего уровня и будущие точки расширения.
- `docs/UI_SPEC.md` хранит пользовательские сценарии, экраны, responsive behavior, визуальные правила и UI-компоненты.
- `docs/DATABASE_SPEC.md` хранит структуру БД, таблицы, поля, типы, constraints, индексы, связи и порядок миграций.
- `docs/OPENAPI.yaml` хранит API-контракт и является source of truth для backend/frontend API-интеграции.
- `docs/MONETIZATION_SPEC.md` хранит future-монетизацию, `free`/`plus`, donation-модель и платные фичи.
- `docs/CHANGELOG.md` собирает изменения по релизам.

## Documentation Engine

- `wishpad-docs:main` публикуется через Gitea Actions runner `wishpad-docs`.
- Публичный сайт документации: `https://docs.wishpad.me` после выпуска TLS-сертификата; HTTP может использоваться во время DNS propagation.
- OpenAPI viewer: Scalar API Reference.
- Published OpenAPI contract: `/openapi.yaml`, source file: `docs/OPENAPI.yaml`.
- Будущая backend-страница `/api/docs` должна использовать тот же OpenAPI contract или ссылаться на `docs.wishpad.me`, чтобы не появилось две разные версии API-документации.

## Правило Обновления

- API-изменение сначала отражается в `docs/OPENAPI.yaml`, затем реализуется в backend/frontend.
- DB-изменение сначала отражается в `docs/DATABASE_SPEC.md`, затем реализуется миграцией.
- UI-решение сначала отражается в `docs/UI_SPEC.md`, затем реализуется во frontend.
- Изменение MVP scope или бизнес-правил сначала отражается в `docs/SPEC.md`.
- Изменение платных возможностей или donation-модели сначала отражается в `docs/MONETIZATION_SPEC.md`.

Если во время реализации обнаруживается, что текущее решение в документации неудобно или неверно:

1. Сначала обновить соответствующий документ.
2. Затем обновить связанные документы, если есть пересечения.
3. После этого менять код.

Если код уже был изменён раньше документации, документацию нужно синхронизировать в том же рабочем цикле, до завершения задачи.

## Changelog Workflow

- Заметные изменения собираются в `docs/CHANGELOG.md` в секции `Unreleased`.
- Перед релизом `Unreleased` переносится в раздел версии с датой релиза.
- Changelog ведётся как release notes, а не как список каждой мелкой правки.
- Обязательно отмечаются изменения API, БД, UI, deploy, security и breaking changes.
- Если релиз требует миграции, env-настройки или ручного действия на VPS, это должно быть явно указано.