[dist-git-move] add monitor-gating document

Signed-off-by: Ryan Lerch <rlerch@redhat.com>

docs/dist-git-move/index.rst

@@ -52,6 +52,7 @@ Index
     pagure
     toddlers
     messaging
+    monitorgating
 
 Conclusions
 ----

docs/dist-git-move/monitorgating.rst

@@ -0,0 +1,98 @@
+.. _monitorgating:
+
+##################################################
+ Pagure Dist Git Interactions With Monitor Gating
+##################################################
+
+`Monitor Gating <https://pagure.io/fedora-ci/monitor-gating>`_ is a set
+of scripts that is used to test if `Fedora CI Gating
+<https://docs.fedoraproject.org/en-US/ci/gating/>`_ is working as
+expected. It essentially follows a typical workflow of cloning a package
+from dist-git, rebuild it in koji, create a update in bodhi, then checks
+that the CI runs, and the build is gated appropriately.
+
+***********************
+ Possible Interactions
+***********************
+
+The following are a set of documented interactions possible between
+Pagure Dist Git and Monitor Gating.
+
+git and fedpkg CLI
+==================
+
+**cloning a repo**
+   Monitor Gating uses ``fedpkg clone`` to clone a repo from dist-git.
+
+   `utils.py#_107
+   <https://pagure.io/fedora-ci/monitor-gating/blob/production/f/monitor_gating/utils.py#_107>`_
+
+**adding a remote**
+   Monitor Gating uses ``git remote add`` to add a fork on dist-git as a
+   remote on a cloned dist-git repo.
+
+   `utils.py#_136
+   <https://pagure.io/fedora-ci/monitor-gating/blob/production/f/monitor_gating/utils.py#_136>`_
+
+**switching branches**
+   Monitor Gating uses ``fedpkg switch-branch`` to switch branches on a
+   dist-git cloned repo.
+
+   `utils.py#_149
+   <https://pagure.io/fedora-ci/monitor-gating/blob/production/f/monitor_gating/utils.py#_149>`_
+
+**git pull, push, commit**
+   Monitor Gating uses ``git commit``, ``git pull```, and ``git push``
+   to get and make changes to a dist-git repo.
+
+   `utils.py#_175-212
+   <https://pagure.io/fedora-ci/monitor-gating/blob/production/f/monitor_gating/utils.py#_175-212>`_
+
+dist-git (pagure) API
+=====================
+
+**CI status**
+   Monitor gating currently gets the status of the CI run(s) on a pull
+   request using the get PR flags endpoint
+   (``api/0/<namespace>/<name>/pull-request/<pr-id>/flag``).
+
+   `utils.py#_636
+   <https://pagure.io/fedora-ci/monitor-gating/blob/production/f/monitor_gating/utils.py#_636>`_
+
+**open pull request**
+   Monitor Gating opens new Pull Requests on dist-git using the pagure
+   API (``api/0/<namespace>/<name>/pull-request/new``)
+
+   `utils.py#_214
+   <https://pagure.io/fedora-ci/monitor-gating/blob/production/f/monitor_gating/utils.py#_214>`_
+
+**merge pull request**
+   Monitor Gating merges Pull Requests on dist-git using the pagure API
+   (``api/0/<namespace>/<name>/pull-request/<pr-id>/merge``)
+
+   `utils.py#_691
+   <https://pagure.io/fedora-ci/monitor-gating/blob/production/f/monitor_gating/utils.py#_691>`_
+
+******************
+ Changes proposed
+******************
+
+In order to switch out Pagure Dist Git for an alternative that provides
+a relatively compatible API pattern, the following changes must be made
+in the places mentioned below.
+
+Necessary
+=========
+
+-  The changes made to the Continuous Integration component with regards
+   to the reporting of CI status need to be updated in monitor gating.
+   Currently dist-git uses the pagure flags system.
+
+-  Monitor Gating will need to be updated to support Opening and Merging
+   pull requests on the new solution
+
+Unnecessary
+===========
+
+-  No changes should be needed for the basic git / fedpkg commands.
+   (this is based on the assumption the new solution is based on git)