Skip to content

Commit 2d1c721

Browse files
hramosfacebook-github-bot
hramos
authored and
facebook-github-bot
committed
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
1 parent 9a91ea4 commit 2d1c721

File tree

3 files changed

+178
-84
lines changed

3 files changed

+178
-84
lines changed

‎docs/GettingStarted.md

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -146,6 +146,8 @@ Because you don't build any native code when using Create React Native App to cr
146146

147147
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.
148148

149+
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.
150+
149151
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.
150152

151153
<block class="native mac windows linux ios android" />

‎docs/Upgrading.md

Lines changed: 39 additions & 38 deletions
Original file line numberDiff line numberDiff line change
@@ -1,61 +1,66 @@
11
---
22
id: upgrading
3-
title: Upgrading
3+
title: Upgrading to new React Native versions
44
layout: docs
55
category: Guides
66
permalink: docs/upgrading.html
7-
banner: ejected
87
next: native-modules-ios
98
previous: understanding-cli
109
---
1110

12-
Upgrading to new versions of React Native will give you access to more APIs, views, developer tools
13-
and other goodies. Because React Native projects are essentially made up of an Android project, an
14-
iOS project and a JavaScript project, all combined under an npm package, upgrading can be rather
15-
tricky. But we try to make it easy for you. Here's what you need to do to upgrade from an older
16-
version of React Native:
11+
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.
1712

18-
## Upgrade based on Git
13+
## Create React Native App projects
1914

20-
**IMPORTANT:** You don't have to install the new version of React Native, it will be installed automatically.
15+
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.
2116

22-
The module `react-native-git-upgrade` provides a one-step operation to upgrade the source files with
23-
a minimum of conflicts. Under the hood, it consists in 2 phases:
17+
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.
18+
19+
## Projects built with native code
20+
21+
<div class="banner-crna-ejected">
22+
<h3>Projects with Native Code Only</h3>
23+
<p>
24+
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.
25+
</p>
26+
</div>
27+
28+
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.
29+
30+
### Upgrade based on Git
31+
32+
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:
2433

2534
* First, it computes a Git patch between both old and new template files,
2635
* Then, the patch is applied on the user's sources.
2736

28-
### 1. Install Git
29-
Your project doesn't have to be handled by the Git versioning system (could be Mercurial, SVN or none)
30-
but Git has to be installed and available in the `PATH`. You can download Git here:
31-
https://git-scm.com/downloads
37+
> **IMPORTANT:** You don't have to install the new version of the `react-native` package, it will be installed automatically.
38+
39+
#### 1. Install Git
3240

33-
### 2. Install the `react-native-git-upgrade` module
41+
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`.
3442

35-
It's a CLI tool and must be installed globally:
43+
#### 2. Install the `react-native-git-upgrade` module
44+
45+
The `react-native-git-upgrade` module provides a CLI and must be installed globally:
3646

3747
```sh
3848
$ npm install -g react-native-git-upgrade
3949
```
4050

41-
### 3. Run the command
51+
#### 3. Run the command
4252

43-
Run the command to start the process:
53+
Run the following command to start the process of upgrading to the latest version:
4454

4555
```sh
4656
$ react-native-git-upgrade
47-
# Upgrade React Native to the latest version
48-
49-
# Or:
50-
51-
$ react-native-git-upgrade X.Y.Z
52-
# Upgrade React Native to the X.Y.Z version
5357
```
5458

55-
The templates are upgraded in a optimized way. You still may encounter conflicts but only where the Git
56-
3-way merge have failed, depending on the version and how you modified your sources.
59+
> You may specify a React Native version by passing an argument: `react-native-git-upgrade X.Y`
5760
58-
### 4. Resolve the conflicts
61+
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.
62+
63+
#### 4. Resolve the conflicts
5964

6065
Conflicted files include delimiters which make very clear where the changes come from. For example:
6166

@@ -84,15 +89,13 @@ Conflicted files include delimiters which make very clear where the changes come
8489

8590
You can think of "ours" as "your team" and "theirs" as "the React Native dev team".
8691

87-
## Alternative
92+
### Alternative
8893

8994
Use this only in case the above didn't work.
9095

91-
### 1. Upgrade the `react-native` dependency
92-
93-
Note the latest version of the `react-native` npm package from here (or use `npm info react-native` to check):
96+
#### 1. Upgrade the `react-native` dependency
9497

95-
* https://www.npmjs.com/package/react-native
98+
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).
9699

97100
Now install that version of `react-native` in your project with `npm install --save`:
98101

@@ -108,7 +111,7 @@ $ npm install --save react@R
108111
# where R is the new version of react from the peerDependency warning you saw
109112
```
110113

111-
### 2. Upgrade your project templates
114+
#### 2. Upgrade your project templates
112115

113116
The new npm package may contain updates to the files that are normally generated when you
114117
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
126129

127130
* If there is a new file in the template, it is simply created.
128131
* If a file in the template is identical to your file, it is skipped.
129-
* If a file is different in your project than the template, you will be prompted; you have options
130-
to keep your file or overwrite it with the template version.
131-
132+
* 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.
132133

133-
# Manual Upgrades
134+
## Manual Upgrades
134135

135136
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.

‎website/src/react-native/versions.js

Lines changed: 137 additions & 46 deletions
Original file line numberDiff line numberDiff line change
@@ -14,7 +14,9 @@ var Site = require('Site');
1414

1515
module.exports = React.createClass({
1616
render: function() {
17-
var availableDocs = (Metadata.config.RN_AVAILABLE_DOCS_VERSIONS || '').split(',');
17+
var availableDocs = (Metadata.config.RN_AVAILABLE_DOCS_VERSIONS ||
18+
'')
19+
.split(',');
1820
var latestVersion = Metadata.config.RN_LATEST_VERSION;
1921

2022
var versions = [
@@ -24,22 +26,31 @@ module.exports = React.createClass({
2426
release: null,
2527
type: 'master',
2628
},
27-
].concat(availableDocs.map((version) => {
28-
const isLatest = latestVersion === version;
29-
const isRC = latestVersion < version;
29+
].concat(
30+
availableDocs.map(version => {
31+
const isLatest = latestVersion === version;
32+
const isRC = latestVersion < version;
3033

31-
var title = version;
32-
if (isRC) {
33-
title += '-RC';
34-
}
34+
var title = version;
35+
if (isRC) {
36+
title += '-RC';
37+
}
3538

36-
return {
37-
title: title,
38-
path: isLatest ? '/react-native' : '/react-native/releases/' + version,
39-
release: 'https://github.com/facebook/react-native/releases/tag/v' + version + '.0' + (isRC ? '-rc.0' : ''),
40-
type: isLatest ? 'latest' : (isRC ? 'release-candidate' : 'release'),
41-
};
42-
}));
39+
return {
40+
title: title,
41+
path: isLatest
42+
? '/react-native'
43+
: '/react-native/releases/' + version,
44+
release: 'https://github.com/facebook/react-native/releases/tag/v' +
45+
version +
46+
'.0' +
47+
(isRC ? '-rc.0' : ''),
48+
type: isLatest
49+
? 'latest'
50+
: isRC ? 'release-candidate' : 'release',
51+
};
52+
})
53+
);
4354

4455
if (!latestVersion) {
4556
versions = [
@@ -58,76 +69,156 @@ module.exports = React.createClass({
5869
var masters = versions.filter(function(version) {
5970
return version.type === 'master';
6071
});
61-
var releaseCandidates = versions.filter(function(version) {
62-
return version.type === 'release-candidate';
63-
});
72+
var releaseCandidates = versions.filter(
73+
function(version) {
74+
return version.type === 'release-candidate';
75+
}
76+
);
6477
var releases = versions.filter(function(version) {
6578
return version.type === 'release';
6679
});
6780

6881
// 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.
6982

7083
return (
71-
<Site section="versions" title="React Native Versions">
72-
<section className="content wrap documentationContent nosidebar">
84+
<Site
85+
section="versions"
86+
title="React Native Versions"
87+
>
88+
<section
89+
className="content wrap documentationContent nosidebar"
90+
>
7391
<div className="inner-content">
7492
<h1>React Native Versions</h1>
75-
<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>
93+
<p>
94+
React Native follows a monthly release train. Every month, a new branch created off master enters the
95+
{' '}
96+
<a href="versions.html#rc">
97+
Release Candidate
98+
</a>
99+
{' '}
100+
phase, and the previous Release Candidate branch is released and considered
101+
{' '}
102+
<a href="versions.html#latest">stable</a>
103+
.
104+
</p>
105+
<p>
106+
If you have an existing project that uses React Native, read the release notes to learn about new features and fixes. You can follow
107+
{' '}
108+
<a href="/react-native/docs/upgrading.html">
109+
our guide to upgrade your app
110+
</a>
111+
{' '}
112+
to the latest version.
113+
</p>
76114
<a name="latest" />
77-
<h3>Current Version (Stable)</h3>
115+
<h3>Current version (Stable)</h3>
78116
<table className="versions">
79117
<tbody>
80-
{latests.map((version) =>
118+
{latests.map(version => (
81119
<tr>
82120
<th>{version.title}</th>
83-
<td><a href={version.path}>Documentation</a></td>
84-
<td>{version.release && <a href={version.release}>Release Notes</a>}</td>
121+
<td>
122+
<a href={version.path}>
123+
Documentation
124+
</a>
125+
</td>
126+
<td>
127+
{version.release &&
128+
<a href={version.release}>
129+
Release Notes
130+
</a>}
131+
</td>
85132
</tr>
86-
)}
133+
))}
87134
</tbody>
88135
</table>
89-
<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>
90-
<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>
136+
<p>
137+
This is the version that is configured automatically when you create a new project using
138+
{' '}
139+
<code>react-native init</code>
140+
.
141+
</p>
91142
<a name="rc" />
92-
<h3>Pre-release Versions</h3>
143+
<h3>Pre-release versions</h3>
93144
<table className="versions">
94145
<tbody>
95-
{masters.map((version) =>
146+
{masters.map(version => (
96147
<tr>
97148
<th>master</th>
98-
<td><a href={version.path}>Documentation</a></td>
99-
<td>{version.release && <a href={version.release}>Release Notes</a>}</td>
149+
<td>
150+
<a href={version.path}>
151+
Documentation
152+
</a>
153+
</td>
154+
<td>
155+
{version.release &&
156+
<a href={version.release}>
157+
Release Notes
158+
</a>}
159+
</td>
100160
</tr>
101-
)}
102-
{releaseCandidates.map((version) =>
161+
))}
162+
{releaseCandidates.map(version => (
103163
<tr>
104164
<th>{version.title}</th>
105-
<td><a href={version.path}>Documentation</a></td>
106-
<td>{version.release && <a href={version.release}>Release Notes</a>}</td>
165+
<td>
166+
<a href={version.path}>
167+
Documentation
168+
</a>
169+
</td>
170+
<td>
171+
{version.release &&
172+
<a href={version.release}>
173+
Release Notes
174+
</a>}
175+
</td>
107176
</tr>
108-
)}
177+
))}
109178
</tbody>
110179
</table>
111-
<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>
180+
<p>
181+
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.
182+
</p>
112183

113184
<a name="archive" />
114-
<h3>Past Versions</h3>
185+
<h3>Past versions</h3>
115186
<table className="versions">
116187
<tbody>
117-
{releases.map((version) =>
188+
{releases.map(version => (
118189
<tr>
119190
<th>{version.title}</th>
120-
<td><a href={version.path}>Documentation</a></td>
121-
<td>{version.release && <a href={version.release}>Release Notes</a>}</td>
191+
<td>
192+
<a href={version.path}>
193+
Documentation
194+
</a>
195+
</td>
196+
<td>
197+
{version.release &&
198+
<a href={version.release}>
199+
Release Notes
200+
</a>}
201+
</td>
122202
</tr>
123-
)}
203+
))}
124204
</tbody>
125205
</table>
126-
<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>
127-
<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>
206+
<p>
207+
You can find past versions of React Native
208+
{' '}
209+
<a
210+
href="https://github.com/facebook/react-native/releases"
211+
>
212+
on GitHub
213+
</a>
214+
. The release notes can be useful if you would like to learn when a specific feature or fix was released.
215+
</p>
216+
<p>
217+
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.
218+
</p>
128219
</div>
129220
</section>
130221
</Site>
131222
);
132-
}
223+
},
133224
});

0 commit comments

Comments
 (0)