diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index e5a8f42e7b5..05d3ba0d075 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,196 +1,5 @@ # Contributing to React Native -React Native is one of Facebook's first open source projects that is both under very active development and is also being used to ship code to everybody on https://facebook.com. We're still working out the kinks to make contributing to this project as easy and transparent as possible, but we're not quite there yet. Hopefully this document makes the process for contributing clear and preempts some questions you may have. +Want to contribute to React Native? There are a few things you need to know. -## Code of Conduct - -Facebook has adopted a Code of Conduct that we expect project participants to adhere to. Please read [the full text](https://code.facebook.com/codeofconduct) so that you can understand what actions will and will not be tolerated. - -## Our Development Process - -Some of the core team will be working directly on [GitHub](https://github.com/facebook/react-native). These changes will be public from the beginning. Other changesets will come via a bridge with Facebook's internal source control. This is a necessity as it allows engineers at Facebook outside of the core team to move fast and contribute from an environment they are comfortable in. - -## Branch Organization - -We will do our best to keep `master` in good shape, with tests passing at all times. But in order to move fast, we will make API changes that your application might not be compatible with. We will do our best to [communicate these changes](https://github.com/facebook/react-native/releases) and version appropriately so you can lock into a specific version if need be. - -To see what changes are coming and provide better feedback to React Native contributors, use the [latest release candidate](http://facebook.github.io/react-native/versions.html) when possible. By the time a release candidate is released, the changes it contains will have been shipped in production Facebook apps for over two weeks. - -## Bugs - -#### Where to Find Known Issues - -We are using [GitHub Issues](https://github.com/facebook/react-native/issues) for our public bugs. Before filing a new task, try to make sure your problem doesn't already exist. - -Questions and feature requests are tracked elsewhere: - - - Have a question? [Ask on Stack Overflow](http://stackoverflow.com/questions/tagged/react-native). - - If you have a question regarding future plans, check out the [roadmap](https://github.com/facebook/react-native/wiki/Roadmap). - - Have a feature request that is not covered in the roadmap? [Add it here](https://react-native.canny.io/feature-requests). - -#### Reporting New Issues - -The best way to get your bug fixed is to provide a reduced test case. Please provide either a [Sketch](https://sketch.expo.io/) or a public repository with a runnable example. - -Please report a single bug per issue. Always provide reproduction steps. You can use Snack in many cases to demonstrate an issue: https://snack.expo.io/. If the bug cannot be reproduced using Snack, verify that the issue can be reproduced locally by targeting the latest release candidate. Ideally, check if the issue is present in master as well. - -Do not forget to include sample code that reproduces the issue. Only open issues for bugs affecting either the latest stable release, or the current release candidate, or master (see http://facebook.github.io/react-native/versions.html). If it is not clear from your report that the issue can be reproduced in one of these releases, your issue will be closed. - -We're not able to provide support through GitHub Issues. If you're looking for help with your code, consider asking on Stack Overflow: http://stackoverflow.com/questions/tagged/react-native - -#### Security Bugs - -Facebook has a [bounty program](https://www.facebook.com/whitehat/) for the safe disclosure of security bugs. With that in mind, please do not file public issues; go through the process outlined on that page. - -## How to Get in Touch - -Many React Native users are active on [Stack Overflow](http://stackoverflow.com/questions/tagged/react-native). - -If you want to get a general sense of what React Native folks talk about, check out the [React Native Community](https://www.facebook.com/groups/react.native.community) Facebook group. - -There is also [an active community of React and React Native users on the Discord chat platform](https://discord.gg/0ZcbPKXt5bZjGY5n) in case you need help. - -The React Native team sends out periodical updates through the following channels: - -* [Blog](https://facebook.github.io/react-native/blog/) -* [Twitter](https://www.twitter.com/reactnative) - -Core contributors to React Native meet monthly and post their meeting notes on the React Native blog. You can also find ad hoc discussions in the [React Native Core Contributors](https://www.facebook.com/groups/reactnativeoss/) Facebook group. - -## Proposing a Change - -If you intend to change the public API, or make any non-trivial changes to the implementation, we recommend [filing an issue](https://github.com/facebook/react-native/issues/new). This lets us reach an agreement on your proposal before you put significant effort into it. - -If you're only fixing a bug, it's fine to submit a pull request right away but we still recommend to file an issue detailing what you're fixing. This is helpful in case we don't accept that specific fix but want to keep track of the issue. - -## Pull Requests - -If you send a pull request, please do it against the master branch. We maintain stable branches for stable releases separately but we don't accept pull requests to them directly. Instead, we cherry-pick non-breaking changes from master to the latest stable version. - -The core team will be monitoring for pull requests. When we get one, we'll run some Facebook-specific integration tests on it first. From here, we'll need to get another person to sign off on the changes and then merge the pull request. For API changes we may need to fix internal uses, which could cause some delay. We'll do our best to provide updates and feedback throughout the process. - -Small pull requests are much easier to review and more likely to get merged. Make sure the PR does only one thing, otherwise please split it. - -*Before* submitting a pull request, please make sure the following is done… - -1. Fork the repo and create your branch from `master`. -2. Add the copyright notice to the top of any new files you've added. -3. Describe your **test plan** in your commit. -4. Ensure **tests pass** on Travis and Circle CI. -5. Make sure your code lints (`node linter.js `). -6. If you haven't already, sign the CLA: https://code.facebook.com/cla -7. Squash your commits (`git rebase -i`). - One intent alongside one commit makes it clearer for people to review and easier to understand your intention. - -> **Note:** It is not necessary to keep clicking `Merge master to your branch` on the PR page. You would want to merge master if there are conflicts or tests are failing. The Facebook-GitHub-Bot ultimately squashes all commits to a single one before merging your PR. - -#### Test plan - -A good test plan has the exact commands you ran and their output, provides screenshots or videos if the pull request changes UI or updates the website. - - - If you've added code that should be tested, add tests! - - If you've changed APIs, update the documentation. - - If you've updated the docs, verify the website locally and submit screenshots if applicable (see `website/README.md`) - -See "What is a Test Plan?" to learn more: -https://medium.com/@martinkonicek/what-is-a-test-plan-8bfc840ec171#.y9lcuqqi9 - -#### Continuous integration tests - -Make sure all **tests pass** on both [Travis][travis] and [Circle CI][circle]. PRs that break tests are unlikely to be merged. - -You can learn more about running tests and contributing to React Native here: https://facebook.github.io/react-native/docs/testing.html - -[travis]: https://travis-ci.org/facebook/react-native -[circle]: http://circleci.com/gh/facebook/react-native - -#### Breaking changes - -When adding a new breaking change, follow this template in your pull request: - -``` -### New breaking change here - -- **Who does this affect**: -- **How to migrate**: -- **Why make this breaking change**: -- **Severity (number of people affected x effort)**: -``` - -If your pull request is merged, a core contributor will update the [list of breaking changes](https://github.com/facebook/react-native/wiki/Breaking-Changes) which is then used to populate the release notes. - -#### Copyright Notice for files - -Copy and paste this to the top of your new file(s): - -```JS -/** - * Copyright (c) 2015-present, Facebook, Inc. - * All rights reserved. - * - * This source code is licensed under the BSD-style license found in the - * LICENSE file in the root directory of this source tree. An additional grant - * of patent rights can be found in the PATENTS file in the same directory. - */ -``` - -If you've added a new module, add a `@providesModule ` at the end of the comment. This will allow the haste package manager to find it. - -### Contributor License Agreement (CLA) - -In order to accept your pull request, we need you to submit a CLA. You only need to do this once, so if you've done this for another Facebook open source project, you're good to go. If you are submitting a pull request for the first time, just let us know that you have completed the CLA and we can cross-check with your GitHub username. - -Complete your CLA here: https://code.facebook.com/cla - -## Style Guide - -Our linter will catch most styling issues that may exist in your code. You can check the status of your code styling by simply running `node linter.js `. - -However, there are still some styles that the linter cannot pick up. - -### Code Conventions - -#### General - -* **Most important: Look around.** Match the style you see used in the rest of the project. This includes formatting, naming things in code, naming things in documentation. -* Add trailing commas, -* 2 spaces for indentation (no tabs) -* "Attractive" - -#### JavaScript - -* Use semicolons; -* `'use strict';` -* Prefer `'` over `"` -* Do not use the optional parameters of `setTimeout` and `setInterval` -* 80 character line length - -#### JSX - -* Prefer `"` over `'` for string literal props -* When wrapping opening tags over multiple lines, place one prop per line -* `{}` of props should hug their values (no spaces) -* Place the closing `>` of opening tags on the same line as the last prop -* Place the closing `/>` of self-closing tags on their own line and left-align them with the opening `<` - -#### Objective-C - -* Space after `@property` declarations -* Brackets on *every* `if`, on the *same* line -* `- method`, `@interface`, and `@implementation` brackets on the following line -* *Try* to keep it around 80 characters line length (sometimes it's just not possible...) -* `*` operator goes with the variable name (e.g. `NSObject *variableName;`) - -#### Java - -* If a method call spans multiple lines closing bracket is on the same line as the last argument. -* If a method header doesn't fit on one line each argument goes on a separate line. -* 100 character line length - -### Documentation - -* Do not wrap lines at 80 characters - configure your editor to soft-wrap when editing documentation. - -## License - -By contributing to React Native, you agree that your contributions will be licensed under its BSD license. +We wrote a [contribution guide](https://facebook.github.io/react-native/docs/contributing.html) to help you get started. diff --git a/README.md b/README.md index e4ff6719c53..f4399cdf4d2 100644 --- a/README.md +++ b/README.md @@ -1,40 +1,33 @@ -# React Native [![Build Status](https://travis-ci.org/facebook/react-native.svg?branch=master)](https://travis-ci.org/facebook/react-native) [![Circle CI](https://circleci.com/gh/facebook/react-native.svg?style=shield)](https://circleci.com/gh/facebook/react-native) [![npm version](https://badge.fury.io/js/react-native.svg)](https://badge.fury.io/js/react-native) +# [React Native](https://facebook.github.io/react-native/) · [![Travis CI Status](https://travis-ci.org/facebook/react-native.svg?branch=master)](https://travis-ci.org/facebook/react-native) [![Circle CI Status](https://circleci.com/gh/facebook/react-native.svg?style=shield)](https://circleci.com/gh/facebook/react-native) [![npm version](https://badge.fury.io/js/react-native.svg)](https://badge.fury.io/js/react-native) [![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](CONTRIBUTING.md#pull-requests) -React Native enables you to build world-class application experiences on native platforms using a consistent developer experience based on JavaScript and [React](https://facebook.github.io/react). The focus of React Native is on developer efficiency across all the platforms you care about - learn once, write anywhere. Facebook uses React Native in multiple production apps and will continue investing in React Native. +Learn once, write anywhere: Build mobile apps with React. + +- **Build native mobile apps using JavaScript and React:** React Native lets you build mobile apps using only JavaScript. It uses the same design as [React](https://facebook.github.io/react), letting you compose a rich mobile UI from declarative components. +- **A React Native app is a real mobile app:** With React Native, you don't build a "mobile web app", an "HTML5 app", or a "hybrid app". You build a real mobile app that's indistinguishable from an app built using Objective-C, Java, or Swift. React Native uses the same fundamental UI building blocks as regular iOS and Android apps. You just put those building blocks together using JavaScript and React. +- **Don't waste time recompiling:** React Native lets you build your app faster. Instead of recompiling, you can reload your app instantly. With hot reloading, you can even run new code while retaining your application state. Give it a try - it's a magical experience. +- **Use native code when you need to:** React Native combines smoothly with components written in Objective-C, Java, or Swift. It's simple to drop down to native code if you need to optimize a few aspects of your application. It's also easy to build part of your app in React Native, and part of your app using native code directly - that's how the Facebook app works. + +The focus of React Native is on developer efficiency across all the platforms you care about - learn once, write anywhere. Facebook uses React Native in multiple production apps and will continue investing in React Native. + +See the official [React Native website](https://facebook.github.io/react-native/) for an introduction to React Native. Supported operating systems are >= Android 4.1 (API 16) and >= iOS 8.0. - [Getting Started](#getting-started) - [Getting Help](#getting-help) - [Documentation](#documentation) -- [Examples](#examples) -- [Extending React Native](#extending-react-native) - [Upgrading](#upgrading) - [Opening Issues](#opening-issues) - [Contributing](#contributing) - [License](#license) -## Introduction - -See the official [React Native website](https://facebook.github.io/react-native/) for an introduction to React Native. - ## Getting Started -- Follow the [Getting Started guide](https://facebook.github.io/react-native/docs/getting-started.html) to install React Native and its dependencies. -- [Open the RNTester app](#examples) to see a list of components that ship with React Native. -- Install the React Developer Tools for [Chrome](https://chrome.google.com/webstore/detail/react-developer-tools/fmkadmapgofadopljbjfkapdkoienihi) or [Firefox](https://addons.mozilla.org/firefox/addon/react-devtools/) for better debugging [(read more)](https://facebook.github.io/react-native/docs/debugging.html). -- Try out apps from the [Showcase](https://facebook.github.io/react-native/showcase.html) to see what React Native is capable of! +Follow the [Getting Started guide](https://facebook.github.io/react-native/docs/getting-started.html). The recommended way to install React Native depends on your project. Here you can find short guides for the most common scenarios: -## Getting Help - -Please use these community resources for getting help. We use the GitHub issues for tracking bugs and feature requests and have limited bandwidth to address them. - -- Ask a question on [StackOverflow](https://stackoverflow.com/) and tag it with `react-native` -- Chat with us on [Reactiflux](https://discord.gg/0ZcbPKXt5bWJVmUY) in #react-native -- Articulate your feature request or upvote existing ones on [Canny](https://react-native.canny.io/feature-requests) -- Start a thread on the [React Discussion Board](https://discuss.reactjs.org/) -- Join #reactnative on IRC: chat.freenode.net -- If it turns out that you may have found a bug, please [open an issue](#opening-issues) +- [Trying out React Native](https://snack.expo.io/BJ-uC-nrb) +- [Creating a New Application](http://facebook.github.io/react-native/docs/getting-started.html) +- [Adding React Native to an Existing Application](http://facebook.github.io/react-native/docs/integration-with-existing-apps.html) ## Documentation @@ -48,54 +41,29 @@ Another great way to learn more about the components and APIs included with Reac The React Native documentation only discusses the components, APIs and topics specific to React Native (React on iOS and Android). For further documentation on the React API that is shared between React Native and React DOM, refer to the [React documentation](https://facebook.github.io/react/). -## Examples - -- `git clone https://github.com/facebook/react-native.git` -- `cd react-native && npm install` - -### Running the RNTester app on iOS - -Now open `RNTester/RNTester.xcodeproj` and hit Run in Xcode. - -### Running the RNTester app on Android - -Note that you'll need the Android NDK installed, see [prerequisites](https://github.com/facebook/react-native/blob/master/ReactAndroid/README.md#prerequisites). - -```bash -./gradlew :RNTester:android:app:installDebug -# Start the packager in a separate shell (make sure you ran npm install): -./scripts/packager.sh -``` - -## Extending React Native - -- Looking for a component? [JS.coach](https://js.coach/react-native) -- Fellow developers write and publish React Native modules to npm and open source them on GitHub. -- Making modules helps grow the React Native ecosystem and community. We recommend writing modules for your use cases and sharing them on npm. -- Read the guides on Native Modules ([iOS](https://facebook.github.io/react-native/docs/native-modules-ios.html), [Android](https://facebook.github.io/react-native/docs/native-modules-android.html)) and Native UI Components ([iOS](https://facebook.github.io/react-native/docs/native-components-ios.html), [Android](https://facebook.github.io/react-native/docs/native-components-android.html)) if you are interested in extending native functionality. - ## Upgrading React Native is under active development. See the guide on [upgrading React Native](https://facebook.github.io/react-native/docs/upgrading.html) to keep your project up-to-date. -## Opening Issues - -If you encounter a bug with React Native we would like to hear about it. Search the [existing issues](https://github.com/facebook/react-native/issues) and try to make sure your problem doesn’t already exist before opening a new issue. It’s helpful if you include the version of React Native and OS you’re using. Please include a stack trace and reduced repro case when appropriate, too. - -The GitHub issues are intended for bug reports and feature requests. For help and questions with using React Native please make use of the resources listed in the [Getting Help](#getting-help) section. [Canny](https://react-native.canny.io/feature-requests) in particular is a good way to signal your interest in a feature or issue. There are limited resources available for handling issues and by keeping the list of open issues lean we can respond in a timely manner. - ## Contributing -For more information about contributing PRs and issues, see our [Contribution Guidelines](https://github.com/facebook/react-native/blob/master/CONTRIBUTING.md). +Read below to learn how you can take part in improving React Native. -[Good First Task](https://github.com/facebook/react-native/labels/Good%20First%20Task) is a great starting point for PRs. +### [Code of Conduct](https://code.facebook.com/codeofconduct) + +Facebook has adopted a Code of Conduct that we expect project participants to adhere to. Please read [the full text](https://code.facebook.com/codeofconduct) so that you can understand what actions will and will not be tolerated. + +### Contributing Guide + +Read our [contributing guide](CONTRIBUTING.md) to learn about our development process, how to propose bugfixes and improvements, and how to build and test your changes to React Native. + +### Beginner Friendly Bugs + +We have a list of [beginner friendly bugs](https://github.com/facebook/react-native/issues?q=is%3Aopen+is%3Aissue+label%3A%22Good+First+Task%22) to help you get your feet wet in the React Native codebase and familiar with our contribution process. This is a great place to get started. -We encourage the community to ask and answer questions on Stack Overflow with [the react-native tag](https://stackoverflow.com/questions/tagged/react-native). It's a great way to help out and be involved! ## License React is [BSD licensed](./LICENSE). We also provide an additional [patent grant](./PATENTS). React documentation is [Creative Commons licensed](./LICENSE-docs). - -Examples provided in this repository and in the documentation are [separately licensed](./LICENSE-examples), as are some of the [custom components](./LICENSE-CustomComponents). diff --git a/docs/Contributing.md b/docs/Contributing.md new file mode 100644 index 00000000000..0cf5526d5a8 --- /dev/null +++ b/docs/Contributing.md @@ -0,0 +1,243 @@ +--- +id: contributing +title: How to Contribute +layout: docs +category: Guides +permalink: docs/contributing.html +next: testing +previous: upgrading +--- + +React Native is one of Facebook's first open source projects that is both under very active development and is also being used to ship code to everybody using Facebook's mobile apps. We're still working out the kinks to make contributing to this project as easy and transparent as possible, but we're not quite there yet. Hopefully this document makes the process for contributing clear and preempts some questions you may have. + +## Code of Conduct + +Facebook has adopted a Code of Conduct that we expect project participants to adhere to. Please read [the full text](https://code.facebook.com/codeofconduct) so that you can understand what actions will and will not be tolerated. + +## Our Development Process + +Some of the core team will be working directly on [GitHub](https://github.com/facebook/react-native). These changes will be public from the beginning. Other changesets will come via a bridge with Facebook's internal source control. This is a necessity as it allows engineers at Facebook outside of the core team to move fast and contribute from an environment they are comfortable in. + +## Branch Organization + +We will do our best to keep `master` in good shape, with tests passing at all times. But in order to move fast, we will make API changes that your application might not be compatible with. We will do our best to [communicate these changes](https://github.com/facebook/react-native/releases) and version appropriately so you can lock into a specific version if need be. + +To see what changes are coming and provide better feedback to React Native contributors, use the [latest release candidate](http://facebook.github.io/react-native/versions.html) when possible. By the time a release candidate is released, the changes it contains will have been shipped in production Facebook apps for over two weeks. + +## Bugs + +### Where to Find Known Issues + +We are using [GitHub Issues](https://github.com/facebook/react-native/issues) for our public bugs. Before filing a new task, try to make sure your problem doesn't already exist. + +Questions and feature requests are tracked elsewhere: + + - Have a question? [Ask on Stack Overflow](http://stackoverflow.com/questions/tagged/react-native). + - If you have a question regarding future plans, check out the [roadmap](https://github.com/facebook/react-native/wiki/Roadmap). + - Have a feature request that is not covered in the roadmap? [Add it here](https://react-native.canny.io/feature-requests). + +### Reporting New Issues + +The best way to get your bug fixed is to provide a reduced test case. Please provide either a [Snack](https://snack.expo.io/) or a public repository with a runnable example. + +Please report a single bug per issue. Always provide reproduction steps. You can use [Snack](https://snack.expo.io/) in many cases to demonstrate an issue. If the bug cannot be reproduced using Snack, verify that the issue can be reproduced locally by targeting the latest release candidate. Ideally, check if the issue is present in `master` as well. + +Do not forget to include sample code that reproduces the issue. Only open issues for bugs affecting either the latest stable release, or the current release candidate, or master (see the [list of versions](http://facebook.github.io/react-native/versions.html)). If it is not clear from your report that the issue can be reproduced in one of these releases, your issue will be closed. + +We're not able to provide support through GitHub Issues. If you're looking for help with your code, consider asking on [Stack Overflow](http://stackoverflow.com/questions/tagged/react-native). + +### Security Bugs + +Facebook has a [bounty program](https://www.facebook.com/whitehat/) for the safe disclosure of security bugs. With that in mind, please do not file public issues; go through the process outlined on that page. + +## Triaging issues and pull requests + +One great way you can contribute to the project without writing any code is to help triage issues and pull requests as they come in. Ask for more information if the issue does not provide all the details required by the template. Suggest [labels](https://github.com/facebook/react-native/labels). Flag issues that are stale or that should be closed. Ask for test plans and review code. + +Adding labels, closing and reopening issues, and merging pull requests is, as you may expect, limited to a subset of contributors. Simply commenting on the issue or pull request can still go a long way towards helping us keep the number of outstanding issues under control. + +### Using the Facebook GitHub Bot + +The Facebook GitHub Bot allows certain active members of the community to perform administrative actions such as labeling and closing issues. The list of community members with this kind of access can be found at the top of [`IssueCommands.txt`](https://github.com/facebook/react-native/blob/master/bots/IssueCommands.txt). The bot can be triggered by adding any of the following commands as a standalone comment on an issue: + +- `@facebook-github-bot close`: **Closes** an issue without providing a particular explanation. +- `@facebook-github-bot label (.*)`: Use this command to add a [label](https://github.com/facebook/react-native/labels), such as "iOS" or "Android", to an issue. +- `@facebook-github-bot duplicate (#[0-9]+)`: Marks an issue as a duplicate. Requires a issue number to be provided. The bot will **close** the issue. +- `@facebook-github-bot stack-overflow`: Mark issues that do not belong in the bug tracker, and redirect to Stack Overflow. The bot will **close** the issue after adding the _For Stack Overflow_ label. +- `@facebook-github-bot feature`: Use this when an issue describes a feature request, as opposed to a reproducible bug. The bot will point the author to the feature request tracker, add the _Feature Request_ label, then **close** the issue. +- `@facebook-github-bot expected`: Use this when an issue describes a type of expected behavior. The bot will **close** the issue. +- `@facebook-github-bot answered`: Use this when an issue appears to be a question that has already been answered by someone on the thread. The bot will **close** the issue. +- `@facebook-github-bot no-reply`: Use this when an issue requires more information from the author but they have not added a comment in over two weeks. The bot will **close** the issue. +- `@facebook-github-bot reopen`: **Re-opens** a previously closed issue. +- `@facebook-github-bot bugfix`: Mark issues that describe a reproducible bug. The bot will prompt the author to submit a pull request with a fix. +- `@facebook-github-bot icebox`: Use this when an issue has been open for over 30 days with no activity. The bot will **close** the issue after adding the _Icebox_ label. + +Additionally, the following commands can be used on a pull request: + +- `@facebook-github-bot cla`: Remind the author that the CLA needs to be signed. +- `@facebook-github-bot shipit`: Flag the PR for merging. If used by a core contributor, the bot will attempt to import the pull request. In general, core contributors are those who have consistently submitted high quality contributions to the project. + +## How to Get in Touch + +Many React Native users are active on [Stack Overflow](http://stackoverflow.com/questions/tagged/react-native). If you want to get a general sense of what React Native folks talk about, check out the [React Native Community](https://www.facebook.com/groups/react.native.community) Facebook group. There is also [an active community of React and React Native users on the Discord chat platform](https://discord.gg/0ZcbPKXt5bZjGY5n) in case you need help. + +The React Native team sends out periodical updates through the following channels: + +* [React Native Blog](https://facebook.github.io/react-native/blog/) +* [@ReactNative on Twitter](https://www.twitter.com/reactnative) + +Core contributors to React Native meet monthly and post their meeting notes on the React Native blog. You can also find ad hoc discussions in the [React Native Core Contributors](https://www.facebook.com/groups/reactnativeoss/) Facebook group. + +## Proposing a Change + +If you intend to change the public API, or make any non-trivial changes to the implementation, we recommend [filing an issue](https://github.com/facebook/react-native/issues/new). This lets us reach an agreement on your proposal before you put significant effort into it. + +If you're only fixing a bug, it's fine to submit a pull request right away but we still recommend to file an issue detailing what you're fixing. This is helpful in case we don't accept that specific fix but want to keep track of the issue. + +## Pull Requests + +### Your First Pull Request + +Working on your first Pull Request? You can learn how from this free video series: + +[**How to Contribute to an Open Source Project on GitHub**](https://egghead.io/courses/how-to-contribute-to-an-open-source-project-on-github) + +To help you get your feet wet and get you familiar with our contribution process, we have a list of [beginner friendly issues](https://github.com/facebook/react-native/labels/Good%20First%20Task) that contain bugs which are fairly easy to fix. This is a great place to get started. + +If you decide to fix an issue, please be sure to check the comment thread in case somebody is already working on a fix. If nobody is working on it at the moment, please leave a comment stating that you intend to work on it so other people don't accidentally duplicate your effort. + +If somebody claims an issue but doesn't follow up for more than two weeks, it's fine to take over it but you should still leave a comment. + +### Sending a Pull Request + +If you send a pull request, please do it against the master branch. We maintain stable branches for stable releases separately but we don't accept pull requests to them directly. Instead, we cherry-pick non-breaking changes from master to the latest stable version. + +The core team will be monitoring for pull requests. When we get one, we'll run some Facebook-specific integration tests on it first. From here, we'll need to get another person to sign off on the changes and then merge the pull request. For API changes we may need to fix internal uses, which could cause some delay. We'll do our best to provide updates and feedback throughout the process. + +Small pull requests are much easier to review and more likely to get merged. Make sure the PR does only one thing, otherwise please split it. + +**Before submitting a pull request**, please make sure the following is done… + +1. Fork [the repository](https://github.com/facebook/react-native) and create your branch from `master`. +2. Add the copyright notice to the top of any new files you've added. +3. Describe your **test plan** in your commit. +4. Ensure **tests pass** on both Travis and Circle CI. +5. Make sure your code lints (`node linter.js `). +6. If you haven't already, [sign the CLA](https://code.facebook.com/cla). + +> **Note:** It is not necessary to keep clicking `Merge master to your branch` on the PR page. You would want to merge master if there are conflicts or tests are failing. The Facebook-GitHub-Bot ultimately squashes all commits to a single one before merging your PR. + +#### Test plan + +A good test plan has the exact commands you ran and their output, provides screenshots or videos if the pull request changes UI or updates the website. + + - If you've added code that should be tested, add tests! + - If you've changed APIs, update the documentation. + - If you've updated the docs, verify the website locally and submit screenshots if applicable (see `website/README.md`) + +See "What is a Test Plan?" to learn more: +https://medium.com/@martinkonicek/what-is-a-test-plan-8bfc840ec171#.y9lcuqqi9 + +#### Continuous integration tests + +Make sure all **tests pass** on both [Travis][travis] and [Circle CI][circle]. PRs that break tests are unlikely to be merged. + +You can learn more about running tests and contributing to React Native [next](docs/testing.html). + +[travis]: https://travis-ci.org/facebook/react-native +[circle]: http://circleci.com/gh/facebook/react-native + +#### Breaking changes + +When adding a new breaking change, follow this template in your pull request: + +``` +### New breaking change here + +- **Who does this affect**: +- **How to migrate**: +- **Why make this breaking change**: +- **Severity (number of people affected x effort)**: +``` + +If your pull request is merged, a core contributor will update the [list of breaking changes](https://github.com/facebook/react-native/wiki/Breaking-Changes) which is then used to populate the release notes. + +#### Copyright Notice for files + +Copy and paste this to the top of your new file(s): + +```JS +/** + * Copyright (c) 2015-present, Facebook, Inc. + * All rights reserved. + * + * This source code is licensed under the BSD-style license found in the + * LICENSE file in the root directory of this source tree. An additional grant + * of patent rights can be found in the PATENTS file in the same directory. + */ +``` + +If you've added a new module, add a `@providesModule ` at the end of the comment. This will allow the haste package manager to find it. + +### Contributor License Agreement (CLA) + +In order to accept your pull request, we need you to submit a CLA. You only need to do this once, so if you've done this for another Facebook open source project, you're good to go. If you are submitting a pull request for the first time, just let us know that you have completed the CLA and we can cross-check with your GitHub username. + +Complete your CLA here: https://code.facebook.com/cla + +## Style Guide + +Our linter will catch most styling issues that may exist in your code. You can check the status of your code styling by simply running `node linter.js `. + +However, there are still some styles that the linter cannot pick up. + +### Code Conventions + +#### General + +* **Most important: Look around.** Match the style you see used in the rest of the project. This includes formatting, naming things in code, naming things in documentation. +* Add trailing commas, +* 2 spaces for indentation (no tabs) +* "Attractive" + +#### JavaScript + +* Use semicolons; +* `'use strict';` +* Prefer `'` over `"` +* Do not use the optional parameters of `setTimeout` and `setInterval` +* 80 character line length + +#### JSX + +* Prefer `"` over `'` for string literal props +* When wrapping opening tags over multiple lines, place one prop per line +* `{}` of props should hug their values (no spaces) +* Place the closing `>` of opening tags on the same line as the last prop +* Place the closing `/>` of self-closing tags on their own line and left-align them with the opening `<` + +#### Objective-C + +* Space after `@property` declarations +* Brackets on *every* `if`, on the *same* line +* `- method`, `@interface`, and `@implementation` brackets on the following line +* *Try* to keep it around 80 characters line length (sometimes it's just not possible...) +* `*` operator goes with the variable name (e.g. `NSObject *variableName;`) + +#### Java + +* If a method call spans multiple lines closing bracket is on the same line as the last argument. +* If a method header doesn't fit on one line each argument goes on a separate line. +* 100 character line length + +### Documentation + +* Do not wrap lines at 80 characters - configure your editor to soft-wrap when editing documentation. + +## License + +By contributing to React Native, you agree that your contributions will be licensed under its BSD license. + +## What Next? + +Read the [next section](docs/testing.html) to learn how to test your changes. diff --git a/docs/MoreResources.md b/docs/MoreResources.md index 71028c38b2e..a3ddb3f8769 100644 --- a/docs/MoreResources.md +++ b/docs/MoreResources.md @@ -18,15 +18,23 @@ One common question is how to handle the "state" of your React Native applicatio If you're looking for a library that does a specific thing, check out [Awesome React Native](http://www.awesome-react-native.com/), a curated list of components that also has demos, articles, and other stuff. -## Example Apps +## Examples -There are some [example apps on GitHub](https://github.com/ReactNativeNews/React-Native-Apps). You can run the apps on a simulator or device, and you can see the source code for these apps, which is neat. +Try out apps from the [Showcase](https://facebook.github.io/react-native/showcase.html) to see what React Native is capable of! There are also some [example apps on GitHub](https://github.com/ReactNativeNews/React-Native-Apps). You can run the apps on a simulator or device, and you can see the source code for these apps, which is neat. The folks who built the app for Facebook's F8 conference in 2016 also [open-sourced the code](https://github.com/fbsamples/f8app) and wrote up a [detailed series of tutorials](http://makeitopen.com/tutorials/building-the-f8-app/planning/). This is useful if you want a more in-depth example that's more realistic than most sample apps out there. +## Extending React Native + +- Looking for a component? [JS.coach](https://js.coach/react-native) +- Fellow developers write and publish React Native modules to npm and open source them on GitHub. +- Making modules helps grow the React Native ecosystem and community. We recommend writing modules for your use cases and sharing them on npm. +- Read the guides on Native Modules ([iOS](https://facebook.github.io/react-native/docs/native-modules-ios.html), [Android](https://facebook.github.io/react-native/docs/native-modules-android.html)) and Native UI Components ([iOS](https://facebook.github.io/react-native/docs/native-components-ios.html), [Android](https://facebook.github.io/react-native/docs/native-components-android.html)) if you are interested in extending native functionality. + + ## Development Tools -[Nuclide](https://nuclide.io/) is the IDE that Facebook uses internally for React Native development. The killer feature of Nuclide is its debugging ability. It also has great inline Flow support. +[Nuclide](https://nuclide.io/) is the IDE that Facebook uses internally for JavaScript development. The killer feature of Nuclide is its debugging ability. It also has great inline Flow support. [VS Code](https://code.visualstudio.com/) is another IDE that is popular with JavaScript developers. [Ignite](https://github.com/infinitered/ignite) is a starter kit that uses Redux and a few different common UI libraries. It has a CLI to generate apps, components, and containers. If you like all of the individual tech choices, Ignite could be perfect for you. @@ -34,6 +42,8 @@ The folks who built the app for Facebook's F8 conference in 2016 also [open-sour [Expo](https://docs.expo.io) is a development environment plus application that focuses on letting you build React Native apps in the Expo development environment, without ever touching Xcode or Android Studio. If you wish React Native was even more JavaScripty and webby, check out Expo. +The [React Developer Tools](docs/debugging.html#react-developer-tools) are great for debugging React and React Native apps. + ## Where React Native People Hang Out The [React Native Community](https://www.facebook.com/groups/react.native.community) Facebook group has thousands of developers, and it's pretty active. Come there to show off your project, or ask how other people solved similar problems. diff --git a/docs/NativeModulesIOS.md b/docs/NativeModulesIOS.md index 0c8c11c0f8f..be8d361e815 100644 --- a/docs/NativeModulesIOS.md +++ b/docs/NativeModulesIOS.md @@ -6,7 +6,7 @@ category: Guides (iOS) permalink: docs/native-modules-ios.html banner: ejected next: native-components-ios -previous: upgrading +previous: testing --- Sometimes an app needs access to platform API, and React Native doesn't have a corresponding module yet. Maybe you want to reuse some existing Objective-C, Swift or C++ code without having to reimplement it in JavaScript, or write some high performance, multi-threaded code such as for image processing, a database, or any number of advanced extensions. diff --git a/docs/Testing.md b/docs/Testing.md index db0342308f2..333bbd3e669 100644 --- a/docs/Testing.md +++ b/docs/Testing.md @@ -5,7 +5,7 @@ layout: docs category: Guides permalink: docs/testing.html next: understanding-cli -previous: upgrading +previous: contributing --- This document is about running tests on React Native itself. If you're interested in testing a React Native app, check out the [React Native Tutorial](http://facebook.github.io/jest/docs/tutorial-react-native.html) on the Jest website. diff --git a/docs/Upgrading.md b/docs/Upgrading.md index 1f6c33a85ba..cef8fc56313 100644 --- a/docs/Upgrading.md +++ b/docs/Upgrading.md @@ -4,7 +4,7 @@ title: Upgrading to new React Native versions layout: docs category: Guides permalink: docs/upgrading.html -next: testing +next: contributing previous: running-on-device --- diff --git a/website/src/react-native/js/scripts.js b/website/src/react-native/js/scripts.js index adf2deeaac1..7b8a272886d 100644 --- a/website/src/react-native/js/scripts.js +++ b/website/src/react-native/js/scripts.js @@ -226,9 +226,6 @@ var parent = hashLinks[i].parentElement; while (parent) { if (parent.tagName === 'BLOCK') { - var gettingStartedGuideType = null; - var devOS = null; - var targetPlatform = null; // Could be more than one target os and dev platform, but just choose some sort of order // of priority here.