[1.8.x] Fixed #23892 -- Clarified compatibility policy for migrations.

Backport of e35c70bef44805d47f6a4ae692be878184c4fe1f from master

1 files changed, 14 insertions, 0 deletions

diff --git a/docs/topics/migrations.txt b/docs/topics/migrations.txt
index d23dee7a90..304306aed7 100644
--- a/docs/topics/migrations.txt
+++ b/docs/topics/migrations.txt
@@ -750,6 +750,20 @@ next run of :djadmin:`makemigrations` on Python 3 will likely generate many
 changes as it converts all the bytestring attributes to text strings; this is
 normal and should only happen once.
 
+Supporting multiple Django versions
+-----------------------------------
+
+If you are the maintainer of a third-party app with models, you may need to
+ship migrations that support multiple Django versions. In this case, you should
+always run :djadmin:`makemigrations` **with the lowest Django version you wish
+to support**.
+
+The migrations system will maintain backwards-compatibility according to the
+same policy as the rest of Django, so migration files generated on Django X.Y
+should run unchanged on Django X.Y+1. The migrations system does not promise
+forwards-compatibility, however. New features may be added, and migration files
+generated with newer versions of Django may not work on older versions.
+
 .. _upgrading-from-south:
 
 Upgrading from South