Процесс разработки

Назначение

Этот гайд описывает типовой рабочий процесс при разработке внутри монорепозитория Nrgy.js.

Структура репозитория

• packages/*: публикуемые пакеты.
• docs/*: проектная, пакетная и developer-документация.
• benchmarks/*: локальные benchmark-сценарии.

Основные команды

npm install

npm run format

npm run check

npm run test

npm run build

Ожидаемый процесс при изменении исходников

1. Обновите исходный файл и colocated-тесты.
2. Обновите colocated-документацию для измененного модуля.
3. Обновите пакетный README.md, если поменялся публичный API или способ использования.
4. Запустите npm run check.
5. Для поведенческих изменений запустите npm run test.

Процесс работы с документацией

• Документация модулей лежит рядом с исходными файлами.
• Пакетные обзоры живут в пакетных README.md.
• Русские переводы используют суффикс .ru.md.
• Файлы index.ts должны документироваться через пакетные README, а не через отдельные index.md.

Процесс работы с сайтом документации

• Источником правды для продуктовой документации и материалов для контрибьюторов является дерево docs/*, а не website/docs/content/*.
• Контент сайта в website/docs/content/* и website/docs/ru/content/* генерируется скриптом website/scripts/generate-content.mjs.
• При изменении документации сначала обновляйте исходные файлы в docs/* и держите синхронизированными соответствующие *.ru.md.

Команды для сайта

Запускайте команды из website/package.json:

cd website
npm run dev

cd website
npm run build

• dev заново генерирует website/docs/content/* и запускает локальный VitePress-сервер.
• build заново генерирует контент и проверяет, что сайт успешно собирается.

Когда нужно обновлять конфигурацию сайта

• Если меняется структура документации, обновляйте sidebar и navigation в website/docs/.vitepress/config.ts.
• Если документы перемещаются между разделами, проверяйте, что сгенерированные маршруты в website/docs/content/docs/* по-прежнему совпадают со ссылками в конфигурации.
• Если для сайта добавляются публичные ассеты, размещайте их в docs/assets/* или website/docs/public/* в зависимости от того, должны ли они копироваться генератором контента.

Файлы, важные для релизов

• Корневой CHANGELOG.md фиксирует изменения уровня проекта.
• Пакетные CHANGELOG.md фиксируют изменения конкретных пакетов.
• Названия пакетов и команды установки должны браться из актуальных package.json.

Релизный процесс

Релизный процесс запускается из корня репозитория через скрипты в package.json и правила версионирования в lerna.json.

Подготовка релиза

1. Убедитесь, что в рабочем дереве находятся только нужные изменения.
2. Запустите npm run check.
3. Запустите npm run test.
4. Запустите npm run build.
5. Проверьте, что документация и записи в changelog обновлены.

Версионирование

Сначала используйте dry run:

npm run preview:new-version

Создавайте версии только после проверки dry run:

npm run new-version

• preview:new-version запускает lerna version --dry-run.
• new-version запускает lerna version с включенными conventional commits.
• Перед версионированием хук preversion запускает npm run check, npm run build и npm run test, а затем добавляет все изменения через git add --all.

Публикация

После того как пакеты получили версии и релизный коммит готов, публикуйте уже пакеты с новыми версиями:

npm run new-publish

• new-publish запускает lerna publish from-package.
• Публикация пакетов опирается на версии, уже записанные в package manifest.

Релизные заметки и валидация

• После версионирования проверьте корневой CHANGELOG.md и пакетные CHANGELOG.md.
• Убедитесь, что сгенерированная документация и package README соответствуют публикуемому API.
• Если менялась документация сайта, перед публикацией соберите сайт через website/package.json.