From 9addec0744b4b8691cbde46477a67f974cc0f79f Mon Sep 17 00:00:00 2001 From: Akashdeep Dhar Date: Mon, 30 Jan 2023 12:32:20 +0530 Subject: [PATCH] Add documentation about Pagure interactions Signed-off-by: Akashdeep Dhar --- docs/pagure2gitlab/index.rst | 3 +- docs/pagure2gitlab/pagure.rst | 122 +++++++++++++++++++++++++++++++++- 2 files changed, 121 insertions(+), 4 deletions(-) diff --git a/docs/pagure2gitlab/index.rst b/docs/pagure2gitlab/index.rst index a653951..2c22107 100644 --- a/docs/pagure2gitlab/index.rst +++ b/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 ------------ diff --git a/docs/pagure2gitlab/pagure.rst b/docs/pagure2gitlab/pagure.rst index 93ec0c1..969fb11 100644 --- a/docs/pagure2gitlab/pagure.rst +++ b/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 `_ to `interact + with the issue tickets `_ 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 `_ repository should be + able to access the issue tickets using the URL + `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 `_ + for the fedora-websites source namespace) or the SSH URL (for example, it + would be + `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. + +