Added more migration information

The documentation for templates still needs to be created.

A warning is now generated in the console for applications using
the previous data attributes that have been migrated.

dist/js/select2.amd.full.js

@@ -3462,6 +3462,31 @@ define('select2/options',[
     $e.prop('disabled', this.options.disabled);
     $e.prop('multiple', this.options.multiple);
 
+    if ($e.data('select2-tags')) {
+      if (console && console.warn) {
+        console.warn(
+          'Select2: The `data-select2-tags` attribute has been changed to ' +
+          'use the `data-data` and `data-tags="true"` attributes and will be ' +
+          'removed in future versions of Select2.'
+        );
+      }
+
+      $e.data('data', $e.data('select2-tags'));
+      $e.data('tags', true);
+    }
+
+    if ($e.data('ajax-url')) {
+      if (console && console.warn) {
+        console.warn(
+          'Select2: The `data-ajax-attribute` has been changed to ' +
+          '`data-ajax--url` and support for the old attribute will be removed' +
+          ' in future versions of Select2.'
+        );
+      }
+
+      $e.data('ajax--url', $e.data('ajax-url'));
+    }
+
     var data = $e.data();
 
     function convertData (data) {

dist/js/select2.amd.js

@@ -3462,6 +3462,31 @@ define('select2/options',[
     $e.prop('disabled', this.options.disabled);
     $e.prop('multiple', this.options.multiple);
 
+    if ($e.data('select2-tags')) {
+      if (console && console.warn) {
+        console.warn(
+          'Select2: The `data-select2-tags` attribute has been changed to ' +
+          'use the `data-data` and `data-tags="true"` attributes and will be ' +
+          'removed in future versions of Select2.'
+        );
+      }
+
+      $e.data('data', $e.data('select2-tags'));
+      $e.data('tags', true);
+    }
+
+    if ($e.data('ajax-url')) {
+      if (console && console.warn) {
+        console.warn(
+          'Select2: The `data-ajax-attribute` has been changed to ' +
+          '`data-ajax--url` and support for the old attribute will be removed' +
+          ' in future versions of Select2.'
+        );
+      }
+
+      $e.data('ajax--url', $e.data('ajax-url'));
+    }
+
     var data = $e.data();
 
     function convertData (data) {

dist/js/select2.full.js

@@ -12997,6 +12997,31 @@ define('select2/options',[
     $e.prop('disabled', this.options.disabled);
     $e.prop('multiple', this.options.multiple);
 
+    if ($e.data('select2-tags')) {
+      if (console && console.warn) {
+        console.warn(
+          'Select2: The `data-select2-tags` attribute has been changed to ' +
+          'use the `data-data` and `data-tags="true"` attributes and will be ' +
+          'removed in future versions of Select2.'
+        );
+      }
+
+      $e.data('data', $e.data('select2-tags'));
+      $e.data('tags', true);
+    }
+
+    if ($e.data('ajax-url')) {
+      if (console && console.warn) {
+        console.warn(
+          'Select2: The `data-ajax-attribute` has been changed to ' +
+          '`data-ajax--url` and support for the old attribute will be removed' +
+          ' in future versions of Select2.'
+        );
+      }
+
+      $e.data('ajax--url', $e.data('ajax-url'));
+    }
+
     var data = $e.data();
 
     function convertData (data) {

dist/js/select2.js

@@ -3890,6 +3890,31 @@ define('select2/options',[
     $e.prop('disabled', this.options.disabled);
     $e.prop('multiple', this.options.multiple);
 
+    if ($e.data('select2-tags')) {
+      if (console && console.warn) {
+        console.warn(
+          'Select2: The `data-select2-tags` attribute has been changed to ' +
+          'use the `data-data` and `data-tags="true"` attributes and will be ' +
+          'removed in future versions of Select2.'
+        );
+      }
+
+      $e.data('data', $e.data('select2-tags'));
+      $e.data('tags', true);
+    }
+
+    if ($e.data('ajax-url')) {
+      if (console && console.warn) {
+        console.warn(
+          'Select2: The `data-ajax-attribute` has been changed to ' +
+          '`data-ajax--url` and support for the old attribute will be removed' +
+          ' in future versions of Select2.'
+        );
+      }
+
+      $e.data('ajax--url', $e.data('ajax-url'));
+    }
+
     var data = $e.data();
 
     function convertData (data) {

docs/announcements-4.0.html

@@ -176,7 +176,7 @@ slug: announcements-4.0
 
     <p>
       The options that you create should have <code>selected="selected"</code>
-      set, so Select2 and the browser knows that they should be selected. The
+      set so Select2 and the browser knows that they should be selected. The
       <code>value</code> attribute of the option should also be set to the value
       that will be returned from the server for the result, so Select2 can
       highlight it as selected in the dropdown. The text within the option
@@ -277,6 +277,71 @@ $("select").select2({
       sent to the server.
     </p>
 
+    <h2 id="changed-options">Changed method and option names</h2>
+
+    <p>
+      When designing the future option set for Select2 4.0, special care was
+      taken to ensure that the most commonly used options were brought over.
+      For the most part, the commonly used options of Select2 can still be
+      referenced under their previous names, but there were some changes which
+      have been noted.
+    </p>
+
+    <h3 id="changed-templating">Renamed templating options</h3>
+
+    <p>
+      Select2 previously provided multiple options for formatting the results list and selected options, commonly referred to as "formatters", using the <code>formatSelection</code> and <code>formatResult</code> options. As the "formatters" were also used for things such as localization, <a href="#changed-translations">which has also changed</a>, they have been renamed to <code>templateSelection</code> and <code>templateResult</code> and their signatures have changed as well.
+    </p>
+
+    <p>
+      You should refer to the updated <a href="options.html#templates">documentation on templates</a> when migrating from previous versions of Select2.
+    </p>
+
+    <h3 id="changed-translations">Renamed translation options</h3>
+
+    <p>
+      In previous versions of Select2, the default messages provided to users could be localized to fit the language of the website that it was being used on. Select2 only comes with the English language by default, but provides <a href="options.html#language">community-contributed translations</a> for many common languages. Many of the formatters have been moved to the <code>language</code> option and the signatures of the formatters have been changed to handle future additions.
+    </p>
+
+    <h3 id="changed-data">
+      Declaring options using <code>data-*</code> attributes
+    </h3>
+
+    <p>
+      In the past, Select2 has only supported declaring a subset of options
+      using <code>data-*</code> attributes. Select2 now supports declaring all
+      options using the attributes, using
+      <a href="options.html#data-attributes">the format specified in the documentation</a>.
+    </p>
+
+    <p>
+      You could previously declare the URL that was used for AJAX requests using
+      the <code>data-ajax-url</code> attribute. While Select2 still allows for
+      this, the new attribute that should be used is the
+      <code>data-ajax--url</code> attribute. Support for the old attribute will
+      be removed in Select2 4.1.
+    </p>
+
+    <p>
+      Although it was not documented, a list of possible tags could also be provided using the <code>data-select2-tags</code> attribute and passing in a JSON-formatted array of objects for tags. As the method for specifying tags has changed in 4.0, you should now provide the array of objects using the <code>data-data</code> attribute, which maps to <a href="options.html#data">the array data</a> option. You should also enable tags by setting <code>data-tags="true"</code> on the object, to maintain the ability for users to create their own options as well.
+    </p>
+
+    <p>
+      If you previously declared the list of tags as...
+    </p>
+
+<pre class="prettyprint linenums">
+&lt;select data-select2-tags="[{id: '1', text: 'One', id: '2', text: 'Two'}]"&gt;&lt;/select&gt;
+</pre>
+
+    <p>
+      ...then you should now delare it as...
+    </p>
+
+<pre class="prettyprint linenums">
+&lt;select data-data="[{id: '1', text: 'One', id: '2', text: 'Two'}]" data-tags="true"&gt;&lt;/select&gt;
+</pre>
+
     <h2 id="removed-methods">Deprecated and removed methods</h2>
 
     <p>
@@ -306,8 +371,12 @@ $("select").select2({
       Select2 will respect the <code>disabled</code> property of the underlying
       select element. In order to enable or disable Select2, you should call
       <code>.prop('disabled', true/false)</code> on the
-      <code>&lt;select&gt;</code> element. This method will be completely
+      <code>&lt;select&gt;</code> element. Support for the old methods will be
-      removed in Select2 4.1.
+      completely removed in Select2 4.1.
     </p>
   </section>
 </div>
+
+<script type="text/javascript">
+prettyPrint();
+</script>

src/js/select2/options.js

@@ -44,6 +44,31 @@ define([
     $e.prop('disabled', this.options.disabled);
     $e.prop('multiple', this.options.multiple);
 
+    if ($e.data('select2-tags')) {
+      if (console && console.warn) {
+        console.warn(
+          'Select2: The `data-select2-tags` attribute has been changed to ' +
+          'use the `data-data` and `data-tags="true"` attributes and will be ' +
+          'removed in future versions of Select2.'
+        );
+      }
+
+      $e.data('data', $e.data('select2-tags'));
+      $e.data('tags', true);
+    }
+
+    if ($e.data('ajax-url')) {
+      if (console && console.warn) {
+        console.warn(
+          'Select2: The `data-ajax-attribute` has been changed to ' +
+          '`data-ajax--url` and support for the old attribute will be removed' +
+          ' in future versions of Select2.'
+        );
+      }
+
+      $e.data('ajax--url', $e.data('ajax-url'));
+    }
+
     var data = $e.data();
 
     function convertData (data) {