Вклад

Вы можете внести свой вклад в экосистему Nuxt разными способами.

Экосистема

Экосистема Nuxt включает в себя множество различных проектов и организаций:

nuxt/ - основные репозитории для самого фреймворка Nuxt. nuxt/nuxt содержит фреймворк Nuxt (как версии 2, так и 3).
nuxt-modules/ - модули и библиотеки, созданные и поддерживаемые сообществом. Существует процесс миграции модуля в nuxt-modules. Хотя у этих модулей есть отдельные мейнтейнеры, они не зависят от одного человека.
unjs/ - многие из этих библиотек используются во всей экосистеме Nuxt. Они разработаны как универсальные библиотеки, не зависящие от фреймворка и окружения. Мы приветствуем их вклад и использование в других фреймворках и проектах.

Просмотрите проблемы и обсуждения проекта, которому вы хотите помочь. Например, вот доска проблем и обсуждения для Nuxt 3. Помощь другим пользователям, обмен обходными путями, воспроизведение проблемы кодом или даже небольшое исследование ошибки и обмен результатами - все это имеет огромное значение.

Создание issue

Спасибо, что нашли время создать проблему! ❤️

Отчеты об ошибках: Ознакомьтесь с нашим руководством, чтобы узнать, что нужно сделать, прежде чем открывать проблему.
Запросы на улучшение: Проверьте, нет ли уже существующей проблемы или обсуждения, охватывающего область применения задуманной вами функции. Если функция относится к другой части экосистемы Nuxt (например, к модулю), пожалуйста, подумайте о том, чтобы сначала отправить feature request туда. Если задуманная вами функция носит общий характер или API не совсем понятен, подумайте о том, чтобы сначала открыть обсуждение в разделе Ideas для обсуждения с сообществом.

Мы приложим все усилия, чтобы следовать нашей внутренней схеме принятия решений по вопросам при реагировании на вопросы.

Отправить Pull Request

Мы всегда рады предоставленным PR! ❤️

Прежде чем начать

Прежде, чем исправлять ошибку, мы рекомендуем вам проверить, есть ли уже проблема, в которой она описана. Возможно, что это проблема документации, или есть какой-то контекст, который было бы полезно знать.

Если вы работаете над новой фичой, то мы просим вас открыть сначала feature request, чтобы обсудить с мейнтенерами, желательна ли эта функция, и каков ее дизайн. Это помогает сэкономить время как ментейнеров, так и авторов, и означает, что функции могут быть отправлены быстрее. Проблема должна быть подтверждена членом команды фреймворка, прежде чем создавать функцию в запросе на вынос.

Для исправления опечаток рекомендуется объединять несколько исправлений в один PR, чтобы сохранить чистую историю коммитов.

Для больших изменений в самом Nuxt мы рекомендуем сначала создать модуль Nuxt и реализовать функцию в нем. Это позволит быстро проверить концепцию. Затем вы можете создать RFC в форме обсуждения. По мере того как пользователи примут его и вы соберете отзывы, его можно будет доработать и добавить в ядро Nuxt или продолжить поддерживать как отдельный модуль.

Конвенции о коммитах

Мы используем Conventional Commits для сообщений коммитов, который позволяет автоматически генерировать журнал изменений на основе коммитов. Пожалуйста, прочитайте руководство до конца, если вы с ним еще не знакомы.

Обратите внимание, что fix: и feat: предназначены для фактических изменений кода (которые могут повлиять на логику). Для опечаток или изменений в документах используйте docs: или chore::

~~fix: typo~~ -> docs: fix typo

Если вы работаете в проекте с монорепо, например nuxt/nuxt, убедитесь, что вы указали основную область применения вашего коммита в скобках. Например: feat(nuxi): add 'do-magic' command.

Создание Pull Request

Если вы не знаете, как отправлять pull request, рекомендуем прочитать руководство.

При отправке PR убедитесь, что название также соответствует Commit Convention.

Если ваш PR исправляет или решает существующие проблемы, пожалуйста, не забудьте упомянуть их в описании PR.

В одном PR может быть несколько коммитов; вам не нужно делать rebase или force push для ваших изменений, так как мы будем использовать Squash and Merge для слияния коммитов в один коммит при объединении.

Мы не добавляем никаких commit-хуков, чтобы обеспечить быстрые коммиты. Но перед тем, как сделать pull request, вы должны убедиться, что все lint/test-скрипты прошли.

В целом, пожалуйста, убедитесь, что в PR нет несвязанных изменений. Например, если ваш редактор изменил пробельные символы или форматирование в другом месте файла, который вы редактировали, пожалуйста, верните их, чтобы было более очевидно, что изменяет ваш PR. И, пожалуйста, избегайте включения нескольких несвязанных функций или исправлений в один PR. Если есть возможность разделить их, лучше иметь несколько PR, чтобы рассматривать и объединять их отдельно. В целом, PR должен делать только одну вещь.

Как только вы создали Pull Request

Как только создали PR, мы сделаем все возможное, чтобы рассмотреть его в кратчайшие сроки.

Если мы назначаем на него мейнтейнера, это означает, что этот человек будет уделять особое внимание его рассмотрению и внесению изменений, которые могут потребоваться.

Если мы просим внести изменения в PR, пожалуйста, не обращайте внимания на красный текст! Это не значит, что мы считаем PR плохим - это просто способ с первого взгляда определить статус списка запросов на исправление.

Если мы помечаем PR как "pending", это означает, что у нас, скорее всего, есть еще одна задача по рассмотрению PR. Это внутренняя заметка для самих себя, и она не обязательно отражает, хороша ли эта идея или нет. Мы постараемся объяснить в комментарии причину статуса "pending".

Мы приложим все усилия, чтобы следовать нашей схеме принятия решений по PR при ответе и рассмотрении PR.

Создание модуля

Если вы создали в Nuxt что-то классное, почему бы не извлечь это в модуль, чтобы им могли поделиться другие? У нас уже есть много отличных модулей, но всегда есть место для новых.

Если вам нужна помощь при создании модуля, не стесняйтесь обращаться к нам.

Создание RFC

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

Если вы уже сделали это, или создание нового модуля нецелесообразно, начните с создания нового обсуждения. Позаботьтесь о том, чтобы оно как можно яснее объясняло ваши мысли. Включите примеры кода или сигнатуры функций для новых API. Ссылайтесь на существующие проблемы или болевые точки с примерами.

Если мы сочтем, что это должно быть RFC, мы изменим категорию на RFC и распространим его более широко для получения отзывов.

Затем RFC проходит следующие стадии:

rfc: active - в настоящее время открыт для комментариев.
rfc: approved - одобрено командой Nuxt.
rfc: ready to implement - создано issue, назначена реализация.
rfc: shipped - реализовано.
rfc: archived - не одобрено, но заархивировано для будущего использования.

Конвенции по всей экосистеме

Следующие соглашения являются обязательными в организации nuxt/ и рекомендуются для других сопровождающих в экосистеме.

Конвенция модулей

Модули должны следовать шаблону шаблон Nuxt-модуля. Для получения дополнительной информации смотрите Руководство по модулям.

Использование основных библиотек `unjs/`

Мы рекомендуем следующие библиотеки, которые используются во всей экосистеме:

pathe - универсальные утилиты путей (замена для path от node)
ufo - утилиты для парсинга и объединения URL-адресов
unbuild - система сборки на основе rollup
... проверьте остальные части организации unjs/, чтобы найти много других библиотек!

Используйте синтаксис ESM и значение по умолчанию `type: module`

Большая часть экосистемы Nuxt может использовать ESM напрямую. В целом, мы рекомендуем вам избегать использования специфического для CJS кода, такого как __dirname и require операторы. Вы можете прочитать больше об ESM.

Что такое Corepack

Corepack позволяет убедиться, что вы используете правильную версию менеджера пакетов при выполнении соответствующих команд. Проекты могут иметь поле packageManager в их package.json.

В проектах с конфигурацией, как показано ниже, Corepack установит v7.5.0 pnpm (если у вас его еще нет) и будет использовать его для выполнения ваших команд.

package.json

{
  "packageManager": "pnpm@7.5.0"
}

Используйте ESLint

Мы используем ESLint как для линтинга, так и для форматирования с помощью @nuxt/eslint-config.

Настройка IDE

Мы рекомендуем использовать VS Code вместе с расширением ESLint. При желании вы можете включить авто-исправление и форматирование при сохранении редактируемого кода:

settings.json

{
  "editor.codeActionsOnSave": {
    "source.fixAll": "never",
    "source.fixAll.eslint": "explicit"
  }
}

Prettier'а нет

Поскольку ESLint уже настроен на форматирование кода, нет необходимости дублировать эту функциональность в Prettier. Чтобы отформатировать код, вы можете запустить yarn lint --fix, pnpm lint --fix, bun run lint --fix или обратиться к разделу ESLint для настройки IDE.

Если в вашем редакторе установлен Prettier, мы рекомендуем отключить его при работе над проектом, чтобы избежать конфликтов.

Примечание: мы обсуждаем включение функции Prettier в будущем.

Менеджер пакетов

Для библиотек мы рекомендуем pnpm. Для модулей мы по-прежнему рекомендуем yarn, но в будущем, возможно, сменим эту рекомендацию на pnpm, как только поддержим режим plug-and-play с самим Nuxt.

Важно включить Corepack, чтобы убедиться, что вы используете ту же версию пакетного менеджера, что и проект. Corepack встроен в новые версии node для беспрепятственной интеграции с менеджером пакетов.

Чтобы включить его, выполните команду:

Terminal

corepack enable

Это нужно сделать только один раз, после установки Node.js на ваш компьютер.

Руководство по стилю документации

Документация - важная часть Nuxt. Мы стремимся быть интуитивно понятным фреймворком - и большая часть этой цели заключается в том, чтобы убедиться, что и опыт разработчиков, и документация совершенны во всей экосистеме. 👌

Вот несколько советов, которые могут помочь улучшить вашу документацию:

По возможности избегайте таких субъективных слов, как просто, только, очевидно.
Не забывайте, что у ваших читателей может быть разное образование и опыт. Поэтому такие слова не передают смысл и могут навредить.
Просто убедитесь, что функция возвращает промис.
Убедитесь, что функция возвращает Promise.
Предпочитайте активный залог.
Ошибка будет выброшена Nuxt.
Nuxt выбросит ошибку.

Узнайте, как внести свой вклад в документацию.

Информирование о багах

Одна из самых ценных ролей в открытом исходном коде - это находить время для сообщения о багах.

Фреймворк

Некоторые специфические моменты, касающиеся вклада в репозиторий фреймворка.