From 7e9e52ec780848238e22e7b4c48eaaddf0ebe32f Mon Sep 17 00:00:00 2001 From: Akashdeep Dhar Date: Thu, 20 Feb 2025 12:11:45 +0530 Subject: [PATCH] [P2F] Add investigation for migrating issue tickets Signed-off-by: Akashdeep Dhar --- docs/pagure2forgejo/tkts.rst | 111 +++++++++++++++++++++++++++++++++++ 1 file changed, 111 insertions(+) create mode 100644 docs/pagure2forgejo/tkts.rst diff --git a/docs/pagure2forgejo/tkts.rst b/docs/pagure2forgejo/tkts.rst new file mode 100644 index 0000000..cf573b3 --- /dev/null +++ b/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 `_, +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. +