Add comments to manage-projects about project-config syncing

There were questions around project-config syncing and the way it is
done in manage-projects during our last project renaming. I've since
read through teh code to try and understand things better and have added
comments to manage-projects.yaml indicating the risks here and why we
approach it the way we do. There is no functional change only an attempt
at better understanding for the future.

Change-Id: I60aa58a36108edce3e00ecf2ac10be3dee7e8ea0

playbooks/manage-projects.yaml

@@ -1,3 +1,23 @@
+# Note that we don't do a sync-project-config before gitea-git-repos
+# because sync-project-config's primary purpose is to update
+# /opt/project-config on the remote host. review.o.o needs this to be
+# updated as jeepyb executes there against the local checkout.
+# gitea-git-repos runs against the project-config on bridge which has
+# already been synced from Zuul to bridge by Zuul.
+#
+# sync-project-config does update project-config from master rather than
+# the Zuul state when run in a periodic or opendev-prod-hourly pipelines
+# but this playbook is never run in those pipelines. It only runs in deploy
+# in response to merged changes.
+#
+# This does mean that we need to be careful landing sequences of changes
+# to rename projects as only the last one in the series should actually
+# run this playbook. Historically, we've avoided problems because Zuul
+# hasn't been able to run post merge jobs at all for intermediate changes
+# after a rename. Only the last change has been in a consistent state
+# which ends up running this playbook. This has mostly been done by chance
+# rather than intentionally and we should take care going forward to not
+# get this wrong.
 - hosts: "gitea:!disabled"
   name: "Create repos on gitea servers"
   roles: