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

Jump to bottom

Add upgrade-helper as an upgrading option #1063

Merged
merged 3 commits into from Jul 2, 2019
Merged

Add upgrade-helper as an upgrading option #1063

Changes from 1 commit
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
74e3c49
Add `upgrade-helper` mention and rearrange content to `upgrading` page
lucasbento Jun 27, 2019
374d978
Use correct react-native CLI repository URL
lucasbento Jul 2, 2019
924b3b4
Change `upgrade` section
lucasbento Jul 2, 2019
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
81 changes: 41 additions & 40 deletions website/versioned_docs/version-0.5/upgrading.md
View file
Open in desktop
Expand Up @@ -14,27 +14,17 @@ See the [Upgrading Expo SDK Walkthrough](https://docs.expo.io/versions/latest/wo

## React Native projects

Because typical React Native projects 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.
Because typical React Native projects are essentially made up of an Android project, an iOS project, and a JavaScript project, upgrading can be rather tricky. There's currently two ways for upgrading your React Native project: by using [React Native CLI](https://github.com/react-native-community/react-native-cli) or manually with [Upgrade Helper](https://github.com/react-native-community/upgrade-helper).
lucasbento marked this conversation as resolved.
Show resolved Hide resolved

### Upgrade based on Git
### React Native CLI

The [React Native CLI](https://github.com/react-native-community/react-native-cli) comes with `upgrade` command that provides a one-step operation to upgrade the source files with a minimum of conflicts, thanks to the [rn-diff-purge](https://github.com/react-native-community/rn-diff-purge) project.
The [React Native CLI](https://github.com/react-native-community/react-native-cli) comes with `upgrade` command that provides a one-step operation to upgrade the source files with a minimum of conflicts, it internally uses [rn-diff-purge](https://github.com/react-native-community/rn-diff-purge) project to find out which files need to be created, removed or modified.
lucasbento marked this conversation as resolved.
Show resolved Hide resolved

#### 1. Make sure your project uses Git
#### Upgrade based on Git
lucasbento marked this conversation as resolved.
Show resolved Hide resolved

> This step applies only to projects that don't use Git. Skip it if yours use it.
The `upgrade` command works on top of Git by using `git apply` with 3-way merge, therefore it's required to use Git in order for this to work, if you don't use Git but still want to use this solution then you can check out how to do it in the [Troubleshooting](#i-want-to-upgrade-with-react-native-cli-but-i-don-t-use-git) section.
lucasbento marked this conversation as resolved.
Show resolved Hide resolved

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 upgrade`. Git will also need to be available in the `PATH`. If your project doesn't use Git, initialize it and commit:

```sh
git init
git add .
git commit -m "upgrade RN"
```

After the upgrade is done and conflicts resolved, you can remove the `.git` directory.

#### 2. Run the `upgrade` command
##### 1. Run the `upgrade` command
lucasbento marked this conversation as resolved.
Show resolved Hide resolved

Run the following command to start the process of upgrading to the latest version:

Expand All @@ -48,9 +38,9 @@ You may specify a React Native version by passing an argument, e.g. to upgrade t
react-native upgrade 0.59.0-rc.0
```

The project is upgraded using `git apply` with 3-way merge. That's why it may happen you'll need to resolve some conflicts.
The project is upgraded using `git apply` with 3-way merge, it may happen that you'll need to resolve a few conflicts after it's finished.

#### 4. Resolve the conflicts
#### 2. Resolve the conflicts

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

Expand All @@ -77,41 +67,36 @@ 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".
You can think of "ours" as "your team" and "theirs" as "the React Native development team".

### Alternative
### Upgrade Helper

Use this only in case the above didn't work.
The [Upgrade Helper](https://react-native-community.github.io/upgrade-helper/) is a web tool to help you out when upgrading your apps by providing the full set of changes happening between any two versions. It also shows comments on specific files to help understanding why that change is needed.

#### 1. Upgrade the `react-native` dependency
#### 1. Select the versions

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).
You first need to select from and to which version you wish to upgrade, by default the latest major versions are selected. After selecting you can click the button "Show me how to upgrade".

Now install that version of `react-native` in your project with `npm install --save`:
💡 Major updates will show an "useful content" section on the top with links to help you out when upgrading.

```sh
$ npm install --save react-native@X.Y
# where X.Y is the semantic version you are upgrading to
npm WARN peerDependencies The peer dependency react@~R included from react-native...
```
#### 2. Upgrade dependencies

If you saw a warning about the peerDependency, also upgrade `react` by running:
The first file that is shown is the `package.json`, it's good to update the dependencies that are showing in there. For example, if `react-native` and `react` appears as changes then you can install it in your project by running `yarn add`:

```sh
$ npm install --save react@R
# where R is the new version of react from the peerDependency warning you saw
# {{VERSION}} and {{REACT_VERSION}} are the release versions showing in the diff
yarn add react-native@{{VERSION}}
yarn add react@{{REACT_VERSION}}
```

#### 2. Upgrade your project templates
#### 3. Upgrade your project files

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.
The new release may contain updates to other files that are generated when you run `react-native init`, those files are listed after the `package.json` in the Upgrade Helper page. If there aren't other changes then you can just rebuild the project and continue developing.

You may consult [rn-diff-purge](https://github.com/pvinis/rn-diff-purge) to see if there were changes in the project template files. In case there weren't any, simply rebuild the project and continue developing. In case of minor changes, you may update your project manually and rebuild.

If there were major changes, run this in a terminal to get these:
In case there are changes then you can either update them manually by copying and pasting from the changes in the page or you can do it with the React Native CLI upgrade command by running:

```sh
$ react-native upgrade
react-native upgrade
```

This will check your files against the latest template and perform the following:
Expand All @@ -120,6 +105,22 @@ This will check your files against the latest template and perform the following
- 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.

## Manual Upgrades
> Some upgrades won't be done automatically with the React Native CLI and require manual work, e.g. `0.28` to `0.29`, or `0.56` to `0.57`. Make 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.

### Troubleshooting

#### I want to upgrade with React Native CLI but I don't use Git

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 upgrade`. Git will also need to be available in the `PATH`. If your project doesn't use Git, initialize it and commit:

```sh
git init # Initialize a Git repository
git add . # Stage all the current files
git commit -m "Upgrade react-native" # Save the current files in a commit
```

After you finish upgrading you may remove the `.git` directory.

#### I have done all the changes but my app is still using an old version

Some upgrades require manual steps, e.g. 0.28 to 0.29, or 0.56 to 0.57. 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.
These sort of errors are usually related to caching, it's recommended to install [react-native-clean-project](https://github.com/pmadruga/react-native-clean-project) to clear all your project's cache and then you can run it again.