Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
65 lines (49 loc) · 4.26 KB

CONTRIBUTING.md

File metadata and controls

65 lines (49 loc) · 4.26 KB
Raw

Внесок у OmniGlyph

Дякуємо за ваш інтерес! У цьому проєкті є два неперехідних культурних правила — саме вони є причиною того, що кожній цифрі в README можна довіряти.

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

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

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

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

Правило 2 — Вимірювання перед твердженнями

Жодна зміна геометрії, атласу, формули тарифікації чи охоплення моделей не потрапляє в кодову базу без виміряної цифри. Репозиторій побудований навколо цієї дисципліни:

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

Гіпотези без цифр ідуть у docs/ROADMAP.md як гіпотези — ніколи в README як факти. Дві "очевидні" ідеї вже спростовані даними (сторінка високої роздільності, атлас зі згладжуванням); процес працює.

Налаштування

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

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

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