Add documentation about Pagure interactions

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

docs/pagure2gitlab/index.rst

@@ -1,4 +1,4 @@
-Pagure to Gitlab Importer
+Pagure to GitLab Importer
 =========================
 
 Purpose
@@ -28,7 +28,6 @@ Requirements
 * Tool should be usable by both CentOS and Fedora users
 * Ability to access the correct namespace on GitLab
 
-
 Nice to have
 ------------
 

docs/pagure2gitlab/pagure.rst

@@ -1,4 +1,122 @@
 .. _pagure:
 
-Pagure export options
+Exporting Namespace Assets From Pagure
-=====================
+====
+
+A lot of projects related to Fedora Project and CentOS Project reside in Pagure
+which makes it important for us to understand the ways they can be interacted 
+with and moved around when the need arises. 
+
+Elements for interaction
+----
+
+In this context, we are looking into interacting with the following elements -
+
+Issue tickets
+^^^^
+
+These can either be requests for adding new features, reporting of a bug, 
+proposal of an idea or anything else. These need to be available in the place 
+where the namespace assets get transferred to, in order to retain the context
+around the probable action items.
+
+Repository assets
+^^^^
+
+These are the actual files stored in the Git repository that pertains to the 
+actual project. This can either be a codebase, a collection of documentation, 
+a group of artworks or anything else. This happens to be the primary subject 
+for the transfer.
+
+We are avoiding interacting with the following elements -
+
+Pull requests
+^^^^
+
+Not only does it require for the pull requests to be artificially created by a 
+stub user (say, a bot user of some kind as we cannot guarantee the availability
+of the GitLab user pertaining to the related Pagure user) in the destination 
+namespace but it also needs the source of the pull request (which can either be
+a fork of the source namespace of a branch inside the same repository) to be 
+available, which might not always be the case. We strongly recommend merging 
+all pending pull requests that are needed and closing those that are not, 
+before the transfer process begins.
+
+Ways of interaction
+----
+
+The elements that we would want to interact with, can be done so using the 
+following ways.
+
+Issue tickets
+^^^^
+
+* *Pagure API*
+  
+  This provides an `extensive method <https://pagure.io/api/0/>`_ to `interact 
+  with the issue tickets <https://pagure.io/api/0/#issues-tab>`_ pertaining to 
+  a certain source namespace. This can be expanded upon to receive information 
+  like issue title, issue content, assignees, tags, creation date, modified 
+  date, comments etc. Depending on what information and how much amount of it 
+  is requested from the API server, the interactions can be done quickly too, 
+  paving the way for automation. The service does not seem to have rate 
+  limiting too and hence, can be used without worry for interacting with bigger
+  repositories.
+
+  * *The good*
+    
+    * A well structured API query with limited scope can ensure that multiple
+      requests are made and addressed quickly.
+    * This does not require any local storage space to be available in order to
+      make requests, unless caching is employed.
+  
+  * *The bad*
+    
+    * Extra assets bound to the issue ticket like images, documentation, media 
+      files etc. cannot be reliably accessed.
+    * Service can be slow at times, leading to timeouts and hence, a condition
+      to address those during automation is needed.
+
+* *Issues Git URL*
+  
+  For the users that have a commit access to a certain source namespace, they 
+  should be able to see an option for listing "Other Git URLs" on the project 
+  page. Although Pagure provides methods to clone both "Issues" and "Pull 
+  Requests" using those special Git URLs, we would only talk about that for the
+  former. For instance, the folks having a commit access to the 
+  `fedora-websites <https://pagure.io/fedora-websites>`_ repository should be 
+  able to access the issue tickets using the URL 
+  `ssh://git@pagure.io/tickets/fedora-websites.git <ssh://git@pagure.io/tickets/fedora-websites.git>`_.
+
+  * *The good*
+    
+    * A clone of the issues repository can help receive all the issue tickets
+      ever created in one fell swoop.
+    * Extra assets bound to the issue ticket like images, documentation, media
+      files etc. can be reliably accessed.
+
+  * *The bad*
+    
+    * It can take a long time to fetch the issues repository in its entirety if
+      the repository has had too many of those.
+    * This mandatorily requires the use of a local storage space to be able to
+      clone and make changes locally before publish.
+
+Repository assets
+^^^^
+
+* *Default Git URL*
+  
+  Folks can access the repository assets of the source namespace using the 
+  default Git URL. Depending on the availability of the API keys for the users,
+  they can choose to either interact with the repository assets with the use of
+  either the HTTPS URL (for example, it would be 
+  `https://pagure.io/fedora-websites.git <https://pagure.io/fedora-websites.git>`_
+  for the fedora-websites source namespace) or the SSH URL (for example, it 
+  would be 
+  `ssh://git@pagure.io/fedora-websites.git <ssh://git@pagure.io/fedora-websites.git>`_
+  for the fedora-websites source namespace). We would not go in detail with the
+  advantages and disadvantages of this method as there seems to be only one way
+  to interact with repository assets.
+
+