diff --git a/docs/dist-git-move/index.rst b/docs/dist-git-move/index.rst index 5b63217..7619904 100644 --- a/docs/dist-git-move/index.rst +++ b/docs/dist-git-move/index.rst @@ -59,6 +59,7 @@ Interactions monitorgating releng packagers + packit Index ------- diff --git a/docs/dist-git-move/packit.rst b/docs/dist-git-move/packit.rst new file mode 100644 index 0000000..bd490c4 --- /dev/null +++ b/docs/dist-git-move/packit.rst @@ -0,0 +1,127 @@ +.. _packit: + +Pagure Dist Git Interactions With Packit +======================================== + +Packit is a CLI tool that helps developers auto-package upstream projects +into Fedora operating system. You can use packit to continuously build your +upstream project in Fedora. With packit you can create SRPMs, open pull +requests in dist-git, submit koji builds and even create bodhi updates, +effectively replacing the whole Fedora packaging workflow. + +Packit interacts with Dist Git mainly by making pull requests (eg. with version bumps) + +`Packit Source Code `_ + + +Possible Interactions +--------------------- + +The following are a set of documented possible interactions between Pagure Dist +Git and Packit + +The ``DistGit`` class +~~~~~~~~~~~~~~~~~~~~~ + +- Packit has a class named + `DistGit `_ + that interacts with dist-git and pagure-over-dist-git API. + The logic covers git and pagure interaction, manipulation with content, + spec files, patches and archives. One optional argument, "clone_path" is the path + where the dist-git repo is cloned, this will be affected by a Dist Git deployment + change. There are a number of methods in the class that interact with dist-git listed + below. + + +- `Cloning the repo `_ + This method clones the dist-git repo for the selected package and returns + the instance of the Dist Git class. Packit uses a wrapper, + `pkgtool `_ + that utilizes `fedpkg clone method `_ + which builds the clone command from getting the fas username, directory, branch, and target path. + + - API Endpoint: ``/api/0//`` + +- `Cloning the package `_ + This method clones the package from Dist Git, utilizing the same ``clone`` method in the + ``pkgtool`` wrapper. Optional argument for the branch to checkout, if so, an additional API call + is made to the endpoint below. + + - API Endpoint: ``/api/0//`` + - API Endpoint: ``/api/0///git/branches`` + +- `Obtaining absolute path for the specfile `_ + Determines the absolute path for the specfile in Dist Git. Specfile path is built using the + configured ``spec_dir_name``, then ``f"{self.package_config.downstream_package_name}.spec"`` + + - API Endpoint: ``/api/0//`` + +- `Updating branch `_ + Fetches the latest commits to the selected branch. Needs to hit the same API Endpoint as the + package cloning method. Packit has a + `LocalProject class `_ + That represents the cloned repo, the **fetch** method is defined there + `Fetch method `_ + + - API Endpoint: ``/api/0///git/branches`` + +- `Synchronizing Access Control Lists `_ + Synchronizes ACLs between the Dist Git project and its fork. Users and groups + with commit or higher access to the original project will gain commit access + to the fork. Users and groups without commit or higher access to the original + project will be removed from the fork. Utilizes ``ogr.abstract`` methods in the + `GitProject class `_ + + - API Endpoint: ``/api/0///hascommit`` + - API Endpoint: ``/api/0///git/modifyacls`` + +- `Pushing to a fork repository `_ + Push changes to a fork of the Dist Git repo after checking if user has access. Hits the same API Endpoint + as **Cloning the repo** above. + + - API Endpoint: ``/api/0//`` + +- `Creating pull request `_ + Creates a Dist Git PR using the requested branches + + - API Endpoint: ``/api/0///pull-request/new`` + +- `Downloading upstream tarballs `_ + Fetch archives for the current upstream release defined in Dist Git's spec. Again, uses the fedpkg + wrapper ``packit/pkgtool.py``, specifically the + `sources method in pkgtool.py `_ + +- `Downloading source files `_ + Downloads source files from the lookaside cache. Using the the **sources** method in + ``packit/pkgtool.py`` + +- `Uploading the source files to the lookaside cache `_ + Uploads files (archives) to the lookaside cache. Uses the + `new_sources method in pkgtool.py `_ + method in ``packit/pkgtool.py`` + +- `Checking if lookaside cache is already populated `_ + Checks whether the archive is already uploaded to the lookaside cache, using a wrapper around lookaside cache + `lookaside.py `_ This returns + True if the archive is present in the lookaside cache, False if not. + +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 +places mentioned below. + +Necessary +~~~~~~~~~ + +- Packit uses a number of URLs that point to dist-git mentioned above. If the URL should + change, they would need to be updated. + +- Packit team has created a library that provides the same API for various git forges, + so the proposed changes above would be necessary for OGR if another git forge is used. + `Packit/ogr `_ + +Unnecessary +~~~~~~~~~~~ +- none