Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
69 lines (53 loc) · 4.34 KB

CONTRIBUTING.md

File metadata and controls

69 lines (53 loc) · 4.34 KB
Raw

Как внести вклад в OmniGlyph

Спасибо за интерес! У этого проекта есть два не подлежащих обсуждению культурных правила — именно благодаря им каждой цифре в README можно доверять.

Правило 1 — Строгий TDD

Весь продакшн-код рождается из теста, который сначала упал:

  1. Напишите тест и убедитесь, что он падает по правильной причине.
  2. Напишите минимум кода, чтобы он прошёл.
  3. Рефакторите, оставаясь зелёным.

Полная планка: pnpm run typecheck && pnpm test && pnpm run build — все три команды, всегда (линтинг ссылок в документации и rebrand-гвард запускаются внутри pnpm test через tests/docs-integrity.test.ts).

Правило 2 — Измерение прежде утверждений

Ни одно изменение геометрии, атласа, формулы биллинга или охвата моделей не попадает в код без измеренной цифры. Репозиторий построен вокруг этой дисциплины:

  • Стоимость биллинга → докажите её через benchmarks/billing-sweep/ (count_tokens бесплатен; ожидаемая невязка: ноль).
  • Читаемость → докажите её через benchmarks/density-frontier/ (n≥30 на плечо, детерминированная оценка, JSONL-подтверждения зафиксированы в benchmarks/*/results/).
  • Планка приёмки для изменения продакшн-значения по умолчанию: суть == текстовому базовому уровню И ноль незаметных ошибок точных строк И положительная экономия.

Гипотезы без цифр идут в docs/ROADMAP.md как гипотезы — никогда в README как факты. Две «очевидные» идеи уже были опровергнуты данными (страница высокого разрешения, сглаженный атлас); процесс работает.

Настройка

pnpm install
pnpm test              # полный набор тестов, ~40–90с
pnpm run dev:node      # локальный прокси в режиме наблюдения

Node ≥18 (CI тестирует 20/22/24), pnpm 10 (зафиксирован через packageManager в package.json).

Структура

папка правило
src/core/ не зависит от среды выполнения (только Web API — работает на Node и Workers)
src/node.ts / src/worker.ts только обвязка хоста
benchmarks/ перезапускаемые наборы; JSONL-результаты — это подтверждения, зафиксированы в репозитории
docs/ benchmarks/ (цифры), architecture/ (карта), ROADMAP (гипотезы), ops/ (OmniRoute)

Коммиты и PR

  • Conventional commits (feat:, fix:, perf:, docs:, refactor:, test:, chore:), тело коммита объясняет почему, с релевантными цифрами.
  • Небольшие, сфокусированные PR; изменения поведения сопровождаются тестом, который их фиксирует, и, если применимо, бенчмарком, который их обосновывает.
  • Не переписывайте клиентские блоки cache_control, не добавляйте зависимости времени выполнения без обсуждения (ядро намеренно малозависимо), не используйте Math.random/временные метки в путях рендеринга (детерминизм — жёсткий инвариант, проверяется побайтовой идентичностью).