Add documentation for FMN interactions

Signed-off-by: Akashdeep Dhar <akashdeep.dhar@gmail.com>

docs/dist-git-move/index.rst

@@ -37,6 +37,14 @@ Requirements
 * Include additions to **Pagure** to support interactions with another platform
 * Include additions to **Anitya/The New Hotness** to support interactions with another platform
 
+Index
+----
+
+.. toctree::
+    :maxdepth: 1
+
+    notifications
+
 Conclusions
 ----
 

docs/dist-git-move/notifications.rst

@@ -0,0 +1,105 @@
+.. _notifications:
+
+Pagure Dist Git Interactions With Fedora Notifications
+====
+
+Fedora Messaging Notifier is a family of systems to manage end-user
+notifications triggered by
+`Fedora Messaging <https://fedora-messaging.readthedocs.io/>`_ and it provides
+a single place for all applications using Fedora Messaging to notify users of
+events.
+
+Possible Interactions
+----
+
+The following are a set of documented interactions possible between Pagure Dist
+Git and Fedora Notifications.
+
+Artifact Details
+^^^^
+
+- Fedora Notifications receives information about the permissions related to
+  a certain asset (which can be a package) from Pagure Dist Git. It receives
+  information about the assets (which can be a package) that a user or a group
+  has access to.
+- Fedora Notifications provide its users with **artifact details** via an HTTP
+  GET endpoint that it retrieves from Pagure Dist Git. For more information,
+  please check the
+  `function definition <https://github.com/fedora-infra/fmn/blob/develop/fmn/api/handlers/misc.py#L55>`_
+  provided here.
+- The inputs required by the Fedora Notifications service to perform this
+  operation are *name patterns of artifacts to be returned*,
+  *name of the users whose artifacts are to be returned*, and
+  *name of the groups whose artifacts are to be returned*.
+- This endpoint makes use of a
+  `FastAPI dependency <https://fastapi.tiangolo.com/tutorial/dependencies/>`_
+  called ``get_distgit_proxy``, more information related to which can be found
+  `here <https://github.com/fedora-infra/fmn/blob/develop/fmn/backends/pagure.py#L284>`_.
+
+The ``PagureAsyncProxy`` class
+^^^^
+
+- The URL of the existing Pagure Dist Git production deployment is referenced
+  here to instantiate an object of type ``PagureAsyncProxy`` class. For more
+  information, please check the
+  `method definition <https://github.com/fedora-infra/fmn/blob/develop/fmn/backends/pagure.py#L69>`_
+  provided here.
+- The
+  `method definition <https://github.com/fedora-infra/fmn/blob/develop/fmn/backends/pagure.py#L72>`_
+  for **determining the next page parameters** is provided here. This is
+  extensively used for recursively navigating through the Pagure Dist Git
+  `API <https://pagure.io/api/0>`_ results.
+- The
+  `method definition <https://github.com/fedora-infra/fmn/blob/develop/fmn/backends/pagure.py#L86>`_
+  for **retrieving project details** is provided here. This is dependent on
+  the values provided for the ``namespace``, ``pattern``, ``username`` and
+  ``owner`` parameters.
+- The
+  `method definition <https://github.com/fedora-infra/fmn/blob/develop/fmn/backends/pagure.py#L115>`_
+  for **retrieving project details associated with a certain user** is provided
+  here. This is dependent on the values provided for the ``username``
+  parameter.
+- The
+  `method definition <https://github.com/fedora-infra/fmn/blob/develop/fmn/backends/pagure.py#L157>`_
+  for **retrieving project details associated with a certain project** is
+  provided here. This is dependent on the values for the ``name`` parameter.
+- The
+  `method definition <https://github.com/fedora-infra/fmn/blob/develop/fmn/backends/pagure.py#L127>`_
+  for **retrieving user details associated with a certain project** is provided
+  here. This is dependent on the values provided for the ``project_path``
+  parameter.
+- The
+  `method definition <https://github.com/fedora-infra/fmn/blob/develop/fmn/backends/pagure.py#L142>`_
+  for **retrieving group details associated with a certain project** is provided
+  here. This is dependent on the values provided for the ``project_path``
+  parameter.
+
+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
+placed mentioned below.
+
+Necessary
+^^^^
+
+- The Pagure Dist Git URL production deployment URL would have to change to
+  point towards the production deployment URL of the alternative. This
+  `method definition <https://github.com/fedora-infra/fmn/blob/develop/fmn/backends/pagure.py#L285>`_
+  is where the URL is formatted to point towards the API.
+- The method ``get_api_url`` has to be redefined depending on what the URL
+  pattern is for the alternative place where we move Pagure Dist Git assets to.
+  Here is the
+  `method definition <https://github.com/fedora-infra/fmn/blob/develop/fmn/backends/pagure.py#L69>`_
+  of where the changes need to be made.
+
+Unnecessary
+^^^^
+
+- The ``APIClient`` class that is inherited by the ``PagureAsyncProxy`` class is
+  agnostic to the place where the assets are hosted so changing over from
+  Pagure Dist Git to an alternative would not necessitate a reworking while
+  checking for compatibilities is strongly recommended. The
+  `method definition <https://github.com/fedora-infra/fmn/blob/develop/fmn/backends/base.py#L39>`_
+  can be found here.