Как внести свой вклад?

React — это один из первых проектов c открытым исходным кодом в компании Facebook, который очень активно развивается и в то же время используется для разработки facebook.com. Мы стараемся сделать процесс открытой разработки как можно более простым и прозрачным, но нам ещё есть над чем поработать. Надеемся, что этот раздел прояснит многие вопросы, касающиеся участия в разработке React.

Правила поведения

Компания Facebook приняла соглашение участника в качестве своего кодекса поведения, поэтому мы ожидаем, что участники проекта будут его придерживаться. Пожалуйста, прочитайте полный текст, чтобы понимать, как правильно себя вести, а как поступать недопустимо.

Открытая разработка

Разработка React ведётся на GitHub. Пулреквесты участников команды React и добровольцев принимаются на общих правах.

Семантическое версионирование

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

Все важные изменения заносятся в файл CHANGELOG.md.

Модель ветвления

Отправляйте все изменения прямиком в ветку main. Мы не используем раздельные ветки для разработки и предстоящих релизов. Мы стараемся сохранять ветку main в хорошем состоянии, где успешно проходят все тесты.

Код в ветке main должен быть совместим с последней стабильной версией. Такой код может содержать дополнительную функциональность, которая не ломает обратную совместимость. Поэтому в любой момент мы можем выпустить новую минорную версию из ветки main.

Флаги возможностей

Для того, чтобы выпускать релизы из ветки main, изменения, ломающие обратную совместимость, и экспериментальные возможности могут быть применены в зависимости от значений флагов возможностей.

Флаги возможностей объявлены в packages/shared/ReactFeatureFlags.js. Разные сборки React могут включать различные наборы флагов возможностей; например, сборка React Native может быть конфигурироваться иначе, чем сборка React DOM. Такие флаги находятся в packages/shared/forks. Флаги возможностей имеют статическую типизацию, заданную с помощью Flow, поэтому запустив yarn flow, можно убедиться, что все необходимые файлы были обновлены.

Система сборки React перед выпуском новой версии удаляет ветви кода с отключённой функциональностью. Задачи непрерывной интеграции запускаются на каждый коммит, чтобы проверить изменения размера бандла. Это значение можно использовать как своего рода сигнал, что та или иная возможность была правильно обработана.

Баги

Где находятся ишью?

Мы используем ишью на GitHub для отслеживания багов. Мы уделяем серьёзное внимание всем ишью и стараемся информировать пользователей о том, какие баги мы исправляем в данный момент.

Как открыть новое ишью?

Для того чтобы было легче исправить баг, нужен пример кода. Поработать с таким примером и отловить баг можно в онлайн-песочнице, например, в JSFiddle.

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

Баги безопасности

У Facebook есть программа Bug Bounty для сообщения о багах безопасности. Пожалуйста, не публикуйте ишью о таких проблемах в открытом доступе. Если вы обнаружили дыру в безопасности React, зайдите на эту страницу и следуйте инструкциям.

Наши контакты

Кроме этого есть сообщество пользователей React на платформе чатов Discord. Туда вы также можете обратиться за помощью.

Предложения по улучшению

Если у вас есть предложения по улучшению React или вы хотите что-то изменить в реализации его функций, откройте новое ишью, чтобы обсудить с нами все нюансы прежде, чем вы начнёте работать.

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

Ваш первый пулреквест

Уже приступили к работе над вашим первым пулреквестом? Посмотрите несколько видеороликов о том, как нужно работать с проектом на GitHub.

Чтобы облегчить вам первые шаги в освоении процесса разработки React, мы завели специальный тег good first issues, по которому можно получить список не очень сложных багов. Будет хорошо, если вы начнёте работу именно с этого списка.

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

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

Как отправлять пулреквесты?

За пулреквестами следит основная команда разработчиков. Мы обязательно рассмотрим ваш пулреквест, а затем сделаем мёрж или попросим что-то доработать в нём. В крайнем случае мы можем отклонить пулреквест с обязательным объяснением причины. Изменения в API вносятся не сразу, потому что нужно отследить и настроить внешние зависимости сайта Facebook.com. Мы делаем всё возможное для обеспечения хорошей обратной связи при выполнении изменений.

Перед тем как отправлять пулреквест, нужно выполнить следующие действия:

Форкнуть репозиторий React и создать собственную ветку от главной ветки main.
Запустить команду yarn в корне репозитория.
Если вы исправляете баг и добавляете код, который должен быть обязательно протестирован, не забудьте запустить тесты!
Убедиться, что все тесты проходят нормально (yarn test). Совет: команда yarn test --watch TestName может оказаться очень полезной в процессе разработки.
Протестировать рабочее окружение с помощью команды yarn test --prod.
Если вам нужно отладить код, запустите yarn test --debug --watch TestName, откройте chrome://inspect и нажмите «Inspect».
Отформатировать код с помощью утилиты prettier (yarn prettier).
Запустить линтер (yarn lint). Совет: команда yarn linc анализирует только изменённые файлы.
Выполнить проверку типов с помощью Flow (yarn flow).
Подписать соглашение добровольного разработчика (Contributor License Agreement).

Соглашение добровольного разработчика (Contributor License Agreement, CLA)

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

Здесь вы можете прочитать и подписать CLA

Что нужно для разработки?

У вас на компьютере должны быть установлены Node LTS версии и Yarn 1.2.0 или выше.
У вас установлен JDK.
Некоторые зависимости React нужно компилировать. Для этого вам необходимо установить gcc. Если у вас OS X, то Xcode Command Line Tools справятся с этой задачей. В Ubuntu команда apt-get install build-essential установит все необходимые пакеты. В других Linux-дистрибутивах установка выполняется с помощью аналогичных команд. Для Windows последовательность действий описана в инструкции по установке node-gyp.
Знание Git.

Порядок сборки и тестирования React

После клонирования репозитория React, запустите yarn, чтобы загрузить все необходимые зависимости. Теперь можно использовать следующие команды:

yarn lint для проверки кода.
yarn linc аналогична yarn lint, но работает быстрее, так как проверяет только изменённые файлы в вашей текущей ветке.
yarn test запускает тесты.
yarn test --watch запускает тесты в интерактивном режиме с наблюдением за изменениями.
yarn test <pattern> запускает тесты только для выбранных файлов.
yarn test --prod тестирует рабочее окружение.
yarn debug-test аналогична yarn test, но имеет возможность отладки. Откройте chrome://inspect и нажмите «Inspect».
yarn flow запускает Flow для проверки типов.
yarn build создаёт папку build, в которую помещает готовые пакеты.
yarn build react/index,react-dom/index --type=UMD создаёт UMD-сборки для React и ReactDOM.

Мы рекомендуем выполнять тестирование ваших изменений с помощью команды yarn test или её аналогов для того, чтобы убедиться, что они ничего не сломали. Тем не менее, было бы здорово проверить React-сборку с вашими изменениями на реальном проекте.

В некоторых случаях лучше выполнять тестирование сборки React на реальном проекте.

Для этого, прежде всего, нужно запустить команду yarn build. Эта команда компилирует и выгружает в папку build готовую сборку, а также создаёт в папке build/packages npm-пакеты.

Если вы хотите попробовать свои изменения в существующем проекте на React, вы можете скопировать build/node_modules/react/umd/react.development.js, build/node_modules/react-dom/umd/react-dom.development.js, или любые другие продукты сборки в вашем приложении и использовать их вместо стабильной версии.

Если ваш проект использует React из npm, вы можете удалить react и react-dom в этой зависимости и использовать yarn lint, чтобы направить их на локальную папку build. Обратите внимание, что вместо --type=UMD вы можете передать --type=NODE при сборке. Вам также будет нужно собрать пакет scheduler:

cd ~/path_to_your_react_clone/
yarn build react/index,react/jsx,react-dom/index,scheduler --type=NODE

cd build/node_modules/react
yarn link
cd build/node_modules/react-dom
yarn link

cd ~/path/to/your/project
yarn link react react-dom

После каждого запуска в корневой папке React команды yarn build пакеты React будут обновляться в node_modules вашего тестового проекта.

Если какой-то пакет всё ещё пропущен (например, если react-dom/server используется в проекте), вы можете всегда сделать полную сбоку через yarn build. Заметьте, что запуск yarn build без дополнительных параметров занимает много времени.

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

Правила оформления кода

Для автоматического форматирования кода мы используем Prettier. Запускайте yarn prettier после каждого редактирования кода.

Линтер отлавливает большую часть проблем, которые есть в ваших программах. Для проверки состояния вашего кода запустите команду yarn linc.

Линтер не может выловить все проблемы в оформлении кода. Если вы в чём-то сомневаетесь, поищите ответ в Airbnb’s Style Guide.

Рабочее предложение (Request for Comments, RFC)

Большинство изменений, включая исправления багов и улучшение документации, обычно предлагаются и реализуются с помощью простых пулреквестов на GitHub.

Но кроме них есть и «глобальные» изменения, которые требуют серьёзного обсуждения и продуманных архитектурных решений со стороны основной команды React.

Рабочее предложение (Request for Comments, RFC) — это процесс, призванный определить сбалансированный и предсказуемый путь для реализации новых функций до того, как будет начата работа над ними. Для рабочих предложений предназначен rfc-репозиторий.

Лицензия

React распространяется под лицензией MIT. Поэтому работая над своими пулреквестами, вы соглашаетесь с тем, что ваш код будет иметь соответствующую лицензию.

Что дальше?

В следующем разделе описана кодовая база React.

Is this page useful?Отредактировать эту страницу