Contributing ru

Участие в разработке

English | 中文 | 日本語 | 한국어 | Español | Português | Русский

Команды

npm test                        # full test suite (Node built-in runner, no build needed)
node --test test/foo.test.mjs   # single file
npm run package                 # build the versioned zip (browsa-vX.Y.Z.zip)
npm run build                   # esbuild vendor bundle (only needed after build.mjs changes)
bash check-compat.sh            # static compatibility check

Ограничение машины на 4GB: сьют — 103 файла (~36 jsdom-тяжёлых) на VPS 2CPU/4GB; скрипт ограничивает конкурентность двойкой, на 4GB предпочитайте --test-concurrency=1. Никогда не выделяйте в тестах блобы в десятки MB (один мок на 44MB однажды уронил машину в OOM — реальный рецидив); предпочитайте pure-function тесты (без DOM, без больших буферов).

Философия тестирования

• Тесты мокают глобальный chrome до импорта реальных модулей; jsdom-тесты используют РЕАЛЬНЫЕ вендорские бандлы marked/DOMPurify/katex/highlight.js, а не подставки.
• sidepanel.js не имеет ни одного экспорта — его тесты грузят весь sidepanel.html в jsdom и ведут его как чёрный ящик (симулированные клики/клавиши/сообщения портов).
• Worker-клиенты держат модульные синглтоны → сценарии, требующие свежего синглтона, ОБЯЗАНЫ быть отдельными ФАЙЛАМИ тестов (раннер изолирует по файлу/процессу).
• Дисциплина lockstep: факты, отражённые в нескольких местах (regex-ы, имена полей, пары CSS/hint, порядок табов), либо схлопываются в один источник, либо закрепляются source-regex с пометкой в AGENTS.md «менять оба в lockstep». Пример: subchat.test.mjs regex-локает точную строку исходника pushSubChatChunk(… SUBCHAT_DONE …).
• Тесты detail-thread / стриминга ОБЯЗАНЫ завершать ход (DONE / ■ / закрытие), иначе 20-секундный интервал SW_PING порта хода утекает и вешает раннер.
• WASM — исключение из «никакого реального исполнения»: WebAssembly.instantiate работает в Node, поэтому тесты pdf-inspector исполняют настоящий вендорский бинарник.

Принципы рефакторинга (оплачены инцидентами; из AGENTS.md)

• N кейсов switch, различающихся только литералами → одна таблица просмотра; две рукописные реализации одного сетевого протокола → одна общая функция с хуками (дрейф DONE-обработчика был реальным семейством багов).
• После каждого извлечения запускайте ПОЛНЫЙ сьют И check-compat.sh — синтаксическая проверка ничего не доказывает.
• Грепайте весь репозиторий (включая test/), прежде чем объявить экспорт мёртвым; тест-онли экспорт не умирает автоматически — читайте окружающие комментарии.

dev-preview (превью UI расширения в headless-окружении)

node dev-preview/gen.mjs        # regenerate preview pages from real sidepanel.html (rerun after HTML changes)
python3 -m http.server 8931     # from the repo root
# http://127.0.0.1:8931/dev-preview/sidepanel.preview.html

Chrome-shim даёт минимальную поверхность chrome.*; seed.js инжектит богатую историю. Скриншоты идут через CDP Page.captureScreenshot (просто, без clip/scale; page.screenshot() имеет артефакты тёмной темы). Зелёное превью ≠ зелёное реальное расширение: sendMessage-конверты шима обязаны зеркалить реальный контракт байт-в-байт, а верификация CSP-класса всегда требует реальной загрузки расширения.

Процесс релиза

1. Поднимите версию в ОБОИХ manifest.json и package.json.
2. PR → зелёный CI → squash-merge в main → обратная заливка dev: git reset --hard origin/main && git push --force-with-lease origin dev (merge-заливка загрязняет main..dev; кнопка Delete branch на странице PR удалила бы dev).
3. PR подъёма версии идут через переиспользуемые release-workflow (xiaohuzai/release-flow@v1) с отменёнными тестами (PAT-режим).
4. Тексты сторового листинга генерируются скиллом .agents/skills/cws-listing (тег — источник истины по версии); история отказов задокументирована.
5. Дисциплина docs-sync (любое видимое пользователю изменение, тот же PR): README на обоих языках (зеркала с выровненными секциями) → сайт документации (оба языка) → скриншоты/баннеры/demo GIF/промо-видео — каждое РАССМАТРИВАЕТСЯ (читаемость судится в собственном разрешении ассета; изменившийся GIF обязан сменить имя файла, чтобы победить кэши) → факты уровня архитектуры записываются в AGENTS.md.

Красные линии (краткий список)

Без автокоммита/упаковки (ждать явной инструкции) · без полного прогона тестов перед упаковкой (точечного зелёного достаточно) · использовать текущую версию, никогда не поднимать самостоятельно · приватный ключ расширения никогда не покидает /root/workspace/browsa-keys/ · пользовательские тексты без жаргона (zh не несёт английского жаргона) · сохранённые пиксели изображений никогда не уничтожаются · thinking по умолчанию omit.

---

Авторитетные версии: Contributing (англ.) / Contributing-zh (кит.) — снимок первичного перевода ИИ, синхронизирован 2026-10-01.