Disgusting surprise v7

[edwinspire]

Complain

Package Version: 7.0.0
I have followed the Dojo project for many years. I always loved the way I could develop quickly and with a widget structure that I fell in love with from the first moment.

The change to Dojo2 was a hard step, but highly anticipated, I appreciate the effort of the team of developers and collaborators.

My discomfort arises from Dojo2 and its change of versions, they break my code, very often. I did not dislike it since my developments were made for passion and entertainment or for personal development.

From version 6 I decided to go a step further and start with developments for clients already with Dojo2.

In a project already 90% advanced, I had the bad idea to update to version 7 recently released and everything broke.

In the new version things no longer work as before, some widgets have been removed and some that are still no longer work as before.

It is very serious that widgets are removed, this should not be the case, they should be improved and maintained so that there is compatibility with new versions.

From previous versions of Dojo what helped me the most was working with widgets instantiating their classes. Now all the examples are in tsx, there is not a single example that tells me how to work with widgets as classes, I mean those of version 7, until version 6 it had been working without problems.

I hope they take into account my humble opinion, someone who is very fond of the project tells them and for years I have refused to leave it or exchange it for other frameworks, because I think I am a fanboy.

Kind regards and blessings from Ecuador.

[matt-gadd]

Hi @edwinspire, I'm really sorry that you have had difficulties in upgrading to Dojo 7. In versions prior to this we have tried our absolute best to provide as painless of an upgrade path as possible. The pattern for this has been by making mostly small additive breaking changes, and the rest being mostly automated by the Dojo upgrade tool here: https://github.com/dojo/cli-upgrade-app.

With Dojo 7 however, we had to make some fundamental changes to widgets that simply weren't possible without making major breaking changes. In fact some of them fully relied on breaking the API's to make them simpler, and others more subtle in terms of improving the out of the box behaviour. Knowing this, the widgets team have put a great amount of work into the migration guide here https://github.com/dojo/widgets/blob/master/docs/V7-Migration-Guide.md, which illustrates how to individually migrate each widget from v6 to v7.

I understand that not everyone has the capacity to upgrade to Dojo 7 and Dojo 7's widgets immediately. If Dojo 6's widgets are working for you then that's great, and you should be able to still use those with Dojo Framework v7 if you wish (@agubler has put together an example here: https://github.com/agubler/dojo-7-interop-dojo-6-widgets)

some widgets have been removed and some that are still no longer work as before.

As far as i'm aware we didn't remove any widgets in Dojo 7 (we actually added lots 😄), but we did rename some widgets for consistency purposes. Can you let us know which have been removed?

From previous versions of Dojo what helped me the most was working with widgets instantiating their classes. Now all the examples are in tsx, there is not a single example that tells me how to work with widgets as classes, I mean those of version 7, until version 6 it had been working without problems.

This is a good point, and I raised an issue a while back (dojo/site#191) to make sure we can support viewing examples in both tsx and v()/w() in the documentation. This is something we hope to be able to add to the documentation tool soon.

The Dojo team do want to make it clear again this was an outlier of a release in terms of breaking changes and that this is not the new norm, and we appreciate your frustration in upgrading. We do feel like the changes we have made are the right ones though, and we now have a widget suite that is more capable than ever, and easier to use out of the box.

If you do have any specific issues while migrating to v7 please do let us know, and we will try to assist as much as possible.

[dylans]

I will add one more thing, which is one of the reasons Dojo 1.x's popularity started to die off is that we really never made breaking changes, but just kept adding to the project. This resulted in us having such a large codebase that it's difficult to accurately test everything when making even small changes.

By having a process where we can normally introduce smaller breaking changes and provide tools to help upgrade (something that was not really possible in the days of Dojo 1.x), we're able to continue iterating on Dojo to help it stay competitive.

As @matt-gadd noted, the changes in v7 were larger than we would normally like, and hopefully we won't have as much churn and change between releases going forward.

[edwinspire]

Best regards. Thank you for taking the time to respond, it is very important and appreciated by me.

One of the widgets I was using was https://github.com/dojo/widgets/tree/v6.2.1/src/toolbar, now it is no longer available in version 7 and I don't see one that works similarly, @ dojo / widgets / header is not a good option.

I am going to review the links that indicated me to migrate my code, if I have news I will be commenting.

[raggedgenes]

I think SplitPane has been removed or just I could not find it?
Bests,
Sz

[bitranch]

I'm afraid I have to agree with the meta-issues the OP brings up, including the "disgusting surprise" title. V7 is a huge pain point to those of us with an existing Dojo 6 code base. I personally view it as bordering on a disaster for us having any ability to move forward since we have a rather massive code base that has about 50 sites running on it. There are so many widespread and subtle changes that upgrading to V7 is almost equivalent to switching to a different library.

But the real issue is that Dojo has slipped further and further from involving and informing the community. The shift from v1 to v2 had constantly updated roadmaps, requested input from the community, explained why decisions were made, and tried to bring existing Dojo users along. Even when I didn't have input on changes, I at least felt I knew why those changes were made and how they would affect my code.

From my outside viewpoint, Dojo has since moved to a narrower and narrower set of people involved. It has started to look like an internal company project that drops new versions with no regard to the community.

Example: The roadmap hasn't been updated for a year. That's a full version with no public roadmap. So there's no place that says "this is where we're thinking of taking Dojo" little less why Dojo should go that direction. And that means there's no way to give early input on planned changes.

Example: You tell us these changes are all necessary, but you don't really say why they're necessary beyond some hand-waving. (Like "easier to use out of the box." Easier for who? Definitely not easier for existing Dojo v6 users who have to rewrite and possibly re-think their code to take advantage of that "easier".)

Example: The doc switch to tsx that gives no priority to existing users. All of the migration examples use tsx. Most of the documentation is tsx. So those of us using vdom calls (v()/w ()) have no documentation for API changes outside of manually translating tsx, which is error-prone at the very least. If you thought of Dojo updates in terms of existing users, adding vdom API call doc would be one of the top priorities before rolling out V7. That "raised an issue a while back" should have been a blocking issue for v7, not something you "hope to add soon." (As it stands, my developers have nearly zero use for the current Dojo documentation.)

I've been using Dojo for a long time. I've never seen the project go so completely off the rails as it has with this release. For the first time in 12 years I have no idea where Dojo is going or why changes were made in the last version. Without that knowledge, much of v7 appears to be random changes for the sake of change. There's no deprecation warnings, no allowance for a phased migration, just whack-change, new-replaces-old. I have no idea what problems you thought you were solving, just reassurances that these changes make everything somehow better.

"Staying competitive" includes the care-and-feeding of existing users. When you throw that out, no matter how much cool and current tech you throw at Dojo, you have failed.

[dylans]

Hi @bitranch , comments inline.

I'm afraid I have to agree with the meta-issues the OP brings up, including the "disgusting surprise" title. V7 is a huge pain point to those of us with an existing Dojo 6 code base. I personally view it as bordering on a disaster for us having any ability to move forward since we have a rather massive code base that has about 50 sites running on it. There are so many widespread and subtle changes that upgrading to V7 is almost equivalent to switching to a different library.

I agree that v7 was the biggest set of changes since v2, though to be fair it was also the longest release cycle. This release was in general intended to address a lot of feedback and well documented feedback received from the team in areas where it was challenging to work with Dojo widgets, as well as a shift to make it easier to support other theme approaches like Material.

I'm assuming you've read through the separate Dojo 7 widgets blog post which I feel does explain some of the previous pain and why things were overcome. Similarly the Dojo widgets v7 migration guide updates illustrate a lot of the inconsistent pain points that we attempted to smooth out.

But the real issue is that Dojo has slipped further and further from involving and informing the community. The shift from v1 to v2 had constantly updated roadmaps, requested input from the community, explained why decisions were made, and tried to bring existing Dojo users along. Even when I didn't have input on changes, I at least felt I knew why those changes were made and how they would affect my code.

To be far, part of that is that it took us 8 years from when we first started talking about v2 to eventually shipping it, so we communicated a lot. :)

That said, I feel like all of the significant changes were communicated through issues in their respective repos that were open for quite a while. One issue that is admittedly not fully updated with the release, but that communicated many of these decisions as far back as September, 2019 is #780 . Similarly we started out the v7 frameworks effort with dojo/framework#530. Over time this ends up as many smaller issues as we get into the details, but there was clear effort to discuss these things starting 9 months ago. By the end of the release there were hundreds of issues open and detailed for every small change in widgets and framework.

What can we do better to raise awareness for all of this? It's really unfortunate as we received very little feedback until after the release.

From my outside viewpoint, Dojo has since moved to a narrower and narrower set of people involved. It has started to look like an internal company project that drops new versions with no regard to the community.

I agree that the core committer community has not grown as much as we had hoped by thisi time, but I disagree with the internal company project stuff as I think we've actually gotten better about opening issues in GitHub for everything we are doing.

Example: The roadmap hasn't been updated for a year. That's a full version with no public roadmap. So there's no place that says "this is where we're thinking of taking Dojo" little less why Dojo should go that direction. And that means there's no way to give early input on planned changes.

I agree that this has not been great, but it's mostly a function of not maintaining the information in multiple places (I used to manually do this, but I've not had as much time lately and most of my personal efforts have been focused on reviewing all of the documentation for clarity).

We can at least put an effort towards updating the website roadmap, but we also would definitely appreciate help at least being reminded in case we forget. What else can we do? Is there anything you would like to help us with here?

Example: You tell us these changes are all necessary, but you don't really say why they're necessary beyond some hand-waving. (Like "easier to use out of the box." Easier for who? Definitely not easier for existing Dojo v6 users who have to rewrite and possibly re-think their code to take advantage of that "easier".)

If you take all of the information from the various tickets and issues and migration guide and blogs you'd have a few hundred page document which no one would read.

I think the information is explained in more depth in the widgets blog post, then in the migration guide, and finally in the related tickets.

Example: The doc switch to tsx that gives no priority to existing users. All of the migration examples use tsx. Most of the documentation is tsx. So those of us using vdom calls (v()/w ()) have no documentation for API changes outside of manually translating tsx, which is error-prone at the very least. If you thought of Dojo updates in terms of existing users, adding vdom API call doc would be one of the top priorities before rolling out V7. That "raised an issue a while back" should have been a blocking issue for v7, not something you "hope to add soon." (As it stands, my developers have nearly zero use for the current Dojo documentation.)

This was explained to some degree in the v6 release. At a minimum, you can still use the v6 widgets with the v7 framework, though I know you of course want to stay current with things. There are things that are difficult to do from an ergonomics and a TypeScript perspective that work better with tsx over v/w, which is the opposite of what was true two years ago. If this is not clear why I can dig up the details if you are curious and don't see the relevant issue (let us know, this reply is already getting pretty verbose :) ).

I've been using Dojo for a long time. I've never seen the project go so completely off the rails as it has with this release. For the first time in 12 years I have no idea where Dojo is going or why changes were made in the last version. Without that knowledge, much of v7 appears to be random changes for the sake of change. There's no deprecation warnings, no allowance for a phased migration, just whack-change, new-replaces-old. I have no idea what problems you thought you were solving, just reassurances that these changes make everything somehow better.

Frankly I think this is unfair to the Dojo team who do this work in the time they have or the time that their respective employers allow them to contribute. It was a substantial effort by a small team trying to fix things that were frustrating or that didn't quite work right. And I do think the details are in there, but again, a blog post announcing a release tends to highlight things rather than dwell on every implementation detail and decision.

"Staying competitive" includes the care-and-feeding of existing users. When you throw that out, no matter how much cool and current tech you throw at Dojo, you have failed.

I don't think we as a team ever try to throw something out or try to be cool. Every decision is made with care and deliberation. We saw that some of the early widget decisions were causing a lot of problems, and attempted to fix as many of them as we could.

[bitranch]

Hi @dylans

That said, I feel like all of the significant changes were communicated through issues in their respective repos that were open for quite a while.

This seems to be saying, in order to understand what's going on, I (and every other Dojo user) should read the open and closed issues across several repos. That's at least 100 issues to sift through. Many of them cross-referencing other issues, some abandoned mid-stream. Now I have to figure out the relative importance of the issues, and what part of epics were implemented. The in-issue checkboxes certainly aren't reliably maintained, so that's more noise to filter. I'm still left guessing why choices were made for whole chunks. Plus there's no context around many issues.

I've been reading Dojo issues for quite some time. There's a lot of assumed knowledge. There's a tacit assumption of agreement with unstated background decisions (e.g. "use TSX", "prefer functional widgets").

Issue #780 is a nice checklist of things to do, but there's little to grab onto if you're trying to understand what's going on:

• There are no comments or warnings about removing backward compatibility. (Unless "Align and improve upon API of existing widgets" actually means "remove or rename APIs ignoring compatibility with existing code".)
• Most of "Advice/guidelines" are completely unexplained. (See "tacit assumption of agreement" above.)

Frankly I think this is unfair to the Dojo team who do this work in the time they have or the time that their respective employers allow them to contribute. It was a substantial effort by a small team trying to fix things that were frustrating or that didn't quite work right.

My point was that code was changed with no consideration of how that would affect existing users.

Let me emphasize: existing users. My core complaint is v7 became self-absorbed and lost the story of who it's primarily for.

An overview and a roadmap being replaced by multiple issues across several repos reinforces how that story was lost. A software version released with no thought of easing migration reinforces how that story was lost.

Existing users got lost in v7. That's a cultural issue. It may have been a substantial effort, but if not one person loudly demanded "how does this affect our users?" is that effort even on the right path?

I don't think we as a team ever try to throw something out

It may not be the intent, but Dojo did exactly that with v7 via:

• Removal/renaming of APIs
• Renamed interface(s) in framework
• Lack of any deprecation policy
• Forcing a hard migration path for upgrades

This isn't about maintaining infinite back-compatibility. It's about needing back-compatibility for one major version to ease code migration. And it's also about caring about existing users.

[matt-gadd]

I would like to clarify a few things:

I've been reading Dojo issues for quite some time. There's a lot of assumed knowledge. There's a tacit assumption of agreement with unstated background decisions (e.g. "use TSX", "prefer functional widgets").

1. TSX has no affect on consumers in terms of usage. The only place where this has had any effect on users is in the documentation. We have had multiple requests for the TSX form as it's easier to grok. Saying that as I have previously stated there is an issue to support both styles in the documentation. A reminder that we have supported both TSX and the v()/w() functions since initial release. I also think it's not a huge leap to read between the 2 forms:

<div>Hello</div>

v('div', [ 'Hello' ])

2. We have made strong arguments on function based widgets, and they were heavily documented in the v6 blog posts and issues leading up to it, its completely unfounded to say there are unstated background decisions based on this. If you are familiar with the dojo project there is a multi year documentation trail from this going all the way back to https://github.com/dojo/compose.

My core complaint is v7 became self-absorbed and lost the story of who it's primarily for.

If self-absorbed is making our authoring system both easier to use and our widgets out of the box easier to use (without a ton of inconsistent patterns and properties across each widget) then i'm lost honestly. In v7 we've improved nearly every part of the widget system. from usage, theming, authoring, documenting and building.

We have gone 4 major (major = breaking) releases of modern dojo, and for the most part these have been mostly automated in upgrade paths via the upgrade tool, and we've made every effort in both not breaking things, being forward and backwards compatible with TypeScript, while also trying to move the framework forward. This is not an easy task. To suggest the team places "no thought of easing migration" is absolutely disingenuous.

In terms of v7 we decided that it was impossible to fix some of the patterns and the api's inconsistencies in Widgets (a lot of which were written before dojo as a framework was even initially released!) without a number of breaking changes. There was no easy way to offer backwards compatibility or else we would have taken it. Trust me, no one wanted to spend all those hours writing up a migration guide to make it easier to upgrade. And also like previously stated, v6 of Widgets is fully compatible with v7 of framework and we will continue to support it.

Removal/renaming of APIs
Renamed interface(s) in framework

If you can let us know on dojo/framework what api's and interfaces have been removed/renamed that would help. Some things do slip through the gaps 👍.

Noting all the above, I do appreciate that not everyone has time to go through all the issues across the dojo project, nor try the release candidates to know what is coming. We will absolutely try to improve our communication on a higher level via the roadmap (which frankly has been neglected while we updated dojo.io), and potentially other means; we are open to suggestions.

[raggedgenes]

Hi @matt-gadd and @dylans
SplitPane is a widget thas was REMOVED in v7.0!
The link is dead: https://github.com/dojo/widgets/blob/master/src/split-pane/README.md
Can you confirm if is a mistake or planned?

[dylans]

@raggedgenes It does appear that the migration guide and blog post completely missed discussion around the removal of SplitPane and what to replace it with (There's a very terse comment at #698 (comment) ).

We'll get something added to the migration guide that explains this change asap. cc @tomdye

[xiaohulu]

adding vdom API call doc would be one of the top priorities

should document how to use Hyperscript(VDOM api) to contains multiple children

for example

<ParentWidget>{{
	foo: (foo) => <ChildWidget foo={foo('a')} />,
	bar: <span>bar</span>,
	baz: 'hello, world'
}}</ParentWidget>

is it?

w(ParentWidget, {}, [{
	foo: (foo) => <ChildWidget foo={foo('a')} />,
	bar: <span>bar</span>,
	baz: 'hello, world'
}]);

@dojo/widgets v7.0 is great，it is the first stable release for widgets in my opinion.

[edwinspire]

Greetings to all. In my particular case I have some relatively large projects in V6, which I will inevitably have to rewrite code to continue supporting my clients by migrating to v7, it is time to invest that I did not have in mind.

It is true that I have not had the time to read each of the topics related to the migration from v6 to v7 that have been discussed throughout these months and because of that my unpleasant surprise.
The Roadmap used to be my main point of inquiry for future changes and when they would happen, now it looks abandoned.

Widgets are great when in new versions they can still be used with the same functionality or with additional improvements, but in this case they have removed widgets, or "renamed" them, but changed the functionality that they had.

For example "Toolbar" in v6 allowed me to have a minimized menu mobile browsers, ideal in PWA which is where I mainly use Dojo, it was very easy to use, now in v7 it is called "Header" and it is no longer responsive, I don't know which one it is The technical reason for removing that feature but maintaining that functionality would not have implied having to rewrite code and look for other options.

Another case is the "Select" widget that I used a lot in my projects, today it is more difficult to implement due to @ dojo / framework / core / middleware / resources, it is more nor the proposed example I have been able to make it work.

I suggest that if a widget is to be removed or replaced, it should be kept for one or two other versions, clarifying in the documentation that the widget is out of date and should no longer be used in new projects.

I don't use tsx, I use widgets as classes in 100% of my projects which has become a barrier to switch to v7 and I am seriously concerned that in the future there will no longer be support to create widgets as classes.
Given my urgency to move forward with my projects, I have had to look for alternatives and, unfortunately, I am inclined to use pure HTML elements with a CSS library (Bulma.io) that allows me to continue developing without fear of having the functionality of a widget changed or that I remove it.

The Dojo project has been great since its inception, I hope to be able to collaborate with something at some point.
The unpleasant experience that many have had with this version I hope and serve so that, both users and developers, we are more in contact and thus minimize the impact on the existing code.
Remember that there are many projects already in production with Dojo 2 and some developers have chosen this framework for different reasons and we are always on the lookout for new things and improvements that each version brings us, in the hope that our fabulous code will not be broken.

The format of the new documentation seems very good and readable to me, I hope to add examples with v () and w (), object oriented (classes) soon.

[tomdye]

@raggedgenes regarding the split pane, it was planned that this would be removed in favour of the new TwoColumnLayout widget. This widget provides a responsive two column layout for your apps, however, it appears that we neglected to add in the resize functionality as was intended. I have created a POC to prove out an approach and have raised an issue for this to be incorporated into the TwoColumnLayout widget as intended. The issue can be found here.

@edwinspire the responsive functionality which was previously in Toolbar was purposefully excluded from the new Header so that it can be used as a building block for future composite widgets such as a fully-fledged app-bar header. We aim to work on more of these app-level widgets using the base widgets for our v8 release. I appreciate that not including an example of how to put this functionality together using the Header and SlidePane was an oversight so I have raised a PR to add an example to the v7 migration guide here. If you wish to check out an example using this code and take a look yourself you can find find it here. This approach should provide much greater control over layout / styling and utilises the breakpoint middleware.

@edwinspire I appreciate that the move to resources is not as easy as others when using class-based widgets but it is possible using a simple resource-wrapper that can inject the resource-middleware into your widgets. An example of this can be seen here. I have raised a pull request to bring this example into the v7 migration guide also so that others can benefit from this solution. The pull request is here.

[edwinspire]

Best regards. I consider the matter closed. Thanks to all the developers and collaborators involved in the project, I understand that it has been hard work and their goal is to make this framework more solid every day.
In these years using them has given me a lot of satisfaction. Perhaps in the current state of the project it no longer meets my needs. I will be watching how it evolves and in the future I hope to return. See you soon.

[tomdye]

@edwinspire I've just released @dojo/[email protected] which should hopefully resolve a lot of the issues adressed here and provide more examples / guidance for the things that we have changed.
One such change is adding resize flag to the TwoColumnLayout which makes it behave like the previous SplitPane functionality.
We appreciate the input and feedback from our users and hope we can continue to work together to build great software.