Правила для внешних контрибьюторов

На странице описано, что нужно сделать, чтобы ваши изменения приняли в проект Diplodoc.

Требования к коду

Код-стайл и линтинг

Пишите код в едином стиле. Для проверки используйте пакет @diplodoc/lint:

• ESLint — проверка JavaScript/TypeScript кода.
• Prettier — форматирование кода.
• Stylelint — проверка CSS/SCSS.

Перед отправкой пул-реквеста выполните:

npm run lint

Для автоматического исправления ошибок:

npm run lint:fix

TypeScript

• Пишите весь исходный код на TypeScript.
• Расширяйте общую конфигурацию @diplodoc/tsconfig.
• Проверяйте типы командой npm run typecheck.

Документирование архитектурных изменений (ADR)

Если ваши изменения затрагивают архитектуру проекта, создайте ADR-файл в формате Markdown в соответствующей папке репозитория. В файле укажите:

• контекст проблемы;
• рассмотренные варианты решения;
• принятое решение и его обоснование.

Тестирование

Покрывайте изменения тестами — это обязательное условие для принятия пул-реквеста.

Тест-раннер

В проекте используется Vitest. Другие тест-раннеры, например, Jest не поддерживаются.

npm run test        # Запуск тестов
npm run test:watch  # Запуск в watch-режиме

Структура тестов

• Unit-тесты — размещайте рядом с тестируемым кодом:

  • src/**/*.test.ts
  • src/**/*.spec.ts
  • src/**/__tests__/

• Интеграционные тесты — в директории test/ (не tests/):

  • test/**/*.test.ts

Конфигурация

Создайте файл vitest.config.mjs в корне пакета:

import {defineConfig} from 'vitest/config';

export default defineConfig({
    test: {
        include: ['src/**/*.test.ts', 'test/**/*.test.ts'],
        exclude: ['node_modules', 'build'],
    },
});

Требования к пул-реквестам

Описание изменений

Добавьте в пул-реквест:

• Описание проблемы — что исправляете или добавляете.
• Описание решения — как решили проблему.
• Ссылки — на связанные issues или документацию.

Оформление коммитов

Подробные требования к оформлению коммитов смотрите в разделе Внесение изменений в проект.

Требования к Extensions

Использование шаблона

При создании нового расширения используйте официальный шаблон из репозитория package-template.

Учёт многопоточности

Сборка документации может выполняться в многопоточном режиме. Убедитесь, что ваше расширение:

• не использует глобальное состояние;
• корректно работает при параллельном выполнении;
• не создает race conditions.

Инфраструктура модулей

@diplodoc/lint

Используйте @diplodoc/lint для единой инфраструктуры линтинга:

# Инициализация нового пакета
npx @diplodoc/lint init

# Обновление существующего пакета
npx @diplodoc/lint update

Скрипты в package.json

Определите в package.json следующие скрипты:

Режим watch

Команда npm run watch запускает среду разработки: собирает пакеты, следит за изменениями и автоматически перезапускает сборку. Это позволяет сразу видеть результат изменений без ручного запуска команд сборки.

Подробнее на GitHub

Файлы модуля

Добавьте в каждый модуль:

• SECURITY.md — политика безопасности
• CONTRIBUTING.md — руководство для контрибьюторов
• LICENSE — лицензия проекта
• vitest.config.mjs — конфигурация Vitest
• .github/workflows/ — CI/CD workflows

GitHub Workflows

Каждый пакет должен содержать стандартные workflows в директории .github/workflows/.

Обязательные workflows:

• tests.yml — основной workflow для тестирования (запускает lint, typecheck, tests)
• release.yml — workflow для релиза
• release-please.yml — конфигурация release-please
• package-lock.yml — обновление package lock
• security.yml — сканирование безопасности
• update-deps.yml — обновление зависимостей

Специальные workflows (сохраняйте при необходимости):

• E2E-специфичные workflows (например, diplodoc-e2e-tests.yaml)
• Кастомные workflows для специфичных нужд пакета

Workflows для удаления (дубликаты):

• tests.yaml (дубликат tests.yml)

При настройке workflows:

1. Проверьте существующие workflows в .github/workflows/.
2. Удалите дублирующиеся workflows (.yaml vs .yml).
3. Убедитесь, что присутствуют все стандартные workflows.
4. Сохраните специальные workflows, если они выполняют специфичную функцию.
5. Проверьте корректность конфигурации workflows.

Подробнее в документации

Неподдерживаемые инструменты

Инструменты и пакеты, которые не поддерживаются в проекте. Используйте рекомендуемые альтернативы.

Сборка

• Webpack → используйте esbuild
• tsc для сборки JS → используйте esbuild, tsc только для деклараций

Устаревшие пакеты

• @diplodoc/eslint-config → используйте @diplodoc/lint
• @diplodoc/prettier-config → используйте @diplodoc/lint

Чеклист перед отправкой PR

Перед отправкой пул-реквеста проверьте:

• Код соответствует стилю проекта (npm run lint проходит без ошибок).
• Типы проверены (npm run typecheck проходит без ошибок).
• Тесты написаны и проходят (npm run test проходит без ошибок).
• Сборка работает (npm run build проходит без ошибок).
• Пул-реквест содержит описание изменений.
• Для архитектурных изменений создан ADR.
• Для визуальных изменений добавлены скриншоты.
• Коммиты оформлены согласно conventional commits.
• Используются только поддерживаемые инструменты (Vitest, esbuild).

Дополнительные ресурсы

• Требования к участию в метапакете
• Управление метапакетами
• Инфраструктура разработки