Small improvements to style guide.

1 files changed, 6 insertions, 3 deletions

diff --git a/doc/development/migration_style_guide.md b/doc/development/migration_style_guide.md
index db2d8b99721..a102d7987de 100644
--- a/doc/development/migration_style_guide.md
+++ b/doc/development/migration_style_guide.md
@@ -1,17 +1,20 @@
 # Migration Style Guide
 
 When writing migrations for GitLab, you have to take into account that
-these will be ran by thousands of organizations of all sizes, some with
+these will be ran by hundreds of thousands of organizations of all sizes, some with
 many years of data in their database.
 
 In addition, having to take a server offline for a an upgrade small or big is
 a big burden for most organizations. For this reason it is important that your
-migrations are written carefully and adhere to the style guide below.
+migrations are written carefully, can be applied online and adhere to the style guide below.
 
 When writing your migrations, also consider that databases might have stale data
 or inconsistencies and guard for that. Try to make as little assumptions as possible
 about the state of the database.
 
+Please don't depend on GitLab specific code since it can change in future versions.
+If needed copy-paste GitLab code into the migration to make make it forward compatible.
+
 ## Comments in the migration
 
 Each migration you write needs to have the two following pieces of information
@@ -36,4 +39,4 @@ Your migration should be reversible. This is very important, as it should
 be possible to downgrade in case of a vulnerability or bugs.
 
 In your migration, add a comment describing how the reversibility of the
-migration was tested.
+migration was tested.
\ No newline at end of file