Updated migration related documentation (#8602)

* Updated migration related documentation

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

Fixes #8581

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() {

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> {
 

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 {

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 {

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

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>

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

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

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 {

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 {

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

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

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

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 {

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 {

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 {

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>

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>

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> {

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" })

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 {

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 {

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

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

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

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

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

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 {

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