diff --git a/doc/source/gerrit.rst b/doc/source/gerrit.rst
index dd5728ec75..e29ec60484 100644
--- a/doc/source/gerrit.rst
+++ b/doc/source/gerrit.rst
@@ -432,6 +432,8 @@ To rename a project:
      repos:
      - old: stackforge/awesome-repo
        new: openstack/awesome-repo
+     - old: openstack/foo
+       new: openstack/bar
      gerrit_groups:
      - old: old-core-group
        new: new-core-group
@@ -472,6 +474,11 @@ To rename a project:
 
      sudo crontab -u root -e
 
+   .. warning::
+      Wait for the ``project-config`` changes to merge before
+      re-enabling cron, else duplicate projects can appear that have
+      to be manually removed.
+
 #. Submit a change that updates .gitreview with the new location of the
    project.