@jupyter-widgets/controls _model_module_version uses protocol version

[blois]

I'm primarily looking for clarification on the _model_module_version which is included in the model state.

In https://github.com/jupyter-widgets/ipywidgets/blob/master/docs/source/migration_guides.md#updating-the-client-side-code it states:

For embedding to work correctly, the module version needs to be a semantic version range that matches a release on NPM.

@jupyter-widgets/controls specifies the version at

ipywidgets/python/ipywidgets/ipywidgets/widgets/widget_core.py

Line 14 in 58adde2

_model_module_version = Unicode(__jupyter_widgets_controls_version__).tag(sync=True)

which refers to

ipywidgets/python/ipywidgets/ipywidgets/_version.py

Line 12 in 58adde2

__jupyter_widgets_controls_version__ = '2.0.0'

This states:

These are protocol versions for each package, not npm versions.

All other controls use npm versions here, why does controls not?

[jasongrout]

All other controls use npm versions here, why does controls not?

The controls version has indeed been a special case in two ways, and it has worked up to this point because by convention controls has been distributed with the widget manager. These special cases have been an experiment in doing the version communication in what I think is a more correct way than what normal widgets do:

1. the version is not an npm version. This has saved us some grief, in that the npm version changes a lot more than the actual model changes, so we are able to maintain better compatibility across versions.
2. the version "range" is actually a single version number, and (at least the jlab manager, which pays attention to versions) adds the ^ as needed:

   ipywidgets/python/jupyterlab_widgets/src/manager.ts

   Lines 190 to 200 in 58adde2

   	// Special-case the Jupyter base and controls packages. If we have just a
   	// plain version, with no indication of the compatible range, prepend a ^ to
   	// get all compatible versions. We may eventually apply this logic to all
   	// widget modules. See issues #2006 and #2017 for more discussion.
   	if (
   	(moduleName === '@jupyter-widgets/base' ||
   	moduleName === '@jupyter-widgets/controls') &&
   	valid(moduleVersion)
   	) {
   	moduleVersion = `^${moduleVersion}`;
   	}

Note that controls does not publish an AMD module, so it cannot be loaded as other widgets are from CDN, yet.

Background context: when we first started working with this version communication years ago, @SylvainCorlay and I disagreed about how it should be done. I advocated for the kernel side to communicate which version of protocol it would speak, i.e., the version it should communicate would be the version of the model schema it understood. I felt it was the frontend's job to provide js that could understand that particular version of the model schema for that package. The complicated part is that somehow the frontend needs to know a mapping from model schema versions to actual js package versions, and that we need to explain to widget authors what this new version number was and how it differed from all the other version numbers they were dealing with. @SylvainCorlay felt that that was too complicated for most widget authors, and most widget model schemas should just be versioned by their npm package version number, which is what we suggest right now for custom widgets.