Updated migration related documentation (#8602)

* Updated migration related documentation

More detailed information on compatibility components.
Mention vaadin:upgrade8 target in migration guide.

Fixes #8581

29 files changed, 104 insertions, 22 deletions

diff --git a/compatibility-server/src/main/java/com/vaadin/v7/ui/Calendar.java b/compatibility-server/src/main/java/com/vaadin/v7/ui/Calendar.java
index d347028895..bf3089e531 100644
--- a/compatibility-server/src/main/java/com/vaadin/v7/ui/Calendar.java
+++ b/compatibility-server/src/main/java/com/vaadin/v7/ui/Calendar.java
@@ -116,6 +116,8 @@ import com.vaadin.v7.ui.components.calendar.handler.BasicWeekClickHandler;
  *
  * @since 7.1
  * @author Vaadin Ltd.
+ *
+ * @deprecated As of 8.0, no replacement available.
  */
 @SuppressWarnings("serial")
 @Deprecated
@@ -1003,7 +1005,7 @@ public class Calendar extends AbstractLegacyComponent
     /**
      * Sets sort order for events. By default sort order is
      * {@link EventSortOrder#DURATION_DESC}.
-     * 
+     *
      * @param order
      *            sort strategy for events
      */
@@ -1018,7 +1020,7 @@ public class Calendar extends AbstractLegacyComponent
 
     /**
      * Returns sort order for events.
-     * 
+     *
      * @return currently active sort strategy
      */
     public EventSortOrder getEventSortOrder() {
diff --git a/compatibility-server/src/main/java/com/vaadin/v7/ui/CheckBox.java b/compatibility-server/src/main/java/com/vaadin/v7/ui/CheckBox.java
index a75815d9df..9aabd6293e 100644
--- a/compatibility-server/src/main/java/com/vaadin/v7/ui/CheckBox.java
+++ b/compatibility-server/src/main/java/com/vaadin/v7/ui/CheckBox.java
@@ -33,6 +33,12 @@ import com.vaadin.v7.data.Property;
 import com.vaadin.v7.shared.ui.checkbox.CheckBoxServerRpc;
 import com.vaadin.v7.shared.ui.checkbox.CheckBoxState;
 
+/**
+ * @author Vaadin Ltd
+ *
+ * @deprecated As of 8.0 replaced by {@link com.vaadin.ui.CheckBox} based on the
+ *             new data binding API
+ */
 @Deprecated
 public class CheckBox extends AbstractField<Boolean> {
 
diff --git a/compatibility-server/src/main/java/com/vaadin/v7/ui/ColorPicker.java b/compatibility-server/src/main/java/com/vaadin/v7/ui/ColorPicker.java
index 5f6c857c2e..5a90b9864e 100644
--- a/compatibility-server/src/main/java/com/vaadin/v7/ui/ColorPicker.java
+++ b/compatibility-server/src/main/java/com/vaadin/v7/ui/ColorPicker.java
@@ -22,9 +22,11 @@ import com.vaadin.v7.shared.ui.colorpicker.Color;
  * component.
  *
  * @since 7.0.0
- *
  * @see ColorPickerArea
+ * @author Vaadin Ltd
  *
+ * @deprecated As of 8.0 replaced by {@link com.vaadin.ui.ColorPicker} based on
+ *             new data binding API
  */
 @Deprecated
 public class ColorPicker extends AbstractColorPicker {
diff --git a/compatibility-server/src/main/java/com/vaadin/v7/ui/ColorPickerArea.java b/compatibility-server/src/main/java/com/vaadin/v7/ui/ColorPickerArea.java
index 06166196d9..5518f087b1 100644
--- a/compatibility-server/src/main/java/com/vaadin/v7/ui/ColorPickerArea.java
+++ b/compatibility-server/src/main/java/com/vaadin/v7/ui/ColorPickerArea.java
@@ -21,9 +21,11 @@ import com.vaadin.v7.shared.ui.colorpicker.Color;
  * A class that defines area-like implementation for a color picker component.
  *
  * @since 7.0.0
- *
  * @see ColorPicker
+ * @author Vaadin Ltd
  *
+ * @deprecated As of 8.0 replaced by {@link com.vaadin.ui.ColorPickerArea} based
+ *             on new data binding API
  */
 @Deprecated
 public class ColorPickerArea extends AbstractColorPicker {
diff --git a/compatibility-server/src/main/java/com/vaadin/v7/ui/ComboBox.java b/compatibility-server/src/main/java/com/vaadin/v7/ui/ComboBox.java
index 0ecfa9657f..f6a9d32d6b 100644
--- a/compatibility-server/src/main/java/com/vaadin/v7/ui/ComboBox.java
+++ b/compatibility-server/src/main/java/com/vaadin/v7/ui/ComboBox.java
@@ -45,6 +45,10 @@ import com.vaadin.v7.shared.ui.combobox.FilteringMode;
  * on newItemsAllowed and change filtering mode (and also turn it off), but you
  * can not turn on multi-select mode.
  *
+ * @author Vaadin Ltd
+ *
+ * @deprecated As of 8.0 replaced by {@link com.vaadin.ui.ComboBox} based on the
+ *             new data binding API
  */
 @SuppressWarnings("serial")
 @Deprecated
diff --git a/compatibility-server/src/main/java/com/vaadin/v7/ui/CustomField.java b/compatibility-server/src/main/java/com/vaadin/v7/ui/CustomField.java
index c2e6c3f40f..e9b7e504f9 100644
--- a/compatibility-server/src/main/java/com/vaadin/v7/ui/CustomField.java
+++ b/compatibility-server/src/main/java/com/vaadin/v7/ui/CustomField.java
@@ -44,6 +44,10 @@ import com.vaadin.v7.data.Property;
  *            field value type
  *
  * @since 7.0
+ * @author Vaadin Ltd
+ *
+ * @deprecated As of 8.0 replaced by a {@link com.vaadin.ui.CustomField} based
+ *             on new data binding API
  */
 @Deprecated
 public abstract class CustomField<T> extends AbstractField<T>
diff --git a/compatibility-server/src/main/java/com/vaadin/v7/ui/DefaultFieldFactory.java b/compatibility-server/src/main/java/com/vaadin/v7/ui/DefaultFieldFactory.java
index 93ea91a9bb..4b60679c41 100644
--- a/compatibility-server/src/main/java/com/vaadin/v7/ui/DefaultFieldFactory.java
+++ b/compatibility-server/src/main/java/com/vaadin/v7/ui/DefaultFieldFactory.java
@@ -1,12 +1,12 @@
 /*
  * Copyright 2000-2016 Vaadin Ltd.
- * 
+ *
  * Licensed under the Apache License, Version 2.0 (the "License"); you may not
  * use this file except in compliance with the License. You may obtain a copy of
  * the License at
- * 
+ *
  * http://www.apache.org/licenses/LICENSE-2.0
- * 
+ *
  * Unless required by applicable law or agreed to in writing, software
  * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
  * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
@@ -27,11 +27,12 @@ import com.vaadin.v7.data.Property;
  * This class contains a basic implementation for both {@link FormFieldFactory}
  * and {@link TableFieldFactory}. The class is singleton, use {@link #get()}
  * method to get reference to the instance.
- * 
+ *
  * <p>
  * There are also some static helper methods available for custom built field
  * factories.
  * 
+ * @deprecated Removed feature in 8.0
  */
 @Deprecated
 public class DefaultFieldFactory
@@ -41,7 +42,7 @@ public class DefaultFieldFactory
 
     /**
      * Singleton method to get an instance of DefaultFieldFactory.
-     * 
+     *
      * @return an instance of DefaultFieldFactory
      */
     public static DefaultFieldFactory get() {
@@ -74,7 +75,7 @@ public class DefaultFieldFactory
     /**
      * If name follows method naming conventions, convert the name to spaced
      * upper case text. For example, convert "firstName" to "First Name"
-     * 
+     *
      * @param propertyId
      * @return the formatted caption string
      */
@@ -93,7 +94,7 @@ public class DefaultFieldFactory
      * <b>Item</b>: {@link Form}. <br/>
      * <b>default field type</b>: {@link LegacyTextField}.
      * <p>
-     * 
+     *
      * @param type
      *            the type of the property
      * @return the most suitable generic {@link LegacyField} for given type
diff --git a/compatibility-server/src/main/java/com/vaadin/v7/ui/Grid.java b/compatibility-server/src/main/java/com/vaadin/v7/ui/Grid.java
index 18e47883ce..cabba91d31 100644
--- a/compatibility-server/src/main/java/com/vaadin/v7/ui/Grid.java
+++ b/compatibility-server/src/main/java/com/vaadin/v7/ui/Grid.java
@@ -192,6 +192,9 @@ import elemental.json.JsonValue;
  *
  * @since 7.4
  * @author Vaadin Ltd
+ *
+ * @deprecated As of 8.0 replaced by {@link com.vaadin.ui.Grid} based on the new
+ *             data binding API
  */
 @Deprecated
 public class Grid extends AbstractComponent
diff --git a/compatibility-server/src/main/java/com/vaadin/v7/ui/HorizontalLayout.java b/compatibility-server/src/main/java/com/vaadin/v7/ui/HorizontalLayout.java
index 02dd385666..de5ae3ab38 100644
--- a/compatibility-server/src/main/java/com/vaadin/v7/ui/HorizontalLayout.java
+++ b/compatibility-server/src/main/java/com/vaadin/v7/ui/HorizontalLayout.java
@@ -30,7 +30,9 @@ import com.vaadin.ui.Component;
  *
  * @author Vaadin Ltd.
  * @since 5.3
- * @deprecated use com.vaadin.ui.HorizontalLayout (with different defaults)
+ *
+ * @deprecated Replaced in 8.0 with {@link com.vaadin.ui.HorizontalLayout} with
+ *             spacing on by default
  */
 @Deprecated
 public class HorizontalLayout extends com.vaadin.ui.HorizontalLayout {
diff --git a/compatibility-server/src/main/java/com/vaadin/v7/ui/InlineDateField.java b/compatibility-server/src/main/java/com/vaadin/v7/ui/InlineDateField.java
index 7c4e7e1721..84d9437740 100644
--- a/compatibility-server/src/main/java/com/vaadin/v7/ui/InlineDateField.java
+++ b/compatibility-server/src/main/java/com/vaadin/v7/ui/InlineDateField.java
@@ -18,6 +18,7 @@ package com.vaadin.v7.ui;
 
 import java.util.Date;
 
+import com.vaadin.ui.InlineDateTimeField;
 import com.vaadin.v7.data.Property;
 
 /**
@@ -30,6 +31,9 @@ import com.vaadin.v7.data.Property;
  * @see PopupDateField
  * @author Vaadin Ltd.
  * @since 5.0
+ *
+ * @deprecated As of 8.0, replaced by {@link com.vaadin.ui.InlineDateField} and
+ *             {@link InlineDateTimeField} based on LocalDate
  */
 @Deprecated
 public class InlineDateField extends DateField {
diff --git a/compatibility-server/src/main/java/com/vaadin/v7/ui/Label.java b/compatibility-server/src/main/java/com/vaadin/v7/ui/Label.java
index 559df24875..6b7f86be20 100644
--- a/compatibility-server/src/main/java/com/vaadin/v7/ui/Label.java
+++ b/compatibility-server/src/main/java/com/vaadin/v7/ui/Label.java
@@ -53,6 +53,9 @@ import com.vaadin.v7.shared.ui.label.LabelState;
  *
  * @author Vaadin Ltd.
  * @since 3.0
+ *
+ * @deprecated As of 8.0, replaced by {@link com.vaadin.ui.Label} that removes
+ *             data binding support
  */
 @SuppressWarnings("serial")
 @Deprecated
diff --git a/compatibility-server/src/main/java/com/vaadin/v7/ui/ListSelect.java b/compatibility-server/src/main/java/com/vaadin/v7/ui/ListSelect.java
index 1e776c4878..b5ae1cd396 100644
--- a/compatibility-server/src/main/java/com/vaadin/v7/ui/ListSelect.java
+++ b/compatibility-server/src/main/java/com/vaadin/v7/ui/ListSelect.java
@@ -25,6 +25,9 @@ import com.vaadin.v7.data.Container;
 /**
  * This is a simple list select without, for instance, support for new items,
  * lazyloading, and other advanced features.
+ *
+ * @deprecated As of 8.0 replaced by {@link com.vaadin.ui.ListSelect} based on
+ *             the new data binding API
  */
 @SuppressWarnings("serial")
 @Deprecated
diff --git a/compatibility-server/src/main/java/com/vaadin/v7/ui/NativeSelect.java b/compatibility-server/src/main/java/com/vaadin/v7/ui/NativeSelect.java
index a782956867..42f270619c 100644
--- a/compatibility-server/src/main/java/com/vaadin/v7/ui/NativeSelect.java
+++ b/compatibility-server/src/main/java/com/vaadin/v7/ui/NativeSelect.java
@@ -31,6 +31,9 @@ import com.vaadin.v7.event.FieldEvents;
  * multiselect, new items, lazyloading, and other advanced features. Sometimes
  * "native" select without all the bells-and-whistles of the ComboBox is a
  * better choice.
+ *
+ * @deprecated As of 8.0 replaced by {@link com.vaadin.ui.NativeSelect} based on
+ *             the new data binding API
  */
 @SuppressWarnings("serial")
 @Deprecated
diff --git a/compatibility-server/src/main/java/com/vaadin/v7/ui/OptionGroup.java b/compatibility-server/src/main/java/com/vaadin/v7/ui/OptionGroup.java
index 5a64b5a5ca..667149d0e9 100644
--- a/compatibility-server/src/main/java/com/vaadin/v7/ui/OptionGroup.java
+++ b/compatibility-server/src/main/java/com/vaadin/v7/ui/OptionGroup.java
@@ -41,10 +41,11 @@ import com.vaadin.v7.shared.ui.optiongroup.OptionGroupState;
 /**
  * Configures select to be used as an option group.
  *
- * @deprecated As of 8.0, use {@link RadioButtonGroup} or {@link CheckBoxGroup}
- *             instead
+ * @author Vaadin Ltd
+ *
+ * @deprecated As of 8.0, use {@link RadioButtonGroup} for single select or
+ *             {@link CheckBoxGroup} for multiselect instead
  */
-@SuppressWarnings("serial")
 @Deprecated
 public class OptionGroup extends AbstractSelect
         implements FieldEvents.BlurNotifier, FieldEvents.FocusNotifier {
diff --git a/compatibility-server/src/main/java/com/vaadin/v7/ui/PasswordField.java b/compatibility-server/src/main/java/com/vaadin/v7/ui/PasswordField.java
index cf00f64b8b..65dc1f8cda 100644
--- a/compatibility-server/src/main/java/com/vaadin/v7/ui/PasswordField.java
+++ b/compatibility-server/src/main/java/com/vaadin/v7/ui/PasswordField.java
@@ -25,6 +25,9 @@ import com.vaadin.v7.data.Property;
 /**
  * A field that is used to enter secret text information like passwords. The
  * entered text is not displayed on the screen.
+ *
+ * @deprecated As of 8.0 replaced by {@link com.vaadin.ui.PasswordField} based
+ *             on the new data binding API
  */
 @Deprecated
 public class PasswordField extends AbstractTextField {
diff --git a/compatibility-server/src/main/java/com/vaadin/v7/ui/PopupDateField.java b/compatibility-server/src/main/java/com/vaadin/v7/ui/PopupDateField.java
index 317fc30f45..52de405477 100644
--- a/compatibility-server/src/main/java/com/vaadin/v7/ui/PopupDateField.java
+++ b/compatibility-server/src/main/java/com/vaadin/v7/ui/PopupDateField.java
@@ -20,6 +20,7 @@ import java.util.Date;
 
 import com.vaadin.server.PaintException;
 import com.vaadin.server.PaintTarget;
+import com.vaadin.ui.DateTimeField;
 import com.vaadin.v7.data.Property;
 import com.vaadin.v7.shared.ui.datefield.PopupDateFieldState;
 
@@ -33,6 +34,9 @@ import com.vaadin.v7.shared.ui.datefield.PopupDateFieldState;
  * @see InlineDateField
  * @author Vaadin Ltd.
  * @since 5.0
+ *
+ * @deprecated As of 8.0, use {@link com.vaadin.ui.DateField} or
+ *             {@link DateTimeField} instead.
  */
 @Deprecated
 public class PopupDateField extends DateField {
diff --git a/compatibility-server/src/main/java/com/vaadin/v7/ui/ProgressBar.java b/compatibility-server/src/main/java/com/vaadin/v7/ui/ProgressBar.java
index 12b0286577..b23cf99097 100644
--- a/compatibility-server/src/main/java/com/vaadin/v7/ui/ProgressBar.java
+++ b/compatibility-server/src/main/java/com/vaadin/v7/ui/ProgressBar.java
@@ -33,6 +33,9 @@ import com.vaadin.v7.shared.ui.progressindicator.ProgressBarState;
  *
  * @since 7.1
  * @author Vaadin Ltd
+ *
+ * @deprecated As of 8.0 replaced by {@link com.vaadin.ui.ProgressBar} based on
+ *             the new data binding API
  */
 @Deprecated
 public class ProgressBar extends AbstractField<Float>
diff --git a/compatibility-server/src/main/java/com/vaadin/v7/ui/RichTextArea.java b/compatibility-server/src/main/java/com/vaadin/v7/ui/RichTextArea.java
index ca638a98da..3b6d4f7b5a 100644
--- a/compatibility-server/src/main/java/com/vaadin/v7/ui/RichTextArea.java
+++ b/compatibility-server/src/main/java/com/vaadin/v7/ui/RichTextArea.java
@@ -33,6 +33,9 @@ import com.vaadin.v7.shared.ui.textarea.RichTextAreaState;
  * Note, that using {@link TextField#setMaxLength(int)} method in
  * {@link RichTextArea} may produce unexpected results as formatting is counted
  * into length of field.
+ *
+ * @deprecated As of 8.0 replaced by {@link com.vaadin.ui.RichTextArea} based on
+ *             the new data binding API
  */
 @Deprecated
 public class RichTextArea extends AbstractField<String>
diff --git a/compatibility-server/src/main/java/com/vaadin/v7/ui/Slider.java b/compatibility-server/src/main/java/com/vaadin/v7/ui/Slider.java
index a898773f7c..9777677e4c 100644
--- a/compatibility-server/src/main/java/com/vaadin/v7/ui/Slider.java
+++ b/compatibility-server/src/main/java/com/vaadin/v7/ui/Slider.java
@@ -31,6 +31,9 @@ import com.vaadin.v7.shared.ui.slider.SliderState;;
  * A component for selecting a numerical value within a range.
  *
  * @author Vaadin Ltd.
+ *
+ * @deprecated As of 8.0 replaced by {@link com.vaadin.ui.Slider} based on the
+ *             new data binding API
  */
 @Deprecated
 public class Slider extends AbstractField<Double> {
diff --git a/compatibility-server/src/main/java/com/vaadin/v7/ui/Table.java b/compatibility-server/src/main/java/com/vaadin/v7/ui/Table.java
index ab5dcd62f0..0636768e2d 100644
--- a/compatibility-server/src/main/java/com/vaadin/v7/ui/Table.java
+++ b/compatibility-server/src/main/java/com/vaadin/v7/ui/Table.java
@@ -101,6 +101,8 @@ import com.vaadin.v7.shared.ui.table.TableState;
  *
  * @author Vaadin Ltd.
  * @since 3.0
+ *
+ * @deprecated As of 8.0, use Grid instead
  */
 @Deprecated
 @SuppressWarnings({ "deprecation" })
diff --git a/compatibility-server/src/main/java/com/vaadin/v7/ui/TableFieldFactory.java b/compatibility-server/src/main/java/com/vaadin/v7/ui/TableFieldFactory.java
index 676f2f6366..8bdec4ca66 100644
--- a/compatibility-server/src/main/java/com/vaadin/v7/ui/TableFieldFactory.java
+++ b/compatibility-server/src/main/java/com/vaadin/v7/ui/TableFieldFactory.java
@@ -32,6 +32,8 @@ import com.vaadin.v7.data.Container;
  * @author Vaadin Ltd.
  * @since 6.0
  * @see FormFieldFactory
+ *
+ * @deprecated As of 8.0, Table is replaced by Grid
  */
 @Deprecated
 public interface TableFieldFactory extends Serializable {
diff --git a/compatibility-server/src/main/java/com/vaadin/v7/ui/TextArea.java b/compatibility-server/src/main/java/com/vaadin/v7/ui/TextArea.java
index c635c0835c..84139030df 100644
--- a/compatibility-server/src/main/java/com/vaadin/v7/ui/TextArea.java
+++ b/compatibility-server/src/main/java/com/vaadin/v7/ui/TextArea.java
@@ -25,6 +25,9 @@ import com.vaadin.v7.shared.ui.textarea.TextAreaState;
 
 /**
  * A text field that supports multi line editing.
+ *
+ * @deprecated As of 8.0 replaced by {@link com.vaadin.ui.TextArea} based on the
+ *             new data binding API
  */
 @Deprecated
 public class TextArea extends AbstractTextField {
diff --git a/compatibility-server/src/main/java/com/vaadin/v7/ui/TextField.java b/compatibility-server/src/main/java/com/vaadin/v7/ui/TextField.java
index d7f9d07b0b..48bd2b77a5 100644
--- a/compatibility-server/src/main/java/com/vaadin/v7/ui/TextField.java
+++ b/compatibility-server/src/main/java/com/vaadin/v7/ui/TextField.java
@@ -40,6 +40,9 @@ import com.vaadin.v7.data.Property;
  *
  * @author Vaadin Ltd.
  * @since 3.0
+ *
+ * @deprecated As of 8.0 replaced by {@link com.vaadin.ui.TextField} based on
+ *             the new data binding API
  */
 @SuppressWarnings("serial")
 @Deprecated
diff --git a/compatibility-server/src/main/java/com/vaadin/v7/ui/Tree.java b/compatibility-server/src/main/java/com/vaadin/v7/ui/Tree.java
index dd0549f7b7..bb019e1b03 100644
--- a/compatibility-server/src/main/java/com/vaadin/v7/ui/Tree.java
+++ b/compatibility-server/src/main/java/com/vaadin/v7/ui/Tree.java
@@ -74,6 +74,8 @@ import com.vaadin.v7.shared.ui.tree.TreeState;
  *
  * @author Vaadin Ltd.
  * @since 3.0
+ *
+ * @deprecated As of 8.0. Replacement planned for 8.1
  */
 @SuppressWarnings({ "serial", "deprecation" })
 @Deprecated
diff --git a/compatibility-server/src/main/java/com/vaadin/v7/ui/TreeTable.java b/compatibility-server/src/main/java/com/vaadin/v7/ui/TreeTable.java
index e5b18472e8..df471d5973 100644
--- a/compatibility-server/src/main/java/com/vaadin/v7/ui/TreeTable.java
+++ b/compatibility-server/src/main/java/com/vaadin/v7/ui/TreeTable.java
@@ -66,6 +66,8 @@ import com.vaadin.v7.ui.Tree.ExpandListener;
  * standard Hierarchical implementations. Developer must however note that
  * {@link Collapsible} containers can not be shared among several users as they
  * share UI state in the container.
+ *
+ * @deprecated As of 8.0. Replacement planned for 8.1
  */
 @SuppressWarnings({ "serial" })
 @Deprecated
diff --git a/compatibility-server/src/main/java/com/vaadin/v7/ui/TwinColSelect.java b/compatibility-server/src/main/java/com/vaadin/v7/ui/TwinColSelect.java
index 50d9e60bb6..d1ddaa4f08 100644
--- a/compatibility-server/src/main/java/com/vaadin/v7/ui/TwinColSelect.java
+++ b/compatibility-server/src/main/java/com/vaadin/v7/ui/TwinColSelect.java
@@ -27,6 +27,9 @@ import com.vaadin.v7.shared.ui.twincolselect.TwinColSelectState;
 /**
  * Multiselect component with two lists: left side for available items and right
  * side for selected items.
+ *
+ * @deprecated As of 8.0 replaced by {@link com.vaadin.ui.TwinColSelect} based
+ *             on the new data binding API
  */
 @SuppressWarnings("serial")
 @Deprecated
diff --git a/compatibility-server/src/main/java/com/vaadin/v7/ui/Upload.java b/compatibility-server/src/main/java/com/vaadin/v7/ui/Upload.java
index 20348c206f..a1f987b55e 100644
--- a/compatibility-server/src/main/java/com/vaadin/v7/ui/Upload.java
+++ b/compatibility-server/src/main/java/com/vaadin/v7/ui/Upload.java
@@ -73,6 +73,9 @@ import com.vaadin.v7.shared.ui.upload.UploadState;
  *
  * @author Vaadin Ltd.
  * @since 3.0
+ *
+ * @deprecated As of 8.0 replaced by {@link com.vaadin.ui.Upload} that is by
+ *             default in immediate mode.
  */
 @SuppressWarnings("serial")
 @Deprecated
diff --git a/compatibility-server/src/main/java/com/vaadin/v7/ui/VerticalLayout.java b/compatibility-server/src/main/java/com/vaadin/v7/ui/VerticalLayout.java
index 3d56dc5827..cb5fea1178 100644
--- a/compatibility-server/src/main/java/com/vaadin/v7/ui/VerticalLayout.java
+++ b/compatibility-server/src/main/java/com/vaadin/v7/ui/VerticalLayout.java
@@ -31,7 +31,9 @@ import com.vaadin.ui.Component;
  *
  * @author Vaadin Ltd.
  * @since 5.3
- * @deprecated use com.vaadin.ui.VerticalLayout (with different defaults)
+ *
+ * @deprecated Replaced in 8.0 with {@link com.vaadin.ui.VerticalLayout} with
+ *             margin and spacing on by default
  */
 @Deprecated
 public class VerticalLayout extends com.vaadin.ui.VerticalLayout {
diff --git a/documentation/migration/migrating-to-vaadin8.asciidoc b/documentation/migration/migrating-to-vaadin8.asciidoc
index b39bc8ec1a..0a351240ab 100644
--- a/documentation/migration/migrating-to-vaadin8.asciidoc
+++ b/documentation/migration/migrating-to-vaadin8.asciidoc
@@ -3,7 +3,6 @@ title: Migrating to Framework 8
 order: 1
 layout: page
 ---
-// TODO: Fix release note links to point to 8.0.0
 [[migration]]
 == Migration from Framework 7 to Framework 8
 
@@ -17,7 +16,7 @@ This is primarily to get an existing Framework 7 project up and running with Fra
 
 The very first step in migration is to ensure that your project is configured to use Framework 8 dependencies, as well as include any of the desired compatibility packages needed in your migration.
 Also note that Framework 8 requires JDK 8 for development.
-For deployment configurations, refer to the list of supported technologies in the release notes, available at link:https://vaadin.com/download/prerelease/8.0/8.0.0/8.0.0.beta1/release-notes.html#supportedversions[].
+For deployment configurations, refer to the list of supported technologies in the release notes, available at link:https://vaadin.com/download/release/8.0/8.0.0/release-notes.html#supportedversions[].
 
 ==== Updating Maven Dependencies
 
@@ -76,6 +75,12 @@ For add-on developers, the same steps outlined in this guide can also be applied
 Once your project's dependencies have been updated for Framework 8 migration there are a few steps to begin using the compatibility versions of the old APIs, namely changing of imports and ensuring that your widgetset is correctly set up.
 Optionally, if you are using Vaadin Designer or declarative files otherwise, the tag names for compatibility components need to be updated.
 
+==== The Migration Tool
+
+To ease the migration process, the vaadin maven plugin has a target `vaadin:upgrade8` which updates all
+imports in java files and prefixes in design files to point to the versions in the compatibility packages.
+This migration tool is available separately at link:https://github.com/vaadin/framework8-migration-tool[].
+
 ==== Changing Imports
 
 The only change to classes in the compatibility packages is the change in their classpath. All compatibility classes can be found under `com.vaadin.v7.*`.
@@ -89,6 +94,9 @@ Typically, widgetset recompilation will handle this automatically for you, excep
 * Your project defines a custom widgetset, in which case you need to make sure `Vaadin7WidgetSet` is inherited
 * An UI in your project defines its widgetset with the annotation `@WidgetSet("com.vaadin.DefaultWidgetSet")`, which should be changed to `@WidgetSet("com.vaadin.v7.Vaadin7WidgetSet")`
 
+IMPORTANT: The widgetset compilation for `Vaadin7WidgetSet` requires at least 1G of memory. To ensure this, add
+`<extraJvmArgs>-Xmx1G</extraJvmArgs>` to the vaadin-maven-plugin configuration in your `pom.xml` file.
+
 ==== Using Compatibility Components In Declarative Files
 
 Using components from the compatibility packages in your declarative files only requires you to change the prefix from `vaadin-` or alternatively `v-` to `vaadin7-`.
@@ -106,10 +114,6 @@ to its compatibility equivalent, `com.vaadin.v7.ui.TextField`, would simply be a
 
 in the corresponding design html file.
 
-==== The Migration Tool
-
-To ease the process of the initial changing of imports and prefixes in design files, a tool for automatically applying these changes to a project is available at link:https://github.com/vaadin/framework8-migration-tool[].
-Please refer to the README available in the repository for up to date instructions on how to run the tool on your project.
 
 === Next Steps