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

.. _messaging:

Pagure Dist Git Interactions With Fedora Messaging
==================================================

Fedora Messaging provides tools and APIs to make using Fedora Project's messaging
infrastructure easier. These include a framework for declaring message schemas, a set of
asynchronous APIs to consume messages, and services to easily run consumers.

Interaction Dependencies
------------------------

Fedora Messaging makes use of the following dependencies to interact with and understand
interactions made with Pagure Dist Git.

Pagure Messages
~~~~~~~~~~~~~~~

In order for `Fedora Messaging <https://fedora-messaging.readthedocs.io/en/stable/>`_ to
comprehend the messages emitted from Pagure, it requires a helper library called `Pagure
Messages <https://pagure.io/pagure-messages>`_. This package is distributed in the
official Fedora Project repositories `here
<https://src.fedoraproject.org/rpms/python-pagure-messages>`__. and on PyPI `here
<https://pypi.org/project/pagure-messages/>`__. It is important to note that at the time
of writing this investigation, the former seems to be in an unmaintained state and the
last update i.e. ``v0.0.6`` was created around two years back. The PyPI releases are
fairly up-to-date with the most recent release i.e. ``v1.1.0`` being created around four
months back.

Possible Interactions
---------------------

The following are a set of documented interactions possible between Pagure Dist Git and
Fedora Messaging.

Projects
~~~~~~~~

The messages in this category follow the topic name pattern ``pagure.project.*``.

Creation of a project
+++++++++++++++++++++

Whenever a new project is created on either Pagure or Pagure Dist Git, the message of
schema topic ``pagure.project.new`` is created on the Fedora Messaging bus. The class
definition can be found `here
<https://pagure.io/pagure-messages/blob/master/f/pagure_messages/project_schema.py#_20-57>`__.

Editing of a project
++++++++++++++++++++

Whenever an existing project is edited on either Pagure or Pagure Dist Git, the message
of schema topic ``pagure.project.edit`` is created on the Fedora Messaging bus. The
class definition can be found `here
<https://pagure.io/pagure-messages/blob/master/f/pagure_messages/project_schema.py#_60-99>`__.

Forking of a project
++++++++++++++++++++

Whenever an existing project is forked on either Pagure or Pagure Dist Git, the message
of schema topic ``pagure.project.forked`` is created on the Fedora Messaging bus. The
class definition can be found `here
<https://pagure.io/pagure-messages/blob/master/f/pagure_messages/project_schema.py#_102-140>`__.

Deleting of a project
+++++++++++++++++++++

Whenever an existing project is removed from either Pagure or Pagure Dist Git, the
message of schema topic ``pagure.project.deleted`` is created on the Fedora Messaging
bus. The class definition can be found `here
<https://pagure.io/pagure-messages/blob/master/f/pagure_messages/project_schema.py#_143-180>`__.

Adding a group to a project
+++++++++++++++++++++++++++

Whenever access is provided to a group for a project on either Pagure or Pagure Dist
Git, the message of schema topic ``pagure.project.group.added`` is created on the Fedora
Messaging bus. The class definition can be found `here
<https://pagure.io/pagure-messages/blob/master/f/pagure_messages/project_schema.py#_183-229>`__.

Deleting a group from a project
+++++++++++++++++++++++++++++++

Whenever access is revoked from a group for a project on either Pagure or Pagure Dist
Git, the message of schema topic ``pagure.project.group.removed`` is created on the
Fedora Messaging bus. The class definition can be found `here
<https://pagure.io/pagure-messages/blob/master/f/pagure_messages/project_schema.py#_232-279>`__.

Updating a group on a project
+++++++++++++++++++++++++++++

Whenever access is updated to a group for a project on either Pagure or Pagure Dist Git,
the message of schema topic ``pagure.project.group.access.updated`` is created on the
Fedora Messaging bus. The class definition can be found `here
<https://pagure.io/pagure-messages/blob/master/f/pagure_messages/project_schema.py#_282-326>`__.

Editing a tag on a project
++++++++++++++++++++++++++

Whenever tags are edited for a project on either Pagure or Pagure Dist Git, the message
of schema topic ``pagure.project.tag.edited`` is created on the Fedora Messaging bus.
The class definition can be found `here
<https://pagure.io/pagure-messages/blob/master/f/pagure_messages/project_schema.py#_329-368>`__.

Deleting a tag on a project
+++++++++++++++++++++++++++

Whenever tags are deleted from a project on either Pagure or Pagure Dist Git, the
message of schema topic ``pagure.project.tag.removed`` is created on the Fedora
Messaging bus. The class definition can be found `here
<https://pagure.io/pagure-messages/blob/master/f/pagure_messages/project_schema.py#_371-410>`__.

Updating a user to a project
++++++++++++++++++++++++++++

Whenever access is updated to a user for a project on either Pagure or Pagure Dist Git,
the message of schema topic ``pagure.project.user.access.updated`` is created on the
Fedora Messaging bus. The class definition can be found `here
<https://pagure.io/pagure-messages/blob/master/f/pagure_messages/project_schema.py#_413-457>`__.

Adding a user to a project
++++++++++++++++++++++++++

Whenever access is provided to a user for a project on either Pagure or Pagure Dist Git,
the message of schema topic ``pagure.project.user.added`` is created on the Fedora
Messaging bus. The class definition can be found `here
<https://pagure.io/pagure-messages/blob/master/f/pagure_messages/project_schema.py#_460-499>`__.

Deleting a user from a project
++++++++++++++++++++++++++++++

Whenever access is revoked from a user for a project on either Pagure or Pagure Dist
Git, the message of schema topic ``pagure.project.user.removed`` is created on the
Fedora Messaging bus. The class definition can be found `here
<https://pagure.io/pagure-messages/blob/master/f/pagure_messages/project_schema.py#_502-541>`__.

Repositories
~~~~~~~~~~~~

The messages in this category follow the topic name pattern ``pagure.git.*``.

Creation of a branch
++++++++++++++++++++

Whenever a new branch is created on a project on either Pagure or Pagure Dist Git, the
message of schema topic ``pagure.git.branch.creation`` is created on the Fedora
Messaging bus. The class definition can be found `here
<https://pagure.io/pagure-messages/blob/master/f/pagure_messages/git_schema.py#_47-95>`__.

Deletion of a branch
++++++++++++++++++++

Whenever an existing branch is deleted on a project on either Pagure or Pagure Dist Git,
the message of schema topic ``pagure.git.branch.deletion`` is created on the Fedora
Messaging bus. The class definition can be found `here
<https://pagure.io/pagure-messages/blob/master/f/pagure_messages/git_schema.py#_98-139>`__.

Reception of commits
++++++++++++++++++++

Whenever a set of commits are pushed to an existing branch in a repository on either
Pagure or Pagure Dist Git, the message of schema topic ``pagure.git.receive`` is created
on the Fedora Messaging bus. The class definition can be found `here
<https://pagure.io/pagure-messages/blob/master/f/pagure_messages/git_schema.py#_142-224>`__.

Creation of a tag
+++++++++++++++++

Whenever a new tag is created on a project on either Pagure or Pagure Dist Git, the
message of schema topic ``pagure.git.tag.creation`` is created on the Fedora Messaging
bus. The class definition can be found `here
<https://pagure.io/pagure-messages/blob/master/f/pagure_messages/git_schema.py#_227-273>`__.

Deletion of a tag
+++++++++++++++++

Whenever an existing tag is deleted on a project on either Pagure or Pagure Dist Git,
the message of schema topic ``pagure.git.tag.deletion`` is created on the Fedora
Messaging bus. The class definition can be found `here
<https://pagure.io/pagure-messages/blob/master/f/pagure_messages/git_schema.py#_276-320>`__.

Issues
~~~~~~

The messages in this category follow the topic name pattern ``pagure.issue.*``.

Please note that these are not used in Pagure Dist Git as the **Issues** tab in Pagure
Dist Git points to the Bugzilla page related to the said package.

Adding assignment to an issue ticket
++++++++++++++++++++++++++++++++++++

Whenever an assignment is added to an existing issue ticket on a project present on
Pagure, the message of schema topic ``pagure.issue.assigned.added`` is created on the
Fedora Messaging bus. The class definition can be found `here
<https://pagure.io/pagure-messages/blob/master/f/pagure_messages/issue_schema.py#_20-62>`__.

Removing assignment from an issue ticket
++++++++++++++++++++++++++++++++++++++++

Whenever an assignment is removed from an existing issue ticket on a project present on
Pagure, the message of schema topic ``pagure.issue.assigned.reset`` is created on the
Fedora Messaging bus. The class definition can be found `here
<https://pagure.io/pagure-messages/blob/master/f/pagure_messages/issue_schema.py#_65-105>`__.

Comment added to an issue ticket
++++++++++++++++++++++++++++++++

Whenever a comment is added to an existing issue ticket on a project present on either
Pagure and Pagure Dist Git, the message of schema topic ``pagure.issue.comment.added``
is created on the Fedora Messaging bus. The class definition can be found `here
<https://pagure.io/pagure-messages/blob/master/f/pagure_messages/issue_schema.py#_108-153>`__.

Adding dependency to an issue ticket
++++++++++++++++++++++++++++++++++++

Whenever a dependency is added to an existing issue ticket on a project present on
Pagure, the message of schema topic ``pagure.issue.dependency.added`` is created on the
Fedora Messaging bus. The class definition can be found `here
<https://pagure.io/pagure-messages/blob/master/f/pagure_messages/issue_schema.py#_156-201>`__.

Removing dependency from an issue ticket
++++++++++++++++++++++++++++++++++++++++

Whenever a dependency is removed from an existing issue ticket from a project present on
Pagure, the message of schema topic ``pagure.issue.dependency.removed`` is created on
the Fedora Messaging bus. The class definition can be found `here
<https://pagure.io/pagure-messages/blob/master/f/pagure_messages/issue_schema.py#_204-257>`__.

Removing an issue ticket
++++++++++++++++++++++++

Whenever an existing issue ticket is removed from a project present on either Pagure,
the message of schema topic ``pagure.issue.drop`` is created on the Fedora Messaging
bus. The class definition can be found `here
<https://pagure.io/pagure-messages/blob/master/f/pagure_messages/issue_schema.py#_260-303>`__.

Editing an issue ticket
+++++++++++++++++++++++

Whenever an existing issue ticket is edited on a project present on either Pagure, the
message of schema topic ``pagure.issue.edit`` is created on the Fedora Messaging bus.
The class definition can be found `here
<https://pagure.io/pagure-messages/blob/master/f/pagure_messages/issue_schema.py#_306-351>`__.

Creating an issue ticket
++++++++++++++++++++++++

Whenever a new issue ticket is created on a project present on either Pagure or , the
message of schema topic ``pagure.issue.new`` is created on the Fedora Messaging bus. The
class definition can be found `here
<https://pagure.io/pagure-messages/blob/master/f/pagure_messages/issue_schema.py#_354-395>`__.

Adding label to an issue ticket
+++++++++++++++++++++++++++++++

Whenever labels are added to an existing issue ticket is created on a project present on
Pagure, the message of schema topic ``pagure.issue.tag.added`` is created on the Fedora
Messaging bus. The class definition can be found `here
<https://pagure.io/pagure-messages/blob/master/f/pagure_messages/issue_schema.py#_398-441>`__.

Removing label from an issue ticket
+++++++++++++++++++++++++++++++++++

Whenever labels are removed from an existing issue ticket is created on a project
present on Pagure, the message of schema topic ``pagure.issue.tag.removed`` is created
on the Fedora Messaging bus. The class definition can be found `here
<https://pagure.io/pagure-messages/blob/master/f/pagure_messages/issue_schema.py#_444-487>`__.

Pull Requests
~~~~~~~~~~~~~

The messages in this category follow the topic name pattern ``pagure.pull-request.*``.

Adding a pull request assignee
++++++++++++++++++++++++++++++

Whenever an assignee is added to an existing pull request made against a project on
either Pagure or Pagure Dist Git, the message of schema topic
``pagure.pull-request.assigned.added`` is created on the Fedora Messaging bus. The class
definition can be found `here
<https://pagure.io/pagure-messages/blob/master/f/pagure_messages/pull_requests_schema.py#_20-61>`__.

Removing a pull request assignee
++++++++++++++++++++++++++++++++

Whenever an assignee is removed from an existing pull request made against a project on
either Pagure or Pagure Dist Git, the message of schema topic
``pagure.pull-request.assigned.reset`` is created on the Fedora Messaging bus. The class
definition can be found `here
<https://pagure.io/pagure-messages/blob/master/f/pagure_messages/pull_requests_schema.py#_64-104>`__.

Closing a pull request
++++++++++++++++++++++

Whenever an existing pull request made against a project on either Pagure or Pagure Dist
Git is closed, the message of schema topic ``pagure.pull-request.closed`` is created on
the Fedora Messaging bus. The class definition can be found `here
<https://pagure.io/pagure-messages/blob/master/f/pagure_messages/pull_requests_schema.py#_107-151>`__.

Adding a comment on a pull request
++++++++++++++++++++++++++++++++++

Whenever a comment is added to an existing pull request made against a project on either
Pagure or Pagure Dist Git is closed, the message of schema topic
``pagure.pull-request.comment.added`` is created on the Fedora Messaging bus. The class
definition can be found `here
<https://pagure.io/pagure-messages/blob/master/f/pagure_messages/pull_requests_schema.py#_154-200>`__.

Editing a comment on a pull request
+++++++++++++++++++++++++++++++++++

Whenever a comment is edited on an existing pull request made against a project on
either Pagure or Pagure Dist Git is closed, the message of schema topic
``pagure.pull-request.comment.edited`` is created on the Fedora Messaging bus. The class
definition can be found `here
<https://pagure.io/pagure-messages/blob/master/f/pagure_messages/pull_requests_schema.py#_203-249>`__.

Adding a flag on a pull request
+++++++++++++++++++++++++++++++

Whenever a flag is added to an existing pull request made against a project on either
Pagure or Pagure Dist Git is closed, the message of schema topic
``pagure.pull-request.flag.added`` is created on the Fedora Messaging bus. The class
definition can be found `here
<https://pagure.io/pagure-messages/blob/master/f/pagure_messages/pull_requests_schema.py#_252-293>`__.

Updating a flag on a pull request
+++++++++++++++++++++++++++++++++

Whenever a flag is updated on an existing pull request made against a project on either
Pagure or Pagure Dist Git is closed, the message of schema topic
``pagure.pull-request.flag.updated`` is created on the Fedora Messaging bus. The class
definition can be found `here
<https://pagure.io/pagure-messages/blob/master/f/pagure_messages/pull_requests_schema.py#_296-339>`__.

Editing a pull request body
+++++++++++++++++++++++++++

Whenever the body of en existing pull request made against a project on either Pagure or
Pagure Dist Git is edited, the message of schema topic
``pagure.pull-request.initial_comment.edited`` is created on the Fedora Messaging bus.
The class definition can be found `here
<https://pagure.io/pagure-messages/blob/master/f/pagure_messages/pull_requests_schema.py#_342-384>`__.

Creating a pull request
+++++++++++++++++++++++

Whenever a pull request is made against a project on either Pagure or Pagure Dist Git,
the message of schema topic ``pagure.pull-request.new`` is created on the Fedora
Messaging bus. The class definition can be found `here
<https://pagure.io/pagure-messages/blob/master/f/pagure_messages/pull_requests_schema.py#_387-427>`__.

Rebasing a pull request
+++++++++++++++++++++++

Whenever a pull request made against a project on either Pagure or Pagure Dist Git is
rebased, the message of schema topic ``pagure.pull-request.rebased`` is created on the
Fedora Messaging bus. The class definition can be found `here
<https://pagure.io/pagure-messages/blob/master/f/pagure_messages/pull_requests_schema.py#_430-469>`__.

Reopening a pull request
++++++++++++++++++++++++

Whenever a closed pull request made against a project on either Pagure or Pagure Dist
Git is reopened, the message of schema topic ``pagure.pull-request.reopened`` is created
on the Fedora Messaging bus. The class definition can be found `here
<https://pagure.io/pagure-messages/blob/master/f/pagure_messages/pull_requests_schema.py#_472-511>`__.

Adding a tag on a pull request
++++++++++++++++++++++++++++++

Whenever a tag is added to an existing pull request made against a project on either
Pagure or Pagure Dist Git, the message of schema topic ``pagure.pull-request.tag.added``
is created on the Fedora Messaging bus. The class definition can be found `here
<https://pagure.io/pagure-messages/blob/master/f/pagure_messages/pull_requests_schema.py#_514-556>`__.

Removing a tag on a pull request
++++++++++++++++++++++++++++++++

Whenever a tag is removed from an existing pull request made against a project on either
Pagure or Pagure Dist Git, the message of schema topic
``pagure.pull-request.tag.removed`` is created on the Fedora Messaging bus. The class
definition can be found `here
<https://pagure.io/pagure-messages/blob/master/f/pagure_messages/pull_requests_schema.py#_559-601>`__.

Updating a pull request
+++++++++++++++++++++++

Whenever an existing pull request made against a project on either Pagure or Pagure Dist
Git is updated, the message of schema topic ``pagure.pull-request.updated`` is created
on the Fedora Messaging bus. The class definition can be found `here
<https://pagure.io/pagure-messages/blob/master/f/pagure_messages/pull_requests_schema.py#_604-643>`__.

Uncategorized
~~~~~~~~~~~~~

The messages in this category do not follow any any certain topic name pattern.

Adding a commit flag
++++++++++++++++++++

Whenever a commit flag is added in a project on either Pagure or Pagure Dist Git, the
message of schema topic ``pagure.commit.flag.added`` is created on the Fedora Messaging
bus. The class definition can be found `here
<https://pagure.io/pagure-messages/blob/master/f/pagure_messages/misc_schema.py#_20-69>`__.

Updating a commit flag
++++++++++++++++++++++

Whenever a commit flag is updated in a project on either Pagure or Pagure Dist Git, the
message of schema topic ``pagure.commit.flag.updated`` is created on the Fedora
Messaging bus. The class definition can be found `here
<https://pagure.io/pagure-messages/blob/master/f/pagure_messages/misc_schema.py#_72-121>`__.

Editing a group
+++++++++++++++

Whenever the edits to a group are saved on either Pagure or Pagure Dist Git, the message
of schema topic ``pagure.group.edit`` is created on the Fedora Messaging bus. The class
definition can be found `here
<https://pagure.io/pagure-messages/blob/master/f/pagure_messages/misc_schema.py#_124-165>`__.

Sending a test notification
+++++++++++++++++++++++++++

For debugging purposes, a test notification can be sent over with the schema topic
``pagure.Test.notification`` is created on the Fedora Messaging bus. The class can be
found `here
<https://pagure.io/pagure-messages/blob/master/f/pagure_messages/misc_schema.py#_168-198>`__.

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 placed mentioned
below.

Necessary
~~~~~~~~~

- The base class for all the topic classes ``PagureMessage`` has two member variables
  storing information about the URL of the production (in ``__link__``) and staging (in
  ``__stg_link__``) deployments of either Pagure or Pagure Dist Git. This needs to be
  changed in accordance with the newer replacement planned. The class definition can be
  found `here
  <https://pagure.io/pagure-messages/blob/master/f/pagure_messages/base.py#_401-443>`__.
- The variable ``SCHEMA_URL`` currently leads to the page
  ``https://fedoraproject.org/message-schema/`` which does not exist. This needs to be
  changed to point to the correct URL.
- There are multiple variables that contain the API schema for Pagure and Pagure Dist
  Git, like ``TagColored``, ``BOARD``, ``BOARD_STATUS``, ``BOARD_ISSUE``, ``USER``,
  ``GIT_RECEIVE_USER``, ``PAGURE_LOG``, ``MILESTONES``, ``PRIORITIES``,
  ``BASE_PROJECT``, ``PROJECT``, ``RELATED_PR``, ``ISSUE``, ``PULL_REQUEST``,
  ``COMMIT_FLAG`` and ``GROUP`` that must undergo changes to store the API schemas for
  the replacement platform.
- The schema project called ``pagure-messages`` need to be changed as well to
  accommodate the JSON schema for the API of the alternative and hence, publish messages
  accordingly.

Unnecessary
~~~~~~~~~~~

- The message classes themselves and the way they operate could, more or less, stay the
  same as the way the messages are being sent to the Fedora Messaging bus would remain
  the same.