478 lines
20 KiB
ReStructuredText
478 lines
20 KiB
ReStructuredText
.. _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.
|