此文章是翻译How to Contribute这篇React(版本v16.2.0)官方文档。
React 是Facebook 的第一个开源项目,它正在积极发展并且在迁移代码到facebook.com 任何位置。我们仍然正在解决节点(kinkes)去是贡献这个项目尽可能的容易和透明,但是我们还没有达到。希望这篇文档能够使贡献清晰并且能够回答你可能遇到的一些问题。
Facebook 已经采纳Code of Conduct,我们希望项目参与者遵守。请阅读全文(the full text),这样你就可以了解什么行为会被或不会被允许。
在React 上的所有工作都直接发生在GitHub 上。包括核心团队成员和外部贡献者发送的pull request 都通过同样的审核过程。
我们将尽最大努力保持master
branch 良好状态,通过每一次测试都通过。但是为了快速移动(move),我们将使API 改变,你的应用程序可能不会兼容。我们推荐你使用React 的最新稳定版本。
如果你发出一个pull request,请不要在master
分支上进行。我们分别为主版本保留稳定分支,但是我们不直接接受pull request。相反,我们从master 摘樱桃(cherry-pick)不破坏(non-breaking)改变到最新的稳定主版本。
React 遵循语义化版本(sematic versioning)。我们发布修订号(patch version)为问题修复,次版本号(minor version)为新特性,主版本号(major version)为任何突破性改变。当我们产生突破性改变,我们也引入废弃警告(deprecation warning)在次版本号,以至于我们的用户了解到升级改变以及提前迁移他们的代码。
我们使用标签为每一个pull request 打tag,标志改变是否应该进入下一个patch、minor、major 版本号中。我们每隔几周发布一个修订号,每隔几月发布一个次版本号,每年发布一两次主版本号。
每一次重大改变都在changelog file记录。
我们为我们的公共bug 使用GitHub Issues。我们密切关注这块,并且当我们有一个内部解决进程时,将尝试解决它。在提交一个新的task 之前,请确保你的问题还没有存在过。
使你的问题得到解决的最好方式是提供一个简化的测试例子。JSFiddle tempalte 是非常好的开始点。
Facebook 有一个安全漏洞的安全泄漏的奖金项目。考虑到这一点,请不要提出公共问题;通过该页概述的过程。
- IRC: #reactjs on freenode
- Discussion forum: discuss.reactjs.org
假使你需要React 帮助,这也有an active community of React users on the Discord chat platform
如果你打算更改公共的API,或者为实现任何重大的改变,我们推荐你提交一个问题(filing an issue)。这使我们能够就你的建议达成协议,然后再付出巨大努力。
如果你只是修复一个bug,可以立即提交关于pull request ,但是我们仍推荐你提交一个问题,描述你修复的问题。这是有用的,假如我们不接收这个具体的修复(specific fix)但是想要跟踪这个问题。
这是你的第一个Pull Request?你能够从这免费的视频系列:How to Contribute to an Open Source Project on GitHub学习。
为了帮助你从实践中学习,并且让你熟悉我们的贡献构成,我们有一系列的good first bugs,它名包括相对容易去解决的bug。这是一个开始的伟大的地方。
如果你决定去修复一个问题,请确保检查这个评论线程,以防有人已经在修复这个问题。如果此刻没有人在工作,请留下一条评论,陈述你想要去工作,以至于其他人不会意外地重复你的努力。
如果有人提出了一个问题,但是超过两周没有被跟进,这是好的接管它,但是你应该仍然留一个评论。
核心团队监控pull request。我们将审查你的pull request,要么合并它,请求改变它,要么解释关闭它。对于API 改变,我们可能需要去在Facebook.com 去修复我们内部的使用,这将导致一些延迟。我们将尽我们最大的努力去更新并且反馈整个过程。
在提交一个pull request 之前, 请确保以下操作完成:
- 派生the repository,并且从
master
中创建你的分支。 - 在repository 根运行
yarn
。 - 如果你已经修复了bug 或添加了代码,这些代码应该被测试,添加测试!
- 确保测试组件通过(
yarn test
)。提示:yarn test --watch TestName
在开发时是有用的。 - 在生产环境运行
yarn test-prod
去测试。它和yarn test
支持相同的选项。 - 如果你需要debugger,运行
yarn debug-test --watch TestName
,打开chrome://inspect
,按“Inspect”。 - 使用prettier(
yarn prettier
)格式化你的代码。 - 确保你的代码lint(
yarn lint
)。提示:yarn linc
只检测改变的文件。 - 运行Flow 类型检测(
npm run flow
)。 - 如果你还没有,完成CLA。
为了接受你的pull request,我们需要你去提交CLA。你只需要去做一次,所以如果你已经为另一个Facebook 开源项目做过,你可以继续。如果你是第一次提交pull request,只要让我们知道你已经完成了CLA,我们可以再次确认(cross-check)你的GitHub 用户名
- 你已经安装了v8.0.0+ 的Node ,以及v1.2.0+ 的Yarn。
- 你已经安装了
gcc
,或安装需要的编译器。我们npm
中的一些依赖可能需要一个编译步骤。在OS X 上,Xcode 命令行工具将包括这些。在Ubuntu 上,apt-get install build-essential
将会安装需要的包。类似的命令应该也在其它Linux distros 上工作。Windows 需要一些额外的步骤,查看node-gyp
installation instructions 详细。 - 你熟悉
git
。
复制完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
但是使用debugger。打开chrome://inspect
,按“Inspect”。yarn flow
运行Flow 类型检测。yarn build
创建一个所有包的build
文件夹。yarn build core,dom --type=UMD
创建只有React 和ReactDOM 的UMD 构建。
我们推荐运行yarn test
(或者上面它的变种)去确保你不会引入任何回退,当你工作在你的改变上。然而,它可以被掌握去试验你的React 构建在一个真实的项目中。
首先,运行yarn build
。这将会生产预构建插件在build
文件夹,以及在build/package
中的准备的npm 包。
最简单的方式去试验你的改变是去运行yarn build core,dom --type=UMD
然后打开fixtures/packaging/babel-standlalone/dev.html
。这文件已经使用来自build
文件夹的react.development.js
,所以它能捡起你的变化。
如果你要在你的已经存在的React 项目中试验你的改变,你可以复制build/dist/react.development.js
、build/dist/react-dom.development.js
或任何其它构建版本到你的应用中,并使用它们而不是使用稳定版本。如果你的项目使用来自npm 的React,你可以在依赖中删除react
和react-dom
,使用yarn link
去指示它们在你本地的build
文件夹中:
cd ~/path_to_your_react_clone/build/packages/react
yarn link
cd ~/path_to_your_react_clone/build/packages/react-dom
yarn link
cd /path/to/your/project
yarn link react react-dom
每次在React 文件夹中运行yarn build
,这个更新的版本将显示在你的项目的node_modules
。你能够重新构建你的你的项目去试验的你的改变。
我们仍然需要你的pull request 包括任何新功能的单元测试。这种方式我们能够确保我们在未来不会破坏你的代码。
我们使用称为Prettier的自动的代码格式化。在任何代码改变之后运行yarn prettier
。
我们linter 将会捕获存在与你的代码中大多数的问题。你可以通过简单的运行yarn linc
去查看你的代码样式的状态。
然而,仍然有一些linter 不能找到一些样式。如果你确认这些事,查看Aribnb's Style Guide 将会给你一个正确的方向。
你可能有兴趣观看这个短视频(26 mins),介绍如何对React 做贡献。
Video highlights:
- 4:12 - 本地构建和测试React
- 6:07 - 创建和发送pull request
- 8:25 - 组织代码
- 14:43 - React npm registry
- 19:15 - 添加新的React 特性
要了解第一次为React 做出贡献的感觉是什么,请看这个有趣的ReactNYC 演讲。
React 小组每周召开一次会议,讨论React 的未来计划、优先项目的开发。你可以找到会议笔记在a dedicated repository。
通过给React 作贡献,你同意你的贡献将授权其在MIT 许可下。
阅读下一章节 去了解代码库是如何被组织的。