[P2F] Add investigation for migrating issue tickets

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

docs/pagure2forgejo/tkts.rst

@@ -0,0 +1,111 @@
+.. _tkts:
+
+Migrating issue tickets
+=======================
+
+This document investigates the necessary methods required to migrate issue 
+tickets from the source namespace on Pagure to the destination namespace on
+Forgejo. As both Pagure and Forgejo support REST API, I will focus on using
+that to conveniently automate the migration process.
+
+Exporting issue tickets from Pagure
+-----------------------------------
+
+As this has already been covered
+`here <https://fedora-arc.readthedocs.io/en/latest/pagure2gitlab/pagureinfo.html>`_,
+it will not be documented again. Please feel free to open an issue ticket
+or a pull request against the namespace if more information is sought about
+this.
+
+Importing issue tickets into Forgejo
+------------------------------------
+
+The Forgejo API follows the REST standard and is documented with the OpenAPI
+or Swagger format, making it incredibly easy for developers to understand the
+behaviour of Forgejo API. The documentation is also interactive in nature and
+it is highly recommended for folks to take it for a spin with the required
+correct credentials.
+
+The following items are considered within the scope for the migration.
+
+- *Issue ticket title and body*
+
+- *Labels associated with the issue tracker*
+
+- *Milestones associated with the issue tracker*
+
+- *User information like creator and assignee*
+
+- *Status of the issue ticket*
+
+- *Comments under the issue ticket*
+
+The following items are considered beyond the scope for the migration.
+
+- *Reactions to issue tickets*
+
+  While it is convenient to create reactions under an issue ticket in a
+  destination namespace on a Forgejo deployment, it is tricky to retrieve
+  that information from the source namespace on a Pagure deployment.
+  Reactions can also be retracted at any given point in time from under
+  an issue ticket, making them an unreliable communication medium,
+  regardless of how convenient they can be to the users.
+
+- *Reactions to comments*
+
+  While it is convenient to create reactions under a comment entry in a
+  destination namespace on a Forgejo deployment, it is tricky to retrieve
+  that information from the source namespace on a Pagure deployment.
+  Reactions can also be retracted at any given point in time from under
+  a comment entry, making them an unreliable communication medium,
+  regardless of how convenient they can be to the users.
+
+The following items are considered nice to haves for the migration.
+
+- *Attachments to issue tickets*
+
+  Pagure maintains an alternative Git repository for storing attachments
+  associated with issue tickets in the source namespace and Forgejo provides
+  means to upload them in the destination namespace using the REST API. It
+  can however be tricky to scan the body of an issue ticket to discern these
+  assets from the source and reinstate them at the destination on a case by
+  case basis. I understand the importance of this though so an attempt will
+  be made to implement this after all the core requirements are fulfilled.
+
+- *Attachments to comments*
+
+  Pagure maintains an alternative Git repository for storing attachments
+  associated with comment entries in the source namespace and Forgejo provides
+  means to upload them in the destination namespace using the REST API. It
+  can however be tricky to scan the body of an comment entry to discern these
+  assets from the source and reinstate them at the destination on a case by
+  case basis. I understand the importance of this though so an attempt will
+  be made to implement this after all the core requirements are fulfilled.
+
+Some caveats
+~~~~~~~~~~~~
+
+- Labels and milestones have to created in the destination namespace before they
+  can be associated with an issue ticket as the request body makes use of lists of
+  Label ID and Milestone ID for validation.
+
+- A separate dictionary needs to be maintained for mapping label names from the
+  source namespace with the label identifiers at the destination namespace to ensure
+  consistency in the information migrated.
+
+- A separate dictionary needs to be maintained for mapping milestone names from
+  the source namespace with the milestone identifiers at the destination namespace to
+  ensure consistency in the information migrated.
+
+- At the moment, Forgejo does not support the creation of an issue ticket with a
+  custom identifier which means that ensuring an empty issue tracker in the destination
+  namespace is mandatory for smooth functioning.
+
+- At the moment, Forgejo does not support the creation of private issue tickets,
+  and hence, migration of certain repositories that make use private issue tickets,
+  would have to be held back or made to GitLab.
+
+- As mentioned above, discerning attachments from issue tickets and comment entries
+  to effectively replace their placeholders with the changed URLs at the destination
+  namespace would be an interesting problem.
+