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

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

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

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

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

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

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

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

Ветки стабильных релизов мы ведём отдельно. Пулреквесты в них не принимаются. Для пулреквестов предназначена ветка master. Отлаженные изменения из неё переносятся в ветку текущего стабильного релиза.

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

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

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

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

Баги

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

  • У вас на компьютере должны быть установлены Node.js версии 8.0.0 или выше и Yarn 1.2.0 или выше.
  • Некоторые зависимости 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 test.
  • 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 на реальном проекте.

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

Для того чтобы проверить работоспособность изменений, проще всего запустить команду yarn build react/index,react-dom/index --type=UMD. После её завершения нужно открыть файл fixtures/packaging/babel-standalone/dev.html. Этот файл запускает скомпилированный react.development.js из папки build.

Если вы хотите провести испытания на уже существующем приложении, вам нужно скопировать build/dist/react.development.js, build/dist/react-dom.development.js и остальные файлы в свой проект вместо стабильной сборки React. В случае, когда вы используете npm-пакеты, следует удалить react и react-dom из списка зависимостей и запустить команду yarn link.

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

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

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

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

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

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

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

Видео о процессе разработки React

Посмотрите этот небольшой видеоролик (26 минут), в котором показан весь процесс разработки React.

Главные темы:

  • 4:12 — сборка и тестирование React
  • 6:07 — создание и отправка пулреквестов
  • 8:25 — структура проекта
  • 14:43 — работа с npm-зависимостями React
  • 19:15 — добавление новой функциональности

Вот ещё одно видео с выступлением на митапе ReactNYC. В нём Шон Вонг (Shawn Wang) рассказывает о своём опыте работы над React.

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

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

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

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

Лицензия

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

Что дальше?

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