Upgrade guide for Dojo 2.0

[kitsonk]

@paulrutter commented on Wed Oct 26 2016

Although Dojo 2.0 not being ready yet, the dojo roadmap looks very promising! Glad to see that our framework of choice a few years ago is still evolving (a year back, we were biting our nails if Dojo 2.0 would ever see the light of day!) and nearing completion.

In order for us to prepare for a possible upgrade to Dojo 2.0, it would be quite handy if there would be an upgrade/migration guide on how to proceed/prepare!

I've found this migration guide, but it looks as if this is very old and doesn't reflect the (massive) changes made to the dojo core in 2.0.

We're on Dojo 1.11.1 now and would like to make an estimate on how much work it would be to upgrade to 2.0. I'm hoping that it's somewhat backwards compatible, but looking at all the new packages i'm guessing that this is not the case. Please correct me if i'm wrong :)

Keep up the good work and thanks in advance!

---

@kitsonk commented on Wed Oct 26 2016

We have had someone recently join the team who is going to be responsible for documentation, including "how to" and "migration" guides.

The answer is going to be largely a very nuanced question though. The migration guide you mention was when we were considering having Dojo 2 be largely a "de-crufted" version of Dojo 1. We made the decision, that with all the changes in JavaScript, the adoption of TypeScript, and the rise of new models of application development, that we needed to build something "from scratch" and not worry initially about migration.

If what you are exclusively using is the dojo package, and you want to migrate to Dojo 2, largely it will essentially be a re-write. Dojo 2 really tries to fully embrace ES6+ and leverage TypeScript to be able to write in a modern syntax. TypeScript doesn't provide functional features we have created dojo-shim to provide that functionality.

We already have users of Dojo 1 making this migration easier by first migrating their code TypeScript. We have dojo/typings which can provide the type information to TypeScript and are still working closely with the TypeScript team to hopefully get that published as part of the mainstream type libraries.

For widgets, Dojo 2 is built around a virtual DOM and the widget system is substantially different to Dijit. We think these have huge benefits, but we realise there is a large user base for Dijit and custom widgets built with Dijit. In that sense, we have already proven that we can "wrap" Dijits and place them into the Dojo 2 virtual DOM. While this won't provide the "best" performance, our experiments so far have shown that it is likely to work in most use cases. This gives you the time to start to migrate your code and widgets without feeling like you have to refactor everything at once to gain any benefits. We hope that new widgeting system will be easy enough to use that re-implimenting custom widgets will be significantly easier than in Dojo 1.

One of the things that Dojo 1 didn't have a simple clear concept of was the wider "application framework". While there were a couple different attempts in dojox none of them were a fully robust model. That is one of the things that is a major part of Dojo 2 though. So depending on how you actually structured your "application" and if you desire to leverage the Dojo 2 application framework, there will be additional work.

Our main work at the moment is focused on getting to a quality beta over the next couple of months. We also expect to have with that beta enough to documentation and "how to" guides to enable you (and others) to properly assess what it would take to move to Dojo 2, but also help guide you in properly sizing the effort.

Another things of note, one of the things we didn't fully succeed at with Dojo 1 was making it super easy to get started. This is where the dojo/cli-* packages come in. We want to give you a single tool (dojo) that allows you to scaffold and build production ready apps. While you can totally use your own toolchain to build Dojo 2, we know that it is a big limit that if you are trying to assess something, that you have to spend days trying to figure out how to get everything setup to just get "Hello World" in a browser. So we really want to make that easy for you.

We are really huge fans of TypeScript. It has really helped us ensure that Dojo 2 is quality, but also, because of the increased ability to express the intent of an API, we think the code we are producing is far more easy for other developers to consume without having to ready tons of documentation and scratch their heads.

So in summary, I would consider the following at this point:

• Consider what adopting TypeScript now for your existing Dojo 1 code bases would be.
• Become familiar with the packages under development
• Wait for the beta to take it out for a "test spin" and do the detailed planning of adopting Dojo 2
• Target the RC as the earliest that you would likely be comfortable fully converting over for production

---

@kitsonk commented on Wed Oct 26 2016

cc/ @ckirby-sitepen - He is the person who has joined the team who will be looking after our documentation, etc. and I think he is very much welcoming input in what people's needs are.

---

@ckirby-sitepen commented on Wed Oct 26 2016

Greetings, Paul, and thank you very much for sharing your thoughts on how we can improve Dojo2 for you. Documenting a migration path is already on my to-do list. If you have anything specific you'd like to see in it, please let me know and I'll be sure to include it.

---

@paulrutter commented on Thu Oct 27 2016

Thanks all for your swift response! Glad to hear that a migration guide is on the todo list.
Although i understand the reasons for a complete rewrite of dojo, i'm not very happy with the idea of rewriting our 100k+ (500+ widgets) line codebase. That would mean that looking into newer frameworks/tools again might also be a viable option.

Don't get me wrong; i do like the ideas and concept of dojo needing to be easier, but i'm not sure i will be able to convince my superior of the need to rewrite almost our whole codebase. Food for thought though :-)

In detail: we're using dojo, dijit and dojox (to some extent). My biggest concern would be how we can migrate our custom widgets (extending _WidgetBase and _TemplatedMixin) to dojo 2.0. Besides important stores (extending JsonRest), that's the majority of our codebase.

I will respond with more information soon, my phone is not the best device for a long story.

---

@dylans commented on Wed Oct 26 2016

@paulrutter for what it's worth, we'll continue to support Dojo 1.x as long as people are using it (so likely for several years), and as @kitsonk alluded to, there's a fairly strong co-existence strategy so there's really no need to rewrite everything at once (or in some cases, ever, if you choose).

With Dojo, one of our primary goals is longevity, and this is really our first major rewrite in nearly 10 years. With the changes brought by ES6 and TS, it was time for us. These changes unfortunately make it really difficult to provide a tool to update things, as it's often not as easy as switching the syntax, but rethinking how to create applications.

Regardless, we'll do everything we can within reason to help.

---

@paulrutter commented on Thu Oct 27 2016

Good to know that Dojo 1.x is still going to be maintained over the next years, that indeed makes it less important to migrate all code at once. It does make the hybrid solution (wrapping Dojo 1.x widgets in 2.0) @kitsonk is talking about very interesting, as that would probably enable us to migrate to 2.0 gradually.
@ckirby-sitepen I would be very interested in a how-to/code example about this!
I can image a situation where we would migrate the code managing (the state of) the application to 2.0, but still use old school 1.x widgets where needed.

@dylans I do understand that at some point you will want to break backwards compatibility. The current Dojo version indeed supports too much deprecated browsers (< IE10 afaik) and therefore cannot use the latest ES6 features, which would be quite beneficial.

@kitsonk i would suggest removing the current migration guide, as it clearly misinforms about the whole migration topic. Do you agree?

---

@ckirby-sitepen commented on Thu Oct 27 2016

@paulrutter Can do, Paul.

---

@dylans commented on Wed Dec 21 2016

Separate issue opened at dojo/dojo-website#26 for renaming the existing migration guide to make it clear that those guides are not a clear Dojo 2 migration path.

[kitsonk]

Moved this here, as any tutorials or guides should consider this.

[paulrutter]

For future reference: the tutorial can be found here: https://dojo.io/tutorials/1040_dojo1_dijits.
Thanks guys, will do a PoC soon to embed our Dojo 1 app in a Dojo 2 app.

[paulrutter]

I just tried the tutorial and it failed on the "dojo build" command on Windows.
I had to add some browserlist configuration to the package.json to make it work.

  "browserslist": [
    "> 1%",
    "last 2 versions"
  ],

Might be worth taking into account in the example?
The tutorial is working otherwise. Now i'm going to try to integrate our Dojo1 app into this.