From 45554fd5c5c6a536db3ce70d78646d3dc398cf08 Mon Sep 17 00:00:00 2001
From: David Vaz <davidmgvaz@gmail.com>
Date: Thu, 26 Sep 2019 10:39:36 -0700
Subject: [PATCH] Fixed #30597 -- Clarified how to unapply migrations.

---
 docs/ref/django-admin.txt  |  4 ++--
 docs/topics/migrations.txt | 24 ++++++++++++++++++++++++
 2 files changed, 26 insertions(+), 2 deletions(-)

diff --git a/docs/ref/django-admin.txt b/docs/ref/django-admin.txt
index 690ca76ba4..7927b89e63 100644
--- a/docs/ref/django-admin.txt
+++ b/docs/ref/django-admin.txt
@@ -802,8 +802,8 @@ The behavior of this command changes depending on the arguments provided:
 * ``<app_label> <migrationname>``: Brings the database schema to a state where
   the named migration is applied, but no later migrations in the same app are
   applied. This may involve unapplying migrations if you have previously
-  migrated past the named migration. Use the name ``zero`` to unapply all
-  migrations for an app.
+  migrated past the named migration. Use the name ``zero`` to migrate all the
+  way back i.e. to revert all applied migrations for an app.
 
 .. warning::
 
diff --git a/docs/topics/migrations.txt b/docs/topics/migrations.txt
index be14d8b8e2..65f6b7cfef 100644
--- a/docs/topics/migrations.txt
+++ b/docs/topics/migrations.txt
@@ -347,6 +347,30 @@ Note that this only works given two things:
   that your database doesn't match your models, you'll just get errors when
   migrations try to modify those tables.
 
+Reverting migrations
+====================
+
+Any migration can be reverted with :djadmin:`migrate` by using the number of
+previous migrations::
+
+    $ python manage.py migrate books 0002
+    Operations to perform:
+      Target specific migration: 0002_auto, from books
+    Running migrations:
+      Rendering model states... DONE
+      Unapplying books.0003_auto... OK
+
+If you want to revert all migrations applied for an app, use the name
+``zero``::
+
+    $ python manage.py migrate books zero
+    Operations to perform:
+      Unapply all migrations: books
+    Running migrations:
+      Rendering model states... DONE
+      Unapplying books.0002_auto... OK
+      Unapplying books.0001_initial... OK
+
 .. _historical-models:
 
 Historical models