arc/docs/dist-git-move/packit.rst

.. _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 <https://github.com/packit/packit/>`_


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 <https://github.com/packit/packit/blob/main/packit/distgit.py>`_
  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 <https://github.com/packit/packit/blob/main/packit/distgit.py#L97>`_
  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 <https://github.com/packit/packit/blob/main/packit/pkgtool.py#L13>`_
  that utilizes `fedpkg clone method <https://github.com/packit/packit/blob/main/packit/pkgtool.py#L136>`_
  which builds the clone command from getting the fas username, directory, branch, and target path.

  - API Endpoint: ``/api/0/<namespace>/<repo>``

- `Cloning the package <https://github.com/packit/packit/blob/main/packit/distgit.py#L180>`_
  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/<namespace>/<package_name>``
  - API Endpoint: ``/api/0/<namespace>/<package_name>/git/branches``

- `Obtaining absolute path for the specfile <https://github.com/packit/packit/blob/main/packit/distgit.py#L207>`_
  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/<namespace>/<repo>``

- `Updating branch <https://github.com/packit/packit/blob/main/packit/distgit.py#L233>`_
  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 <https://github.com/packit/packit/blob/6e286a7b4d0f79cd2a8213a8ae978788be5219c5/packit/local_project.py#L31>`_
  That represents the cloned repo, the **fetch** method is defined there
  `Fetch method <https://github.com/packit/packit/blob/6e286a7b4d0f79cd2a8213a8ae978788be5219c5/packit/local_project.py#L560>`_

  - API Endpoint: ``/api/0/<namespace>/<package_name>/git/branches``

- `Synchronizing Access Control Lists <https://github.com/packit/packit/blob/main/packit/distgit.py#L255>`_
  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 <https://packit.github.io/ogr/abstract.html#ogr.abstract.GitProject>`_

  - API Endpoint: ``/api/0/<namespace>/<package_name>/hascommit``
  - API Endpoint: ``/api/0/<namespace>/<package_name>/git/modifyacls``

- `Pushing to a fork repository <https://github.com/packit/packit/blob/main/packit/distgit.py#L282>`_
  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/<namespace>/<package_name>``

- `Creating pull request <https://github.com/packit/packit/blob/main/packit/distgit.py#L328>`_
  Creates a Dist Git PR using the requested branches

  - API Endpoint: ``/api/0/<namespace>/<package_name>/pull-request/new``

- `Downloading upstream tarballs <https://github.com/packit/packit/blob/main/packit/distgit.py#L382>`_
  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 <https://github.com/packit/packit/blob/main/packit/pkgtool.py#L64>`_

- `Downloading source files <https://github.com/packit/packit/blob/main/packit/distgit.py#L403>`_
  Downloads source files from the lookaside cache. Using the the **sources** method in 
  ``packit/pkgtool.py``

- `Uploading the source files to the lookaside cache <https://github.com/packit/packit/blob/main/packit/distgit.py#L420>`_
  Uploads files (archives) to the lookaside cache. Uses the 
  `new_sources method in pkgtool.py <https://github.com/packit/packit/blob/main/packit/pkgtool.py#L42>`_
  method in ``packit/pkgtool.py``

- `Checking if lookaside cache is already populated <https://github.com/packit/packit/blob/main/packit/distgit.py#L456>`_
  Checks whether the archive is already uploaded to the lookaside cache, using a wrapper around lookaside cache
  `lookaside.py <https://github.com/packit/packit/blob/main/packit/utils/lookaside.py#L17>`_ 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 <https://github.com/packit/ogr>`_

Unnecessary
~~~~~~~~~~~
- none