Grid compatibility in 1.2

[jaredj]

Grid compatibility in 1.2

This concern was raised by people at my place of employment. There is a lo of needed and good work going into the dojox Grid to make it better ... but it breaks current users. Since there are a lot of people making use of it now, we need a good story for compatibility (a layer or a mixin or something), or some sort of option for them to be able to still use code from 1.1 without a lot of pain to upgrade.

Opening this at the request of Dylan.

[alex]

so after a discussion w/ Bryan, I want to clarify the strategy we're employing for 1.2 and the reasons for it:

• we landed the grid inside of dojox in order to make it clear that the APIs would change. It has taken us longer than anticipated to make some of the desired changes, but that doesn't reduce the need nor imply anything different about the advertised maturity level of the APIs that shipped on 1.0 and 1.1
• many of the names used in the initial shipping versions don't conform to the style guide. It's possible to do a thin shim to provide back-compat on this level and Bryan has already mentioned to me his intention to do this (likely tracked under the cover of this bug)
• there are *serious* issues with the existing APIs. Not only are there layers if indirection in the current configuration structure that make the grid hard to use, there are layers of code in the grid and model systems which don't make sense in a Dojo 0.9+ world. Those tracts of code need to be removed if we have any hope of keeping the grid code a living body of work and not a dead tool. Making some of these changes necessarily means breaking back-compat.
• the grid needs new features badly. Many of these features need to be based on a modernized code-based lest we face even more forward-porting issues as we go on. Given the limited resources available from SitePen? to pour into the grid, we're prioritizing things that give us longer-term leverage and then working to implement high-priority features

I think the right strategy here is going to be for us to continue to slash-and-burn up to and perhaps just past the 1.2 release. This means that new features are going to likely be added without much hesitation and old, sub-optimal decisions will be cut away. There's no plan to *cut* old features, but their form will change (almost always by way of simplification). The best thing for those critically depending on the previous configuration style will be to perhaps express *exactly* what they need in terms of features and lay out how they're using the Grid so that we can figure out if a thin shim will do the job to get them up-ported or if there's more work to be done in terms of providing a back-compat wrapper (assuming they can't just forward-port).

Regards

[chrism]

Here't the official release note: http://www.sitepen.com/blog/2007/11/05/dojo-foundation-announces-dojo-toolkit-10/ The release notes that 1.0 now includes a high-performance grid (alongside other features that do have n-1 compatibility), with no mention that it's beta or experimental. (the numerous related blogs to Ajaxian, etc. are all similar, and all represent grid as a feature alongside other features that have been treated as stable.

Users are already frustrated and have been leaving because of api changes. The following blog post type of comment and reaction Dojo will likely receive if high-visibility features like grid are not handled with n-1 compatibility in mind: http://www.dojotoolkit.org/forum/dijit-dijit-0-9/dijit-support/please-more-stability-required

In this post: http://www.dojotoolkit.org/forum/dojo-foundation/general-discussion/need-advice-0-4-or-1-0 Note that the post is about will 1.0 be api compatible with previous versions but it is immediately followed by posts about how grid has finally landed (with no mention that it's experimental or beta)--so in these user's minds they think they're getting a grid that's stable because in the context of the discussion 1.0 Extensions stability is not mentioned. We've all seen grid promoted this way (you never hear if you use it be careful because it's changing a lot).

We now have MANY customers that have grid in their applications and this screws them again (in some of their eyes again if they were around for the 0.4-0.9 migration).

The fact that grid has been in a beta state (meaning needs better docs?) has hardly been advertised, as can be seen in these examples--and this wouldn't be the major issue that it is for us if it had been honestly been presented that way. http://dojotoolkit.org/projects/dojox <- We do mention that one should check the stability of dojox projects, but we haven't mentioned anything about what alpha/beta/production means in those projects in terms of api compatibility. Tom and Adam's work to address this should help going forward.

I fully understand the reasons why one does not want to support and maintain the 1.1 level of grid code at this point. We have also had a developer tied up fixing a myriad of Grid defects since 1.0--and we really like the changes in 1.2 grid.

If we're going to take a hard line on compatabilty of it, we at least are going to need good migration docs, and a roadmap for when we do expect it to be stable (eg. when will it move into dijit?) Can we plan to put grid into dijit in 1.3 and deprecate the dojox.grid module for example?

The approach that was taken with the rewrite of SplitContainer? and LayoutContainer? as BorderContainer? is much more acceptable to customers. (And I honestly believe this is how current dojo users will be expecting)

Can we please reconsider and make a better attempt here to help users in this particular situation?

We are doing quite a lot to sell the dojo story with our customers, but each time an api change like this happens unexpectedly, its a big step back and we lose users. Handling changes like this (without a deprecation) are much better left to major versions, because the perception at major version number changes is that the api's are changing.

Best regards, -Chris

[chrism]

I spoke with Alex about this recently in a private chat, and he said he is ok with doing a rename approach for the new grid in order to keep compatibility, as long as we have a clear strategy for dealing with the old code.

The key requirement here is that applications should continue to run as they did previously when using Grid 1.1, and that it is a choice for developers to upgrade their apps to the new Grid 1.2 api's.

The new Grid 1.2 api's will still not be deemed stable by time of 1.2. The preferred option would be to put Grid into dijit namespace with experimental tag, but since this is not allowed, and we need to keep the old 1.1 Grid code in place to keep applications running as they did before, I'd like to propose the following solution for 1.2:

dojox/datagrid - Contains the 1.2 Grid. README should state status as per Tom and Adam's recent dojox status proposal. Code should be marked dojox.experimental with deprecation debug warning indicating that the dojox/datagrid is the new preferred codebase for Grid as of 1.2.

dojox/grid - Contains the 1.1.1 Grid. Change README to note status of deprecated/orphaned with a note that this code is no longer being maintained, and that the new dojox/datagrid is now the preferred Grid codebase as of 1.2.

For 1.3 release - Complete dojox/datagrid/Grid api, documentation, i18n, ally. Move grid codebase to dijit/Grid. Deprecate dojox/datagrid with debug warning stating dijit/Grid is the final stable api for 1.x releases. Create dojox/datagrid/Grid alias to dijit/Grid for backward compatibility with 1.2.

-Chris

[chrism]

Replying to chrism:

I spoke with Alex about this recently in a private chat, and he said he is ok with doing a rename approach for the new grid in order to keep compatibility, as long as we have a clear strategy for dealing with the old code. The key requirement here is that applications should continue to run as they did previously when using Grid 1.1, and that it is a choice for developers to upgrade their apps to the new Grid 1.2 api's. The new Grid 1.2 api's will still not be deemed stable by time of 1.2. The preferred option would be to put Grid into dijit namespace with experimental tag, but since this is not allowed, and we need to keep the old 1.1 Grid code in place to keep applications running as they did before, I'd like to propose the following solution for 1.2: dojox/datagrid - Contains the 1.2 Grid. README should state status as per Tom and Adam's recent dojox status proposal. Code should be marked dojox.experimental with deprecation debug warning indicating that the dojox/datagrid is the new preferred codebase for Grid as of 1.2.

Minor change: we probably don't need the deprecation warning for dojox/datagrid until 1.3.

dojox/grid - Contains the 1.1.1 Grid. Change README to note status of deprecated/orphaned with a note that this code is no longer being maintained, and that the new dojox/datagrid is now the preferred Grid codebase as of 1.2. For 1.3 release - Complete dojox/datagrid/Grid api, documentation, i18n, ally. Move grid codebase to dijit/Grid. Deprecate dojox/datagrid with debug warning stating dijit/Grid is the final stable api for 1.x releases. Create dojox/datagrid/Grid alias to dijit/Grid for backward compatibility with 1.2. -Chris

[bill]

I'm fine w/moving grid to dijit as soon as the API is stable. I'm not sure when that will be though; hopefully for 1.3.

What is our strategy for dealing w/the old code?

[chrism]

dojox/grid would remain in place (no longer maintained as the primary codebase for Grid and new features, unless there are patches contributors want to apply to that codebase). At 2.0 we would have the option to jettison the old dojox/grid and dojox/datagrid codebase.

[chrism]

The strategy for dealing with Grid should also be outlined in the migration guide for 1.2, to communicate the actual stability of datagrid api's and the approach that we are using to get Grid treated as a first class dijit.

[bill]

Nathan and I would suggest dojox.table.Table for the new code (becoming dijit.Table eventually).

[BryanForbes]

(In [14371]) fixes #6797 !strict

• Added 1.1 grid at dojox/grid/compat.
• Added dojox/grid/Grid.js and dojox/grid/VirtualGrid.js which just bring in the appropriate files from the compat module.
• Updated tests in the compat package to have the correct paths for CSS and JavaScript?.
• Added test showing 1.1 and 1.2 grids on the same page working in harmony.