feat(readme): new bilingual standard v2 with features table (#116 )

* 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>

2026-07-29 03:22:28 +03:00

3.5 KiB

Raw Blame History

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-таблицу между новыми разделителями  и .
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) разделяет пользовательский контент и парсимый витриной.

3.5 KiB Raw Blame History Unescape Escape