From 8bd92c97083f3a14b226d409c8647d63afa6d6ab Mon Sep 17 00:00:00 2001
From: =?utf8?q?Pekka=20Hyv=C3=B6nen?= <pekka@vaadin.com>
Date: Fri, 9 Dec 2016 09:57:14 +0200
Subject: [PATCH] Add list of breaking changes in FW8 to release notes (#102)

* Add list of breaking changes in FW8 to release notes

Fixes vaadin/framework8-issues#226
---
 all/src/main/templates/release-notes.html | 120 +++++++++++++++++++---
 1 file changed, 108 insertions(+), 12 deletions(-)

diff --git a/all/src/main/templates/release-notes.html b/all/src/main/templates/release-notes.html
index 13e71ff9d8..99f41b2c91 100644
--- a/all/src/main/templates/release-notes.html
+++ b/all/src/main/templates/release-notes.html
@@ -103,21 +103,117 @@
                 Notes for Vaadin 7.7.0</a>.
         </p>
 
-        <h3 id="incompatible">Incompatible or Behavior-altering Changes in @version-minor@</h3>
-        <ul>
+        <h2 id="incompatible">Incompatible or Behavior-altering Changes in @version-major@</h2>
+        
+        <ul><h4>Compatibility and requirements</h4>
             <li>Vaadin now requires Java 8 or later and Servlet 3.0 or later</li>
             <li>Support for older browsers (including Microsoft IE 8-10) and Windows Phone has been dropped</li>
-            <li>A new data binding API replaces the old API (including Container, Item, Property, FieldGroup, Validator, Converter and components using those).</li>
-            <li>The default width of Label is now undefined, matching other components</li>
-            <li>Immediate mode is the default for all components except Upload</li>
-            <li>Some deprecated/obsolete parts of API (including the Form component) have been removed</li>
-            <li>Most addListener/removeListener methods have been removed - use the Java 8 friendly addClickListener(), addValueChangeListener() etc. instead</li>
-            <li>Many new listeners are unregistered using a Registration object returned by addXyzListener() rather than with a separate removeXyzListener()</li>
-            <li>Old input prompts have been replaced with placeholders utilizing the related browser functionality</li>
+            <li><a href="#supportedservers">Supported servers</a></li>
+        </ul>
+        <ul><h4>New Data Binding API related changes</h4>
+            <li>Components using <tt>Property</tt>, <tt>Item</tt> or <tt>Container</tt> API have been reimplemented for the new API, except <tt>Tree</tt>, <tt>Table</tt>, <tt>TreeTable</tt> and <tt>Calendar</tt></li>
+            <li>Vaadin 7 versions of the components available in the v7 compatibility package for easier migration, <a href="#legacycomponents">see list of legacy components</a></li>
+            <li><tt>Binder</tt> is the replacement of <tt>FieldGroup</tt>, and similarly <tt>BeanBinder</tt> is the replacement of <tt>BeanFieldGroup</tt></li>
+            <li>Converters and Validators have been moved from Components to <tt>Binder</tt></li>
+            <li><tt>DataProvider</tt> is the replacement of <tt>Container</tt></li>
+            <ul>
+                <li><tt>ListDataProvider</tt> is the default in-memory data provider replacing <tt>IndexedContainer</tt>, <tt>BeanItemContainer</tt>, and <tt>BeanContainer</tt></li>
+                <li><tt>BackEndDataProvider</tt> is the basis for a lazy data provider</li>
+                <li><tt>SQLContainer</tt> is deprecated in v7 compatibility package and not directly replaced</li>
+                <li><tt>HierarchicalContainer</tt> is deprecated in v7 compatibility package and a replacement is planned for 8.1</li>
+            </ul>
+            <li>All components that list data are based on <tt>Listing / AbstractListing</tt></li>
+            <li>All <tt>Listing</tt> components have been typed with the type of items they are listing</li>
+            <li><tt>HasValue</tt> replaces the <tt>Field</tt> interface as the basis for all field components</li>
+            <li>Field components based on <tt>HasValue</tt> may or may not accept null values, depending on each component. There is no <tt>setNullRepresentation</tt> anymore</li>
+            <li><tt>AbstractField::setRequired(boolean)</tt> has been replaced with:
+            <ul>
+                <li><tt>HasValue::setRequiredIndicatorVisible(boolean)</tt> which only makes the <tt>*</tt> required indicator visible for the component</li>
+                <li><tt>BindingBuilder::setRequired(String)</tt> adds a "not-empty" validator when used in <tt>Binder</tt> and makes the <tt>*</tt> required indicator visible</li>
+            </ul>
+            <li><tt>setItemCaptionGenerator</tt> in <tt>AbstractListing</tt> replaces <tt>setItemCaption</tt>, <tt>setItemCaptionMode</tt> and <tt>setItemCaptionPropertyId</tt> from <tt>AbstractSelect</tt></li>
+            <li><tt>setItemIconGenerator</tt> in <tt>AbstractListing</tt> replaces <tt>setItemIcon</tt> and <tt>setItemIconPropertyId</tt> from <tt>AbstractSelect</tt></li>
+        </ul>
+        <ul><h4>General API changes</h4>
+            <li>All components are now immediate, and <tt>AbstractComponent::setImmediate(boolean immediate)</tt> has been removed.</li>
+            <li>Read-only is now a feature for field components and has been moved from <tt>AbstractComponent</tt> to <tt>HasValue</tt> </li>
+            <li>Some deprecated/obsolete parts of API have been removed</li>
+            <li>All addListener/removeListener methods have been removed - replaced with the Java 8 friendly <tt>addClickListener()</tt>, <tt>addValueChangeListener()</tt> etc. instead</li>
+            <li>All new listeners are unregistered using a <tt>Registration</tt> object returned by <tt>addXyzListener()</tt> rather than with a separate <tt>removeXyzListener()</tt></li>
+            <li>Input prompts have been replaced with placeholders utilizing the related browser functionality, API is now <tt>setPlaceHolder</tt> instead of <tt>setInputPrompt</tt></li>
+            <li>Valo is the default theme, instead of Reindeer</li>
+            <li>Valo is the only included theme, all other themes have been moved to the <tt>compatiblity-themes</tt> package and are available as a separate dependency</li>
+            <li><tt>SharedState</tt> and the getter methods for it have been added to each component, regardless of whether those are used for anything or not</li>
             <li>The old liferay theme (Liferay 6.0 look) has been removed</li>
-            <li>Components in the compatibility packages now use the prefix "vaadin7-" in declarative design files</li>
-            <li>RichTextArea no longer receives a special "v-richtextarea-readonly" class when readonly, only the standard "v-readonly" class</li>
         </ul>
+        <ul><h4>Component specific API changes</h4>
+            <li><tt>DateField</tt> replaces old <tt>PopupDateField</tt></li>
+            <li><tt>DateField</tt> and <tt>InlineDateField</tt> are now based on Java 8 <tt>LocalDate</tt> instead of <tt>Date</tt></li>
+            <li><tt>DateField</tt> and <tt>InlineDateField</tt> don't support time anymore, meaning the highest resolution for those is <tt>Resolution.DAY</tt></li>
+            <li><tt>OptionGroup</tt> has been removed and replaced by:</li>
+            <ul>
+                <li><tt>CheckBoxGroup</tt> replaces <tt>OptionGroup</tt> in multiselect mode</li>
+                <li><tt>RadioButtonGroup</tt> replaces <tt>OptionGroup</tt> in single select mode</li>
+                <ul><tt>OptionGroup::setItemEnabled(Object, boolean)</tt> has been replaced by <tt>setItemEnabledProvider</tt> that accepts a predicate</ul>
+            </ul>
+            <li><tt>TwinColSelect</tt> is always in multiselect mode</li>
+            <li><tt>ListSelect</tt> is always in multiselect mode</li>
+            <li><tt>Upload</tt> has a separate immediate mode <tt>setImmediateMode(boolean immediateMode)</tt> replacing removed <tt>setImmediate</tt></li>
+            <li><tt>RichTextArea</tt> no longer receives a special "v-richtextarea-readonly" class when readonly, only the standard "v-readonly" class</li>
+            <li><tt>Grid</tt> has been typed to the bean type it is using and its columns are specified with a value provider callback instead of "propertyId"</li>
+            <li><tt>Grid</tt> Editor now uses <tt>Binder</tt> instead of <tt>FieldGroup</tt>, and doesn't support a <tt>FieldFactory</tt></li>
+            <li><tt>Grid</tt> selection API has been removed from component level to <tt>GridSelectionModel</tt> which is available via <tt>Grid::getSelectionModel()</tt></li>
+            <li><tt>Grid::setSelectionModel(GridSelectionModel)</tt> visibility has been changed from <tt>public</tt> to <tt>protected</tt> to reduce confusion with <tt>Grid::setSelectionMode</tt></li>
+        </ul>
+        <ul><h4>Component specific visual changes</h4>
+            <li>The default width of <tt>Label</tt> is now undefined, matching other components</li>
+            <li>The default width for <tt>ComboBox</tt> pop-up is now 100 % (previously undefined)</li>
+            <li><b>NOT YET INCLUDED: </b><tt>VerticalLayout</tt> has by default <tt>spacing = true</tt> and <tt>margin = true</tt></li>
+            <li><b>NOT YET INCLUDED: </b><tt>HorizontalLayout</tt> has by default <tt>spacing = true</tt> and <tt>margin = false</tt></li>
+        </ul>
+        <ul><h4>Component specific declarative syntax changes</h4>
+            <li>Components in the compatibility packages now use the prefix <tt>vaadin7-"</tt> in declarative design files</li>
+            <li><tt>required-indicator-visible</tt> attribute replaces the <tt>required</tt> attribute</li>
+            <li><tt>placeholder</tt> attribute replaces the <tt>input-prompt</tt> attribute for input components</li>
+            <li><tt>multi-select</tt> attribute is no longer used for select components</li>
+            <li><tt>v-option-group</tt> with attribute <tt>multi-select=true</tt> is replaced by <tt>v-check-box-group</tt></li>
+            <li><tt>v-option-group</tt> with attribute <tt>multi-select=false</tt> is replaced by <tt>v-radio-button-group</tt></li>
+            <li><tt>immediate</tt> attribute is not used for any component</li>
+            <li><tt>read-only</tt> attribute is now only used for field components instead of all components</li>
+            <li><tt>v-upload</tt> has a new attribute <tt>immediate-mode</tt> that replaces the removed <tt>immediate</tt> attribue</li>
+        </ul>
+        <ul id="legacycomponents"><h4>Legacy components in the v7 compatiblity package <tt>com.vaadin.v7.ui</tt> available as a separate dependency</h4>
+            <li><tt>Calendar</tt> - no replacement in 8</li>
+            <li><tt>CheckBox</tt></li>
+            <li><tt>ColorPicker</tt></li>
+            <li><tt>ColorPickerArea</tt></li>
+            <li><tt>ComboBox</tt></li>
+            <li><tt>CustomField</tt></li>
+            <li><tt>DateField</tt> - the replacing 8 version does not support selecting time</li>
+            <li><tt>Form</tt> - no replacement in 8</li>
+            <li><tt>Grid</tt> (and renderers)</li>
+            <li><tt>HorizontalLayout</tt></li>
+            <li><tt>InlineDateField</tt> - the replacing 8 version does not support selecting time</li>
+            <li><tt>Label</tt></li>
+            <li><tt>ListSelect</tt></li>
+            <li><tt>NativeSelect</tt></li>
+            <li><tt>OptionGroup</tt> - replaced by <tt>CheckBoxGroup</tt> (multiselection) and <tt>RadioButtonGroup</tt> (single selection)</li>
+            <li><tt>PasswordField</tt></li>
+            <li><tt>PopupDateField</tt> - replaced by partly by <tt>DateField</tt>, but doesn't allow selecting time</li>
+            <li><tt>ProgressBar</tt></li>
+            <li><tt>ProgressIndicator</tt></li>
+            <li><tt>RichTextArea</tt></li>
+            <li><tt>Select</tt> - removed, use <tt>ComboBox</tt> for single selection and <tt>ListSelect</tt> for multiselection</li>
+            <li><tt>Table</tt> - no replacement in 8.0, use Grid.</li>
+            <li><tt>TextArea</tt></li>
+            <li><tt>TextField</tt></li>
+            <li><tt>Tree</tt> - no replacement in 8.0, planned for 8.1</li>
+            <li><tt>TreeTable</tt> - no replacement in 8.0, TreeGrid planned for 8.1</li>
+            <li><tt>TwinColSelect</tt></li>
+            <li><tt>VerticalLayout</tt></li>
+            <li><tt>Upload</tt></li>
+        </ul>
+                
         <h3 id="knownissues">Known Issues and Limitations</h3>
         <ul>
             <li>Context click events are not generated on iOS devices
@@ -368,7 +464,7 @@
             following <b>application servers</b> are supported:
         </p>
 
-        <ul>
+        <ul id="supportedservers">
             <li>Apache Tomcat 7-8</li>
             <li>Apache TomEE 1.7 and 7.0</li>
             <li>Oracle WebLogic Server 12.2</li>
-- 
2.39.5