Skip to content
Permalink
Branch: master
Find file Copy path
Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
180 lines (113 sloc) 20.9 KB
id title layout permalink next redirect_from
how-to-contribute
Как внести свой вклад?
contributing
docs/how-to-contribute.html
codebase-overview.html
contributing/how-to-contribute.html
tips/introduction.html

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

Правила поведения {#code-of-conduct}

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

Открытая разработка {#open-development}

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

Модель ветвления {#branch-organization}

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

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

Семантическое версионирование {#semantic-versioning}

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

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

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

Баги {#bugs}

Где находятся ишью? {#where-to-find-known-issues}

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

Как открыть новое ишью? {#reporting-new-issues}

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

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

Баги безопасности {#security-bugs}

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

Наши контакты {#how-to-get-in-touch}

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

Предложения по улучшению {#proposing-a-change}

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

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

Ваш первый пулреквест {#your-first-pull-request}

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

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

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

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

Как отправлять пулреквесты? {#sending-a-pull-request}

За пулреквестами следит основная команда разработчиков. Мы обязательно рассмотрим ваш пулреквест, а затем сделаем мёрж или попросим что-то доработать в нём. В крайнем случае мы можем отклонить пулреквест с обязательным объяснением причины. Изменения в 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) {#contributor-license-agreement-cla}

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

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

Что нужно для разработки? {#contribution-prerequisites}

  • У вас на компьютере должны быть установлены 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 {#development-workflow}

После клонирования репозитория 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 вашего тестового проекта.

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

Правила оформления кода {#style-guide}

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

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

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

Видео о процессе разработки React {#introductory-video}

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

Главные темы: {#video-highlights}

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

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

Рабочее предложение (Request for Comments, RFC) {#request-for-comments-rfc}

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

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

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

Лицензия {#license}

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

Что дальше? {#what-next}

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

You can’t perform that action at this time.