Permalink
Browse files

Update Getting Started, Upgrading for CRNA

Summary:
Restored the version lag caveat in the Getting Started, and updated the Upgrading guide to account for CRNA.

Additionally, updated the release versions page to account for the new release cycle (e.g. release candidates are encouraged).
Closes #14112

Differential Revision: D5112224

Pulled By: hramos

fbshipit-source-id: d544c5178484c27f1ed6dee3479bcd94e5e81982
  • Loading branch information...
hramos authored and facebook-github-bot committed May 23, 2017
1 parent 9a91ea4 commit 2d1c721fd67ac41863e112a7e7d482458fdd8ada
Showing with 178 additions and 84 deletions.
  1. +2 −0 docs/GettingStarted.md
  2. +39 −38 docs/Upgrading.md
  3. +137 −46 website/src/react-native/versions.js
View
@@ -146,6 +146,8 @@ Because you don't build any native code when using Create React Native App to cr
If you know that you'll eventually need to include your own native code, Create React Native App is still a good way to get started. In that case you'll just need to "[eject](https://github.com/react-community/create-react-native-app/blob/master/react-native-scripts/template/README.md#ejecting-from-create-react-native-app)" eventually to create your own native builds. If you do eject, the "Building Projects with Native Code" instructions will be required to continue working on your project.
Create React Native App configures your project to use the most recent React Native version that is supported by the Expo client app. The Expo client app usually gains support for a given React Native version about a week after the React Native version is released as stable. You can check [this document](https://github.com/react-community/create-react-native-app/blob/master/VERSIONS.md) to find out what versions are supported.
If you're integrating React Native into an existing project, you'll want to skip Create React Native App and go directly to setting up the native build environment. Select "Building Projects with Native Code" above for instructions on configuring a native build environment for React Native.
<block class="native mac windows linux ios android" />
View
@@ -1,61 +1,66 @@
---
id: upgrading
title: Upgrading
title: Upgrading to new React Native versions
layout: docs
category: Guides
permalink: docs/upgrading.html
banner: ejected
next: native-modules-ios
previous: understanding-cli
---
Upgrading to new versions of React Native will give you access to more APIs, views, developer tools
and other goodies. Because React Native projects are essentially made up of an Android project, an
iOS project and a JavaScript project, all combined under an npm package, upgrading can be rather
tricky. But we try to make it easy for you. Here's what you need to do to upgrade from an older
version of React Native:
Upgrading to new versions of React Native will give you access to more APIs, views, developer tools and other goodies. Upgrading requires a small amount of effort, but we try to make it easy for you. The instructions are a bit different depending on whether you used `create-react-native-app` or `react-native init` to create your project.
## Upgrade based on Git
## Create React Native App projects
**IMPORTANT:** You don't have to install the new version of React Native, it will be installed automatically.
Upgrading your Create React Native App project to a new version of React Native requires updating the `react-native`, `react`, and `expo` package versions in your `package.json` file. Please refer to [this document](https://github.com/react-community/create-react-native-app/blob/master/VERSIONS.md) to find out what versions are supported. You will also need to set the correct `sdkVersion` in your `app.json` file.
The module `react-native-git-upgrade` provides a one-step operation to upgrade the source files with
a minimum of conflicts. Under the hood, it consists in 2 phases:
See the [CRNA user guide](https://github.com/react-community/create-react-native-app/blob/master/react-native-scripts/template/README.md#updating-to-new-releases) for up-to-date information about upgrading your project.
## Projects built with native code
<div class="banner-crna-ejected">
<h3>Projects with Native Code Only</h3>
<p>
This section only applies to projects made with <code>react-native init</code> or to those made with Create React Native App which have since ejected. For more information about ejecting, please see the <a href="https://github.com/react-community/create-react-native-app/blob/master/EJECTING.md" target="_blank">guide</a> on the Create React Native App repository.
</p>
</div>
Because React Native projects built with native code are essentially made up of an Android project, an iOS project, and a JavaScript project, upgrading can be rather tricky. Here's what you need to do to upgrade from an older version of React Native.
### Upgrade based on Git
The module `react-native-git-upgrade` provides a one-step operation to upgrade the source files with a minimum of conflicts. Under the hood, it consists in 2 phases:
* First, it computes a Git patch between both old and new template files,
* Then, the patch is applied on the user's sources.
### 1. Install Git
Your project doesn't have to be handled by the Git versioning system (could be Mercurial, SVN or none)
but Git has to be installed and available in the `PATH`. You can download Git here:
https://git-scm.com/downloads
> **IMPORTANT:** You don't have to install the new version of the `react-native` package, it will be installed automatically.
#### 1. Install Git
### 2. Install the `react-native-git-upgrade` module
While your project does not have to be handled by the Git versioning system -- you can use Mercurial, SVN, or nothing -- you will still need to [install Git](https://git-scm.com/downloads) on your system in order to use `react-native-git-upgrade`. Git will also need to be available in the `PATH`.
It's a CLI tool and must be installed globally:
#### 2. Install the `react-native-git-upgrade` module
The `react-native-git-upgrade` module provides a CLI and must be installed globally:
```sh
$ npm install -g react-native-git-upgrade
```
### 3. Run the command
#### 3. Run the command
Run the command to start the process:
Run the following command to start the process of upgrading to the latest version:
```sh
$ react-native-git-upgrade
# Upgrade React Native to the latest version
# Or:
$ react-native-git-upgrade X.Y.Z
# Upgrade React Native to the X.Y.Z version
```
The templates are upgraded in a optimized way. You still may encounter conflicts but only where the Git
3-way merge have failed, depending on the version and how you modified your sources.
> You may specify a React Native version by passing an argument: `react-native-git-upgrade X.Y`
### 4. Resolve the conflicts
The templates are upgraded in a optimized way. You still may encounter conflicts but only where the Git 3-way merge have failed, depending on the version and how you modified your sources.
#### 4. Resolve the conflicts
Conflicted files include delimiters which make very clear where the changes come from. For example:
@@ -84,15 +89,13 @@ Conflicted files include delimiters which make very clear where the changes come
You can think of "ours" as "your team" and "theirs" as "the React Native dev team".
## Alternative
### Alternative
Use this only in case the above didn't work.
### 1. Upgrade the `react-native` dependency
Note the latest version of the `react-native` npm package from here (or use `npm info react-native` to check):
#### 1. Upgrade the `react-native` dependency
* https://www.npmjs.com/package/react-native
Note the latest version of the `react-native` npm package [from here](https://www.npmjs.com/package/react-native) (or use `npm info react-native` to check).
Now install that version of `react-native` in your project with `npm install --save`:
@@ -108,7 +111,7 @@ $ npm install --save react@R
# where R is the new version of react from the peerDependency warning you saw
```
### 2. Upgrade your project templates
#### 2. Upgrade your project templates
The new npm package may contain updates to the files that are normally generated when you
run `react-native init`, like the iOS and the Android sub-projects.
@@ -126,10 +129,8 @@ This will check your files against the latest template and perform the following
* If there is a new file in the template, it is simply created.
* If a file in the template is identical to your file, it is skipped.
* If a file is different in your project than the template, you will be prompted; you have options
to keep your file or overwrite it with the template version.
* If a file is different in your project than the template, you will be prompted; you have options to keep your file or overwrite it with the template version.
# Manual Upgrades
## Manual Upgrades
Some upgrades require manual steps, e.g. 0.13 to 0.14, or 0.28 to 0.29. Be sure to check the [release notes](https://github.com/facebook/react-native/releases) when upgrading so that you can identify any manual changes your particular project may require.
@@ -14,7 +14,9 @@ var Site = require('Site');
module.exports = React.createClass({
render: function() {
var availableDocs = (Metadata.config.RN_AVAILABLE_DOCS_VERSIONS || '').split(',');
var availableDocs = (Metadata.config.RN_AVAILABLE_DOCS_VERSIONS ||
'')
.split(',');
var latestVersion = Metadata.config.RN_LATEST_VERSION;
var versions = [
@@ -24,22 +26,31 @@ module.exports = React.createClass({
release: null,
type: 'master',
},
].concat(availableDocs.map((version) => {
const isLatest = latestVersion === version;
const isRC = latestVersion < version;
].concat(
availableDocs.map(version => {
const isLatest = latestVersion === version;
const isRC = latestVersion < version;
var title = version;
if (isRC) {
title += '-RC';
}
var title = version;
if (isRC) {
title += '-RC';
}
return {
title: title,
path: isLatest ? '/react-native' : '/react-native/releases/' + version,
release: 'https://github.com/facebook/react-native/releases/tag/v' + version + '.0' + (isRC ? '-rc.0' : ''),
type: isLatest ? 'latest' : (isRC ? 'release-candidate' : 'release'),
};
}));
return {
title: title,
path: isLatest
? '/react-native'
: '/react-native/releases/' + version,
release: 'https://github.com/facebook/react-native/releases/tag/v' +
version +
'.0' +
(isRC ? '-rc.0' : ''),
type: isLatest
? 'latest'
: isRC ? 'release-candidate' : 'release',
};
})
);
if (!latestVersion) {
versions = [
@@ -58,76 +69,156 @@ module.exports = React.createClass({
var masters = versions.filter(function(version) {
return version.type === 'master';
});
var releaseCandidates = versions.filter(function(version) {
return version.type === 'release-candidate';
});
var releaseCandidates = versions.filter(
function(version) {
return version.type === 'release-candidate';
}
);
var releases = versions.filter(function(version) {
return version.type === 'release';
});
// Note: Our Algolia DocSearch box supports version-specific queries. If you will be drastically changing the way versions are listed in this page, make sure https://github.com/algolia/docsearch-configs/blob/master/configs/react-native-versions.json is updated accordingly.
return (
<Site section="versions" title="React Native Versions">
<section className="content wrap documentationContent nosidebar">
<Site
section="versions"
title="React Native Versions"
>
<section
className="content wrap documentationContent nosidebar"
>
<div className="inner-content">
<h1>React Native Versions</h1>
<p>React Native follows a monthly release train. Every month, a new branch created off master enters the <a href="versions.html#rc">Release Candidate</a> phase, and the previous Release Candidate branch is released and considered <a href="versions.html#latest">stable</a>.</p>
<p>
React Native follows a monthly release train. Every month, a new branch created off master enters the
{' '}
<a href="versions.html#rc">
Release Candidate
</a>
{' '}
phase, and the previous Release Candidate branch is released and considered
{' '}
<a href="versions.html#latest">stable</a>
.
</p>
<p>
If you have an existing project that uses React Native, read the release notes to learn about new features and fixes. You can follow
{' '}
<a href="/react-native/docs/upgrading.html">
our guide to upgrade your app
</a>
{' '}
to the latest version.
</p>
<a name="latest" />
<h3>Current Version (Stable)</h3>
<h3>Current version (Stable)</h3>
<table className="versions">
<tbody>
{latests.map((version) =>
{latests.map(version => (
<tr>
<th>{version.title}</th>
<td><a href={version.path}>Documentation</a></td>
<td>{version.release && <a href={version.release}>Release Notes</a>}</td>
<td>
<a href={version.path}>
Documentation
</a>
</td>
<td>
{version.release &&
<a href={version.release}>
Release Notes
</a>}
</td>
</tr>
)}
))}
</tbody>
</table>
<p>This is the version that is configured automatically when you run <code>react-native init</code>. We highly recommend using the current version of React Native when starting a new project.</p>
<p>If you have an existing project that uses React Native, read the release notes to learn about new features and fixes. You can follow <a href="/react-native/docs/upgrading.html">our guide to upgrade your app</a> to the latest version.</p>
<p>
This is the version that is configured automatically when you create a new project using
{' '}
<code>react-native init</code>
.
</p>
<a name="rc" />
<h3>Pre-release Versions</h3>
<h3>Pre-release versions</h3>
<table className="versions">
<tbody>
{masters.map((version) =>
{masters.map(version => (
<tr>
<th>master</th>
<td><a href={version.path}>Documentation</a></td>
<td>{version.release && <a href={version.release}>Release Notes</a>}</td>
<td>
<a href={version.path}>
Documentation
</a>
</td>
<td>
{version.release &&
<a href={version.release}>
Release Notes
</a>}
</td>
</tr>
)}
{releaseCandidates.map((version) =>
))}
{releaseCandidates.map(version => (
<tr>
<th>{version.title}</th>
<td><a href={version.path}>Documentation</a></td>
<td>{version.release && <a href={version.release}>Release Notes</a>}</td>
<td>
<a href={version.path}>
Documentation
</a>
</td>
<td>
{version.release &&
<a href={version.release}>
Release Notes
</a>}
</td>
</tr>
)}
))}
</tbody>
</table>
<p>For those who live on the bleeding edge. Only recommended if you're actively contributing code to React Native, or if you need to verify how your application behaves in an upcoming release.</p>
<p>
To see what changes are coming and provide better feedback to React Native contributors, use the latest release candidate 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.
</p>
<a name="archive" />
<h3>Past Versions</h3>
<h3>Past versions</h3>
<table className="versions">
<tbody>
{releases.map((version) =>
{releases.map(version => (
<tr>
<th>{version.title}</th>
<td><a href={version.path}>Documentation</a></td>
<td>{version.release && <a href={version.release}>Release Notes</a>}</td>
<td>
<a href={version.path}>
Documentation
</a>
</td>
<td>
{version.release &&
<a href={version.release}>
Release Notes
</a>}
</td>
</tr>
)}
))}
</tbody>
</table>
<p>You can find past versions of React Native <a href="https://github.com/facebook/react-native/releases">on GitHub</a>. The release notes can be useful if you would like to learn when a specific feature or fix was released.</p>
<p>You can also view the docs for a particular version of React Native by clicking on the Docs link next to the release in this page. You can come back to this page and switch the version of the docs you're reading at any time by clicking on the version number at the top of the page.</p>
<p>
You can find past versions of React Native
{' '}
<a
href="https://github.com/facebook/react-native/releases"
>
on GitHub
</a>
. The release notes can be useful if you would like to learn when a specific feature or fix was released.
</p>
<p>
You can also view the docs for a particular version of React Native by clicking on the Docs link next to the release in this page. You can come back to this page and switch the version of the docs you're reading at any time by clicking on the version number at the top of the page.
</p>
</div>
</section>
</Site>
);
}
},
});

0 comments on commit 2d1c721

Please sign in to comment.