Upgrade scaffold

This document provides the steps for upgrading your React Native scaffold to the latest version.

Prerequisites

Set up

Make sure that you have performed all the steps in Set up your developer environment. You should have the following installed and configured.

Install cookiecutter

cookiecutter is a package used exclusively by the cb upgrade CLI command. If you have any questions or issues, refer to the cookiecutter documentation.

To determine if you have cookiecutter or to verify installation, run:
cookiecutter --version
If cookiecutter is installed, the response will include the cookiecutter version. 

If it is not installed, use one of the following to install it:

• pip: python3 -m pip install --user cookiecutter

• Pipx: pipx install cookiecutter

• Homebrew (macOS X only): brew install cookiecutter

Check your scaffold version

If you are not sure of the scaffold version of your app, open the crowdbotics.json file.  The scaffold version is listed there.

Perform the upgrade

1. Create a new branch.

2. Run the following:

   cd your-repo-dir
   git checkout -b upgrade-scaffold
   cb upgrade

3. Use the arrow keys to select Upgrade my scaffold.

   ? What do you want to do? (Use arrow keys)
   ❯ Upgrade my scaffold
     Undo all changes
     Remove all diff files
     Clear local cache (debug)
     Quit

Important

Do not commit the changes until you have reviewed the files with upgrade issues!

Reviewing the results

As the upgrade is processing, you see the results of the upgrade on each file.

• Any line (file) with a green checkbox icon (✅) processed successfully.

• Any file that did not automatically upgrade is identified with a yellow warning icon (⚠️) and the failure reason is provided, for example:

⚠️ package.json — Failed integrity check. Refer to the new version package.new.json and its corresponding .diff file.

For each file that was not automatically upgraded, we provide two new files in addition to the original file. For example, for package.json, there are now three files.

• package.json — the version as it was before the upgrade

• package.new.json — the file as it will look after the upgrade

• package.json.diff — A diff file showing the difference between:

  • the version of the file at the initial commit/creation

  • the package.new.json file

Making changes

1. As you go through the .diff file, review the changes and differences to determine which changes you want to maintain.
   The Example section below explains the .diff file contents.

2. Make your changes in the new. file. (e.g., package.new.json)

3. When you have completed the review and made all the changes in the new. file, replace the original file (e.g., package.json) with the new. file (e.g., package.new.json).

4. Move on to the next .diff file, until you cover all of them.

5. (Optional) Use the Remove all diff files command to if you prefer not to delete each one individually.

6. (Optional) If, at any point, you want to revert all the changes since you ran the Upgrade my scaffold command, run the command again and choose Undo all changes.

7. After you have resolved all issues, git add/commit and push to the remote.

8. Open a Pull Request for the branch you just pushed and ask your teammates for a review.

Your scaffold is now upgraded to the latest version.

Example

The following is an example of the package.json.diff file for package.json.

# File: /your-repo/package.json
# Original: /your-repo/build/crowdbotics/build/v1/your-repo/package.json
#
# This is a git diff between your local version of the file and the scaffold
# original. Go over all the changes displayed here and consider which ones
# you would like to bring to the new version of this file:
# package.new.json.
#
# When you finish replace your package.json with package.new.json.

diff --git a/your-repo/package.json b/your-repo/package.json
index fea5ce4..30580d7 100644
--- a/your-repo/build/crowdbotics/build/v1/your-repo/package.json
+++ b/your-repo/package.json
@@ -12,44 +12,45 @@
     "web:build": "./node_modules/.bin/webpack --config ./webpack.config.js --color --mode production"
   },
   "dependencies": {
-    "react": "17.0.1",
-    "react-native": "0.64.4",
-    "axios": "^0.21.1",
+    "@modules/articles": "file:./modules/articles/",
     "@react-native-community/masked-view": "^0.1.10",
     "@react-navigation/native": "^5.9.3",
-    "react-native-gesture-handler": "^1.10.3",
-    "react-native-reanimated": "~2.4.1",
-    "react-native-safe-area-context": "^3.2.0",
-    "react-native-screens": "^2.18.1",
     "@react-navigation/stack": "^5.14.3",
-    "redux": "^4.0.5",
-    "react-redux": "^7.2.2",
     "@reduxjs/toolkit": "^1.5.0",
+    "axios": "^0.21.1",
+    "react": "17.0.1",
+    "react-dom": "^17.0.0",
+    "react-native": "0.64.4",
     "react-native-dotenv": "^2.5.3",
-    "react-native-responsive-screen": "^1.4.2",
     "react-native-elements": "^3.3.1",
-    "react-native-vector-icons": "^8.1.0",
-    "react-dom": "^17.0.0",
+    "react-native-gesture-handler": "^1.10.3",
     "react-native-radio-buttons-group": "^2.2.11",
-    "react-native-web": "^0.18.2"
+    "react-native-reanimated": "~2.4.1",
+    "react-native-responsive-screen": "^1.4.2",
+    "react-native-safe-area-context": "^3.2.0",
+    "react-native-screens": "^2.18.1",
+    "react-native-vector-icons": "^8.1.0",
+    "react-native-web": "^0.18.2",
+    "react-redux": "^7.2.2",
+    "redux": "^4.0.5"
   },
   "devDependencies": {
     "@babel/core": "^7.12.9",
     "@babel/runtime": "^7.12.5",
     "@react-native-community/eslint-config": "^2.0.0",
     "babel-jest": "^26.6.3",
+    "babel-loader": "^8.2.5",
+    "babel-plugin-import-glob-meta": "github:crowdbotics/babel-plugin-import-glob-meta",
+    "babel-plugin-react-native-web": "^0.18.2",
     "eslint": "7.14.0",
+    "html-webpack-plugin": "^5.5.0",
     "jest": "^26.6.3",
     "metro-react-native-babel-preset": "^0.64.0",
     "react-test-renderer": "17.0.1",
-    "babel-plugin-import-glob-meta": "github:crowdbotics/babel-plugin-import-glob-meta",
-    "babel-loader": "^8.2.5",
     "url-loader": "^4.1.1",
     "webpack": "^5.73.0",
     "webpack-cli": "^4.10.0",
-    "webpack-dev-server": "^4.9.3",
-    "babel-plugin-react-native-web": "^0.18.2",
-    "html-webpack-plugin": "^5.5.0"
+    "webpack-dev-server": "^4.9.3"
   },
   "jest": {
     "preset": "react-native"
@@ -66,4 +67,4 @@
       "last 1 safari version"
     ]
   }
-}
\\\\ No newline at end of file
+}

The diff shows us that the file diverged from the original version, more specifically one dependency got added. (The other diffs here are only lines reordering.)

+    "@modules/articles": "file:./modules/articles/",

This means that we have to add the same dependency to package.new.json and replace the old file.

mv package.new.json package.json
yarn add file:./modules/articles
git add package.json yarn.lock