464fa6ec83
* feat(readme): new bilingual standard v2 with features table * docs(handoff): rename handoff and ADR to PR number convention * docs(review): fix ADR-051 section name and add PR#116 refs --------- Co-authored-by: opencode-agent <agent@opencode.local>
47 lines
3.5 KiB
Markdown
47 lines
3.5 KiB
Markdown
# ADR-051: README standard v2 — Why/What + Features table
|
||
|
||
## Статус
|
||
Accepted (2026-07-29)
|
||
|
||
## Контекст
|
||
|
||
Витрина slaid098.dev парсит `README.md` из каждого репозитория: извлекает
|
||
фрагменты между разделителями. В стандарте v1 (ADR-049, PR#112) были 2 пары
|
||
разделителей (`summary-en/ru`) с Problem/Solution текстом и опциональный
|
||
`tier` (flagship/utility), влияющий только на блок `demo_gif`. Problem/Solution
|
||
оказался не универсален — не каждый проект укладывается в "проблема → решение"
|
||
(например, конфиг-репозитории, утилиты). Tier system усложнял поддержку: два
|
||
пути генерации, флаг demo_gif, разные описания параметров. Витрине нужна
|
||
таблица фич для каждой карточки — в v1 её не было.
|
||
|
||
## Решение
|
||
|
||
Перейти на стандарт v2:
|
||
|
||
- **Why/What** вместо Problem/Solution — универсальная структура: зачем
|
||
существует проект и что делает. Применима к любому репо.
|
||
- **Features table** — обязательная часть README. Каждая фича: `{ emoji, name,
|
||
description }`. Рендерится в markdown-таблицу между новыми разделителями
|
||
`<!-- features-en:start/end -->` и `<!-- features-ru:start/end -->`.
|
||
- **4 пары разделителей** (summary-en, features-en, summary-ru, features-ru) —
|
||
витрина парсит и summary, и features независимо.
|
||
- **Tier system убран** — один формат для всех репо, без условной логики.
|
||
- **`custom_sections_en/ru` вне delimiter tags** — после `features-en:end`,
|
||
до Quick Start. Раньше были внутри summary delimiter.
|
||
- **`demo_gif` убран** — не использовался витриной.
|
||
- `validate` проверяет наличие и непустоту всех 4 пар разделителей.
|
||
|
||
## Альтернативы
|
||
|
||
- **Сохранить Problem/Solution** — отвергнуто: не универсально. Не каждый
|
||
проект укладывается в "проблема → решение" (конфиг-репозитории, утилиты).
|
||
Why/What применимо к любому репо.
|
||
- **Сохранить tier system (flagship/utility)** — отвергнуто: усложнял поддержку
|
||
(два пути генерации, флаг demo_gif, разные описания параметров). Один формат
|
||
для всех репо проще в поддержке.
|
||
- **Оставить 2 пары разделителей (summary только)** — отвергнуто: витрина не
|
||
может парсить features независимо от summary. 4 пары позволяют извлекать и
|
||
summary, и таблицу фич как независимые блоки per language.
|
||
- **Держать custom_sections внутри summary delimiter** — отвергнуто: перенос
|
||
вне delimiter tags (после features-en:end, до Quick Start) разделяет
|
||
пользовательский контент и парсимый витриной.
|