Update docs and add a warning block for this function

Author: milmazz

lib/ecto/migration.ex

@@ -1273,13 +1273,44 @@ defmodule Ecto.Migration do
 
   See `add/3` for more information on supported types.
 
-  If you want to modify a column without changing its type,
-  such as adding or dropping a null constraints, consider using
-  the `execute/2` command with the relevant SQL command instead
-  of `modify/3`, if supported by your database. This may avoid
-  redundant type updates and be more efficient, as an unnecessary
-  type update can lock the table, even if the type actually
-  doesn't change.
+  > #### Modifying a column without changing its type {: .warning}
+  >
+  > If you want to modify a column without changing its type,
+  > such as adding or dropping a null constraints, consider using
+  > the `execute/2` command with the relevant SQL command instead
+  > of `modify/3`, if supported by your database. This may avoid
+  > redundant type updates and be more efficient, as an unnecessary
+  > type update can lock the table, even if the type actually
+  > doesn't change.
+  >
+  > We have considered changing the column type even when it is not needed
+  > could lead to undesirable locks, that's why, at least in the PostgreSQL
+  > adapter, if you provide the option `:from`, and the type matches, we
+  > will avoid changing the type.
+  >
+  > Examples
+  >
+  >     # modify column with rollback options
+  >     alter table("posts") do
+  >       modify :title, :text, null: false, from: {:text, null: true}
+  >     end
+  >
+  >     # adding a new foreign key constraint
+  >     alter table("posts") do
+  >       modify :author_id, references(:authors, type: :id), from: :id
+  >     end
+  >
+  >     # Modify the :on_delete option of an existing foreign key
+  >     alter table("comments") do
+  >       modify :post_id, references(:posts, on_delete: :delete_all),
+  >         from: references(:posts, on_delete: :nothing)
+  >     end
+  >
+  >
+  > The previous syntax will offer two benefits, at least in the PostgreSQL adapter,
+  > the migration is reversible and if the column type remains the same, the column
+  > type update will be skipped.
+
 
   ## Examples