diff --git a/docs/dist-git-move/index.rst b/docs/dist-git-move/index.rst index 961f3c5..f738ba5 100644 --- a/docs/dist-git-move/index.rst +++ b/docs/dist-git-move/index.rst @@ -48,6 +48,7 @@ Index hotness notifications toddlers + messaging Conclusions ---- diff --git a/docs/dist-git-move/messaging.rst b/docs/dist-git-move/messaging.rst new file mode 100644 index 0000000..363e38c --- /dev/null +++ b/docs/dist-git-move/messaging.rst @@ -0,0 +1,478 @@ +.. _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 `_ +to comprehend the messages emitted from Pagure, it requires a helper library +called `Pagure Messages `_. This package is +distributed in the official Fedora Project repositories +`here `_ and on PyPI +`here `_. 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 `_. + +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 `_. + +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 `_. + +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 `_. + +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 `_. + +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 `_. + +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 `_. + +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 `_. + +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 `_. + +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 `_. + +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 `_. + +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 `_. + +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 `_. + +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 `_. + +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 `_. + +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 `_. + +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 `_. + +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 `_. + +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 `_. + +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 `_. + +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 `_. + +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 `_. + +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 `_. + +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 `_. + +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 `_. + +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 `_. + +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 `_. + +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 `_. + +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 `_. + +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 `_. + +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 `_. + +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 `_. + +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 `_. + +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 `_. + +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 `_. + +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 `_. + +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 `_. + +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 `_. + +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 `_. + +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 `_. + +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 `_. + +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 `_. + +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 `_. + +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 `_. + +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 `_. + +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 `_. +- 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.