1 files changed, 24 insertions, 4 deletions
diff --git a/doc/development/migration_style_guide.md b/doc/development/migration_style_guide.md
index 3f202115b4c..776ac252b76 100644
--- a/doc/development/migration_style_guide.md
+++ b/doc/development/migration_style_guide.md
@@ -176,9 +176,15 @@ Removing a column:
 ```ruby
 include Gitlab::Database::MigrationHelpers
 
-def change
+def up
   with_lock_retries do
-    remove_column :users, :full_name, :string
+    remove_column :users, :full_name
+  end
+end
+
+def down
+  with_lock_retries do
+    add_column :users, :full_name, :string
   end
 end
 ```
@@ -188,11 +194,17 @@ Removing a foreign key:
 ```ruby
 include Gitlab::Database::MigrationHelpers
 
-def change
+def up
   with_lock_retries do
     remove_foreign_key :issues, :projects
   end
 end
+
+def down
+  with_lock_retries do
+    add_foreign_key :issues, :projects
+  end
+end
 ```
 
 Changing default value for a column:
@@ -200,11 +212,17 @@ Changing default value for a column:
 ```ruby
 include Gitlab::Database::MigrationHelpers
 
-def change
+def up
   with_lock_retries do
     change_column_default :merge_requests, :lock_version, from: nil, to: 0
   end
 end
+
+def down
+  with_lock_retries do
+    change_column_default :merge_requests, :lock_version, from: 0, to: nil
+  end
+end
 ```
 
 ### When to use the helper method
@@ -231,6 +249,8 @@ Example changes:
 
 **Note:** `with_lock_retries` method **cannot** be used with `disable_ddl_transaction!`.
 
+**Note:** `with_lock_retries` method **cannot** be used within the `change` method, you must manually define the `up` and `down` methods to make the migration reversible.
+
 ### How the helper method works
 
 1. Iterate 50 times.