Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[Docs] Update Getting Started, Upgrading for CRNA #14112

Closed
wants to merge 2 commits into from
Closed

[Docs] Update Getting Started, Upgrading for CRNA #14112

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
7d5c65c
Add version lag caveat
hramos May 22, 2017
f3e5d61
Add CRNA/native notes to Upgrading guide
hramos May 22, 2017
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions docs/GettingStarted.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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" />
Expand Down
77 changes: 39 additions & 38 deletions docs/Upgrading.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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:

Expand Down Expand Up @@ -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`:

Expand All @@ -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.
Expand All @@ -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.
183 changes: 137 additions & 46 deletions website/src/react-native/versions.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,9 @@ var Site = require('Site');

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

My editor automatically ran Prettier on this page, which explains all the non-copy changes.

Happy to undo these if necessary.

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 = [
Expand All @@ -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 = [
Expand All @@ -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>
);
}
},
});