Migrating from JET v2.0 to v4.1 — A painful road, Part 1
I wanted to wrap this all up in one post, but turns out it is more complicated than I thought. This post thus only explains the pitfalls when upgrading from v2.0 to v2.3, and one or two separate posts will treat upgrading to v3 and v4, respectively.
v2.0 to v2.3
For some reason, you can only upgrade to v3 if you are at v2.3, so the first step is to upgrade the <v2.3 application to v2.3. Thankfully, there is a migration guide available. Just follow the steps from that guide, and refer to my following notes for each step (if any) for more information. I did the migration for our internal Travelcost application, so if you encounter this name, substitute it for your own apps name.
- Step 1: When running
npm cache cleanyou get an error as pictured below if you are on npm v5. Just ignore it and move on, npm got smarter since the migration guide was written.
- Step 3: To keep everything nice and clean, move your v2.0 application to a *_v2–0 folder before you run the generator. Then generate the v2.3 application under your application name, as we will be moving our existing source files into the newly generated v2.3 application (weird, but whatever…).
- After step 3: If you take your application seriously, you have it under version control. This is a good point in the upgrade process to do so for the new v2.3 application. Just
git add .everything and commit it and don’t worry about files that you may not need in your final v2.3 app — you can tidy up everything later. Commit your work at least after the migration is completed, possibly even more often.
- After step 8: The migration guide assumes you do not have any custom Grunt scripts. In our case we have scripts for running ESLint and Karma tests — obviously, copy them over to the v2.3 application as well. Same goes for additional config files, like a
karma.conf.js. If you have custom Grunt scripts, you probably also have edited your Gruntfile, so copy the relevant lines over to your new Gruntfile as well.
- I had some troubles with the oraclejet bower package not being installed in the correct version. This is probably an issue with the npm cache and may or may not occur anymore in npm v5. To make sure you have the correct version, run
cat bower_components/oraclejet/bower.jsonand verify that the version is
- The guide also forgets to mention that you should edit the
bowercopy.jsfile if you have any additional Bower dependencies, like fontawesome for example. Manually copy the relevant stuff from your old
bowercopy.js— hopefully only a few lines at the end of the file.
That’s it! Check if all works by running
grunt build and then
grunt serve ! Also make sure all your tests are still passing — if you have any, which I sure hope you do ;)
As the last step, you want to merge your changes into the main codebase. If you just wanted to upgrade to v2.3, you can just merge into master. If you plan to continue down the road to v4.1, just merge your master branch into the update-branch (in my case ‘upgrade_v2.3') to make sure everything is in the right place and then continue the migration. Git may refuse to merge unrelated histories, but a wise man on Stackoverflow says you can use the
--allow-unrelated-histories flag when doing the merge to force the merge (which indeed works as expected, at least for me).
Let’s hope moving from v2.3 to v3 will be easier, but as v3 gets rid of Bower, it is bound to get interesting again! I plan to publish that post later this week.