Infrastructure/arc
3
0
Fork 0
Code Issues 1 Pull requests Projects Releases Packages Wiki Activity Actions

fix parsing errors and sphinx warnings

Browse source 
Signed-off-by: Ryan Lerch <rlerch@redhat.com>
This commit is contained in:
Ryan Lercho 2023-11-16 08:02:56 +10:00 • committed by zlopez
parent 8fb9b2fdf0
commit ba720c3d77
98 changed files with 4799 additions and 4788 deletions
Download patch file Download diff file Expand all files Collapse all files

6
docs/badges/current_implementation.rst
View file

@ -1,10 +1,10 @@
.. _current_implementation:
Current implementation
====
======================
The Fedora Badges service is currently split up into multiple projects that all
work together to award badges to Fedora Project contributors. These parts are -
The Fedora Badges service is currently split up into multiple projects that all work
together to award badges to Fedora Project contributors. These parts are -
.. toctree::
:maxdepth: 1

16
docs/badges/current_implementation_artwork_and_rules.rst
View file

@ -1,14 +1,14 @@
.. _current_implementation_artwork_and_rules:
Artwork and rules
====
=================
The fedora-badges repo on Pagure is where community members contribute the
badge rules and badge images for new badges. These assets are added to the
fedora-badges repo, and copied over to the servers using the
`push-badges manual playbook <https://pagure.io/fedora-infra/ansible/blob/main/f/playbooks/manual/push-badges.yml>`_
The fedora-badges repo on Pagure is where community members contribute the badge rules
and badge images for new badges. These assets are added to the fedora-badges repo, and
copied over to the servers using the `push-badges manual playbook
<https://pagure.io/fedora-infra/ansible/blob/main/f/playbooks/manual/push-badges.yml>`_
The artwork is copied over to `badges-web01` and the rules are copied over to `badges-backend01`.
* Source repository: `https://pagure.io/fedora-badges/ <https://pagure.io/fedora-badges/>`_
The artwork is copied over to `badges-web01` and the rules are copied over to
`badges-backend01`.
- Source repository: https://pagure.io/fedora-badges/

24
docs/badges/current_implementation_badge_issuer_scripts.rst
View file

@ -1,19 +1,19 @@
.. _current_implementation_badge_issuer_scripts:
Badge issuer scripts
====
====================
In addition to manually granting a badge in the web interface, and the
messages consumer granting badges, the third way badges are granted are by a
collection of scripts that live on the badges-backend01 server.
In addition to manually granting a badge in the web interface, and the messages consumer
granting badges, the third way badges are granted are by a collection of scripts that
live on the badges-backend01 server.
These scripts run periodically using cron, and are used for badges that aren't
triggered by an incoming message on the messaging bus.
These scripts run periodically using cron, and are used for badges that aren't triggered
by an incoming message on the messaging bus.
A good example of this is the "lifecycle" badges, that award people for having
a Fedora Account for a period of time. There is no message sent when a Fedora
Account turns a certain age, so this is done using a script.
* Source repository: `https://pagure.io/fedora-infra/ansible/blob/main/f/roles/badges/backend/files/cron <https://pagure.io/fedora-infra/ansible/blob/main/f/roles/badges/backend/files/cron>`_
* Production location: badges-backend01.iad2.fedoraproject.org
A good example of this is the "lifecycle" badges, that award people for having a Fedora
Account for a period of time. There is no message sent when a Fedora Account turns a
certain age, so this is done using a script.
- Source repository:
https://pagure.io/fedora-infra/ansible/blob/main/f/roles/badges/backend/files/cron
- Production location: badges-backend01.iad2.fedoraproject.org

58
docs/badges/current_implementation_databases_and_api.rst
View file

@ -1,37 +1,45 @@
.. _current_implementation_databases_and_api:
The database and the API
====
========================
The database for Fedora Badges stores the badge definitions. and what users
have been granted these badges. These is also a Python API for interacting
with the database.
The database for Fedora Badges stores the badge definitions. and what users have been
granted these badges. These is also a Python API for interacting with the database.
* Source repository: `https://github.com/fedora-infra/tahrir-api <https://github.com/fedora-infra/tahrir-api>`_
* Production location: db01.iad2.fedoraproject.org/tahrir
- Source repository: https://github.com/fedora-infra/tahrir-api
- Production location: db01.iad2.fedoraproject.org/tahrir
Technology used
----
---------------
The database and API is written in Python 2 and uses SQLAlchemy for database
management. In the production deployment, a Postgres database is used.
The database and API is written in Python 2 and uses SQLAlchemy for database management.
In the production deployment, a Postgres database is used.
Basic table information
----
-----------------------
The badges database appears to have been implemented with extra features for
Open Badges (or Badgr) compatibility, but a lot of these tables are not really
in use in the production deployment of Fedora Badges.
The badges database appears to have been implemented with extra features for Open Badges
(or Badgr) compatibility, but a lot of these tables are not really in use in the
production deployment of Fedora Badges.
.. csv-table::
:header: "DB Table", "Information"
:widths: 15, 30
"Person", "A table for a user. Contains basic information about the user"
"Badge", "A table of all the badge definitions. Note that the badge image is not stored in the DB, it is just a link to an image on the backend server. Also, the criteria for a badge is only a URL to criteria."
"Assertion", "A table that maps users to badges allowing them to arbitrarily grant them."
"Authorization", "A table that maps users to badges allowing them to arbitrarily grant them."
"Issuer", "A table of the issuers that issue badges. In Fedora badges, there is only one issuer -- Fedora, so not really used."
"Series", "A table to do with having a series of badges -- can't find much documentation about it, but on production badges, it is empty, so not in use."
"Milestones", "Another table to do with having a series of badges -- can't find much documentation about it, but on production badges, it is empty, so not in use."
"Team", "Yet another table to do with having a series of badges -- can't find much documentation about it, but on production badges, it only has one entry 'Infrastructure'."
============= ==========================================================================
DB Table Information
============= ==========================================================================
Person A table for a user. Contains basic information about the user
Badge A table of all the badge definitions. Note that the badge image is not
stored in the DB, it is just a link to an image on the backend server.
Also, the criteria for a badge is only a URL to criteria.
Assertion A table that maps users to badges allowing them to arbitrarily grant them.
Authorization A table that maps users to badges allowing them to arbitrarily grant them.
Issuer A table of the issuers that issue badges. In Fedora badges, there is only
one issuer -- Fedora, so not really used.
Series A table to do with having a series of badges -- can't find much
documentation about it, but on production badges, it is empty, so not in
use.
Milestones Another table to do with having a series of badges -- can't find much
documentation about it, but on production badges, it is empty, so not in
use.
Team Yet another table to do with having a series of badges -- can't find much
documentation about it, but on production badges, it only has one entry
'Infrastructure'.
============= ==========================================================================

56
docs/badges/current_implementation_frontend.rst
View file

@ -1,48 +1,46 @@
.. _current_implementation_frontend:
Badges frontend
====
===============
Tahrir is the name given to the web interface that allows service users to
view the badges they have been awarded, view those awarded to other community
members, and grant special badges. Additionally, Fedora Badges admins also use
the web interface to add new badges into the database.
Tahrir is the name given to the web interface that allows service users to view the
badges they have been awarded, view those awarded to other community members, and grant
special badges. Additionally, Fedora Badges admins also use the web interface to add new
badges into the database.
* Source repository: `https://github.com/fedora-infra/tahrir <https://github.com/fedora-infra/tahrir>`_
* Production deployment: `https://badges.fedoraproject.org/ <https://badges.fedoraproject.org/>`_
* Production location: `badges-web01.iad2.fedoraproject.org <badges-web01.iad2.fedoraproject.org>`_
- Source repository: https://github.com/fedora-infra/tahrir
- Production deployment: https://badges.fedoraproject.org/
- Production location: badges-web01.iad2.fedoraproject.org
Note: The
`badges artworks <https://pagure.io/fedora-badges/blob/master/f/pngs>`_ are
stored in the `Fedora Badges repository <https://pagure.io/Fedora-Badges>`_,
and when new rules are added, copied over to the production location (i.e.
badges-web01 server) using the
`push-badges manual playbook <https://pagure.io/fedora-infra/ansible/blob/main/f/playbooks/manual/push-badges.yml>`_.
Note: The `badges artworks <https://pagure.io/fedora-badges/blob/master/f/pngs>`_ are
stored in the `Fedora Badges repository <https://pagure.io/Fedora-Badges>`_, and when
new rules are added, copied over to the production location (i.e. badges-web01 server)
using the `push-badges manual playbook
<https://pagure.io/fedora-infra/ansible/blob/main/f/playbooks/manual/push-badges.yml>`_.
Technology used
----
---------------
The web interface is written in Python 2 and uses Pyramid as a web framework
with Mako templates.
The web interface is written in Python 2 and uses Pyramid as a web framework with Mako
templates.
Usecases
----
--------
The following are the usecases of the web interface of Fedora Badges.
User usecases
^^^^
~~~~~~~~~~~~~
* View the badges that a particular user has
* View the leaderboard of badges
* View the details of a specific badge
* Get granted a badge (via a link or QR code)
* Give a badge to another user (if I have permissions on that badge)
- View the badges that a particular user has
- View the leaderboard of badges
- View the details of a specific badge
- Get granted a badge (via a link or QR code)
- Give a badge to another user (if I have permissions on that badge)
Admin usecases
^^^^
* Add a new badge to the database
* Give grant permissions to a user for a specific badge
* Create an invitation so users can get a badge via a QR code / link
~~~~~~~~~~~~~~
- Add a new badge to the database
- Give grant permissions to a user for a specific badge
- Create an invitation so users can get a badge via a QR code / link

54
docs/badges/current_implementation_messages_consumer.rst
View file

@ -1,40 +1,38 @@
.. _current_implementation_messages_consumer:
Messages consumer
====
=================
The fedbadges fedmsg consumer is the main piece of Fedora Badges that grants
badges to the service users. It consumes every message from the fedmsg bus,
checks to see if that message matches a badge rule, and if it does, uses the
Tahrir API (database API) to issue the badge to the user in the database.
The fedbadges fedmsg consumer is the main piece of Fedora Badges that grants badges to
the service users. It consumes every message from the fedmsg bus, checks to see if that
message matches a badge rule, and if it does, uses the Tahrir API (database API) to
issue the badge to the user in the database.
Many badge rules require the consumer to know about past messages too, not
just the one that triggered the rule. For example, a badge for 100 Bodhi
comments requires a historical count of bodhi comment messages from the
Datanommer (every message sent, ever) database. Note, however that currently
the consumer interfaces directly with the Datanommer database, rather than
using Datagrepper (been assumed so for performance reasons).
Many badge rules require the consumer to know about past messages too, not just the one
that triggered the rule. For example, a badge for 100 Bodhi comments requires a
historical count of bodhi comment messages from the Datanommer (every message sent,
ever) database. Note, however that currently the consumer interfaces directly with the
Datanommer database, rather than using Datagrepper (been assumed so for performance
reasons).
The badges rules are defined in YAML files are defined in a custom
specification that is documented in the
`fedbadges documentation <https://github.com/fedora-infra/fedbadges/blob/develop/README.rst>`_.
For Fedora Badges, the
`badges rules are stored <https://pagure.io/fedora-badges/blob/master/f/rules>`_
in the `Fedora Badges repo <https://pagure.io/Fedora-Badges>`_ and when new
rules are added, copied over to the badges-backend01 server using the
`pushes-badges manual playbook <https://pagure.io/fedora-infra/ansible/blob/main/f/playbooks/manual/push-badges.yml>`_.
The badges rules are defined in YAML files are defined in a custom specification that is
documented in the `fedbadges documentation
<https://github.com/fedora-infra/fedbadges/blob/develop/README.rst>`_. For Fedora
Badges, the `badges rules are stored
<https://pagure.io/fedora-badges/blob/master/f/rules>`_ in the `Fedora Badges repo
<https://pagure.io/Fedora-Badges>`_ and when new rules are added, copied over to the
badges-backend01 server using the `pushes-badges manual playbook
<https://pagure.io/fedora-infra/ansible/blob/main/f/playbooks/manual/push-badges.yml>`_.
* Source repository: `https://github.com/fedora-infra/fedbadges <https://github.com/fedora-infra/fedbadges>`_
* Production location: badges-backend01.iad2.fedoraproject.org
- Source repository: https://github.com/fedora-infra/fedbadges
- Production location: badges-backend01.iad2.fedoraproject.org
Note: The messages consumer has some code in the main development branch that
appears to start implementing support for Badgr. but this appears to be
half-finished and was never deployed to production. It also appears to only
send badges to badgr, and not store them in the tahrir database. So content
can start here.
Note: The messages consumer has some code in the main development branch that appears to
start implementing support for Badgr. but this appears to be half-finished and was never
deployed to production. It also appears to only send badges to badgr, and not store them
in the tahrir database. So content can start here.
Technologies used
----
-----------------
The messages consumer is written in Python 2.

199
docs/badges/discourse_integration.rst
View file

@ -1,122 +1,123 @@
.. _discourse_integration:
Integrate Fedora Discussions with the Fedora Badges System
====
==========================================================
Fedora Badges has not only been a means to incentivize contribution for the
Fedora Project community but also been an topic of active conversation and a
healthy competition among the community members. One of the attempts to bring
the system to the forefront was made by
`Matthew Miller <https://accounts.fedoraproject.org/user/mattdm>`_ on
`this Fedora Discussions thread <https://discussion.fedoraproject.org/t/magical-experimental-fedora-badges-topic/35007>`_
and participated by a lot of community members. This turned out to be quite a
successful experiment and the badges that people have acquired got integrated
with the Discourse badges page (For eg. here is a catalog of badges acquired by
`Akashdeep Dhar <https://discussion.fedoraproject.org/u/t0xic0der/badges>`_).
Fedora Badges has not only been a means to incentivize contribution for the Fedora
Project community but also been an topic of active conversation and a healthy
competition among the community members. One of the attempts to bring the system to the
forefront was made by `Matthew Miller <https://accounts.fedoraproject.org/user/mattdm>`_
on `this Fedora Discussions thread
<https://discussion.fedoraproject.org/t/magical-experimental-fedora-badges-topic/35007>`_
and participated by a lot of community members. This turned out to be quite a successful
experiment and the badges that people have acquired got integrated with the Discourse
badges page (For eg. here is a catalog of badges acquired by `Akashdeep Dhar
<https://discussion.fedoraproject.org/u/t0xic0der/badges>`_).
As it stands, the usage of Discourse (or Fedora Discussions) happens to help
with simplifying the creation (and maintenance) of the frontend of the Fedora
Badges system. Although this is a welcome proposal, the frontend happens to be
the least challenging component of the system (as mentioned by Ryan Lerch in
`his reply <https://discussion.fedoraproject.org/t/discourse-badges-should-we-or-shouldnt-we/34698/6>`_
to the
`original post <https://discussion.fedoraproject.org/t/discourse-badges-should-we-or-shouldnt-we/34698>`_
about testing waters around
`Discourse Badges <http://discussion.fedoraproject.org/badges>`_ created on
23rd Nov 2021) but the fact that it still has not been maintained and requires
modernization cannot be denied. At the very same time, it is a very alluring
choice which helps us save efforts in developing the frontend from ground up
and redirect them into redeveloping the backend, which admittedly requires the
most attention.
As it stands, the usage of Discourse (or Fedora Discussions) happens to help with
simplifying the creation (and maintenance) of the frontend of the Fedora Badges system.
Although this is a welcome proposal, the frontend happens to be the least challenging
component of the system (as mentioned by Ryan Lerch in `his reply
<https://discussion.fedoraproject.org/t/discourse-badges-should-we-or-shouldnt-we/34698/6>`_
to the `original post
<https://discussion.fedoraproject.org/t/discourse-badges-should-we-or-shouldnt-we/34698>`_
about testing waters around `Discourse Badges
<http://discussion.fedoraproject.org/badges>`_ created on 23rd Nov 2021) but the fact
that it still has not been maintained and requires modernization cannot be denied. At
the very same time, it is a very alluring choice which helps us save efforts in
developing the frontend from ground up and redirect them into redeveloping the backend,
which admittedly requires the most attention.
The original post about exploring the idea of using Discourse as the frontend
for Fedora Badges system (which can be found
`here <https://discussion.fedoraproject.org/t/exploring-the-idea-of-using-discourse-as-a-badges-frontend-the-backend-implications/34887>`_
created on 1st Dec 2021) further details on the proposed approaches of making
it happen. Although the study is superficial but the implications provided
there should be adequate enough to connect with our study regarding the
entities involved in the proposed redevelopment of the system (the one that can
be found
`here <https://fedora-arc.readthedocs.io/en/latest/badges/prop_rewrite_entities.html>`_
) to deduce that Fedora Discussions could very well be used to be a drop-in
replacement of sorts for our Liberation entity (information about the internal
entities can be found
`here <https://fedora-arc.readthedocs.io/en/latest/badges/prop_rewrite_entities.html#internal-entities>`_
The original post about exploring the idea of using Discourse as the frontend for Fedora
Badges system (which can be found `here
<https://discussion.fedoraproject.org/t/exploring-the-idea-of-using-discourse-as-a-badges-frontend-the-backend-implications/34887>`__
created on 1st Dec 2021) further details on the proposed approaches of making it happen.
Although the study is superficial but the implications provided there should be adequate
enough to connect with our study regarding the entities involved in the proposed
redevelopment of the system (the one that can be found `here
<https://fedora-arc.readthedocs.io/en/latest/badges/prop_rewrite_entities.html>`__ ) to
deduce that Fedora Discussions could very well be used to be a drop-in replacement of
sorts for our Liberation entity (information about the internal entities can be found
`here
<https://fedora-arc.readthedocs.io/en/latest/badges/prop_rewrite_entities.html#internal-entities>`__
).
The discussions in the aforementioned post were continued over at the original
post sharing notes of the things needed to be taken care of while implementing
the same (which can be found
`here <https://discussion.fedoraproject.org/t/badges-to-discourse-experiment-notes-on-discourse-as-a-badges-front-end/35262>`_
created on 16th Dec 2021). The following are the key points we derived and
discussed about from the said treatise.
The discussions in the aforementioned post were continued over at the original post
sharing notes of the things needed to be taken care of while implementing the same
(which can be found `here
<https://discussion.fedoraproject.org/t/badges-to-discourse-experiment-notes-on-discourse-as-a-badges-front-end/35262>`_
created on 16th Dec 2021). The following are the key points we derived and discussed
about from the said treatise.
1. The Discourse frontend does provide for a much faster loading of badges list
(Source:
`JSON acquring time for user mattdm <https://discussion.fedoraproject.org/t/badges-to-discourse-experiment-notes-on-discourse-as-a-badges-front-end/35262#:~:text=Getting%20list%20of%20badges%20for%20mattdm%20via%20JSON%20here%3A%20about%20140ms.%20From%20badges%20site%2C%20about%2035%20whole%20seconds>`_
) and the plugin system is convenient enough to allow for adding features
and elements atop a stock interface.
2. The global listing of badges on the Discourse interface allows marking of
acquired badges and for grouping, which can help solve the issue of
introducing badge paths, although the listing of badges according to their
age needs looking into.
3. The per-user listing of badges could use some organization according to
categories and/or badge paths but favourite badges can be picked and shown
on the profile card, which makes these badges more than a royal collectible
but something to start discussions around.
4. The leaderboards also remain something to be seen, though the implementation
should be fairly easy if we are to have the same format as that of the
current frontend (i.e. show weekly, monthly and all-time leaders). The badge
count for the users should be added too.
1. The Discourse frontend does provide for a much faster loading of badges list (Source:
`JSON acquring time for user mattdm
<https://discussion.fedoraproject.org/t/badges-to-discourse-experiment-notes-on-discourse-as-a-badges-front-end/35262#:~:text=Getting%20list%20of%20badges%20for%20mattdm%20via%20JSON%20here%3A%20about%20140ms.%20From%20badges%20site%2C%20about%2035%20whole%20seconds>`_
) and the plugin system is convenient enough to allow for adding features and
elements atop a stock interface.
2. The global listing of badges on the Discourse interface allows marking of acquired
badges and for grouping, which can help solve the issue of introducing badge paths,
although the listing of badges according to their age needs looking into.
3. The per-user listing of badges could use some organization according to categories
and/or badge paths but favourite badges can be picked and shown on the profile card,
which makes these badges more than a royal collectible but something to start
discussions around.
4. The leaderboards also remain something to be seen, though the implementation should
be fairly easy if we are to have the same format as that of the current frontend
(i.e. show weekly, monthly and all-time leaders). The badge count for the users
should be added too.
5. The use of Discourse's internal badge levels alongside our badge paths has a
possibility of doing more harm than good, as it allegedly allows for only
three levels (i.e. bronze, silver and gold). This might confuse the frontend
if certain badges of a path belong to a level or tier.
6. The UI for manually awarding badges is allegedly restricted to only those
who are admins of the forum. Integrating that access capacity with a FAS
group should allow for members belonging to that group to award badges while
restricting them from any other admin-like operations.
7. The inclusion of QR codes or links to receive badges does not seem to be a
feature on the Discourse frontend but it is something that we could play
around with and implement using automation scripts. Also, there should be a
way for folks to opt-in or opt-out of these as they fit.
possibility of doing more harm than good, as it allegedly allows for only three
levels (i.e. bronze, silver and gold). This might confuse the frontend if certain
badges of a path belong to a level or tier.
6. The UI for manually awarding badges is allegedly restricted to only those who are
admins of the forum. Integrating that access capacity with a FAS group should allow
for members belonging to that group to award badges while restricting them from any
other admin-like operations.
7. The inclusion of QR codes or links to receive badges does not seem to be a feature on
the Discourse frontend but it is something that we could play around with and
implement using automation scripts. Also, there should be a way for folks to opt-in
or opt-out of these as they fit.
The following are the pain-points we derived out of the study.
1. There are possibilities that the users would get bombarded with loads of
notifications as they receive loads of badges in a short duration of time.
If this is understood correctly, this issue can be safely ignored as this
happens to be a one-time problem only.
2. There can be times when the user can have their account activated for
Fedora Badges and not on Discourse, or vice-versa. We would require to
rework the database (and the access to it from the Discourse frontend) to
ensure that the Badges database has the precedence.
1. There are possibilities that the users would get bombarded with loads of
notifications as they receive loads of badges in a short duration of time. If this is
understood correctly, this issue can be safely ignored as this happens to be a
one-time problem only.
2. There can be times when the user can have their account activated for Fedora Badges
and not on Discourse, or vice-versa. We would require to rework the database (and the
access to it from the Discourse frontend) to ensure that the Badges database has the
precedence.
How to go about it?
----
-------------------
We swap out the Liberation entity part from the
`internal entity chart <https://fedora-arc.readthedocs.io/en/latest/_images/badges-proposed-architecture.png>`_
and replace it with the Discourse frontend. The interactions, for the most
parts, should stay the same but a considerably different set of technologies
would be required to work on the Discourse frontend.
We swap out the Liberation entity part from the `internal entity chart
<https://fedora-arc.readthedocs.io/en/latest/_images/badges-proposed-architecture.png>`_
and replace it with the Discourse frontend. The interactions, for the most parts, should
stay the same but a considerably different set of technologies would be required to work
on the Discourse frontend.
Is there a Plan B?
----
------------------
Of course, there is. Just in case, the proposal for the use of the Discourse
frontend is not met with the community's approval or if it becomes too
difficult to work on - we can always make the current implementation of
integration work with the redeveloped system. In this way, we can have our own
frontend all while ensuring that our badges are not left behind catching
electronic dust by giving them the attention on the Fedora Discussions forum,
with their use as custom titles and listing them on the user cards.
Of course, there is. Just in case, the proposal for the use of the Discourse frontend is
not met with the community's approval or if it becomes too difficult to work on - we can
always make the current implementation of integration work with the redeveloped system.
In this way, we can have our own frontend all while ensuring that our badges are not
left behind catching electronic dust by giving them the attention on the Fedora
Discussions forum, with their use as custom titles and listing them on the user cards.
Further reading
----
---------------
1. `Discourse Badges - should we or shouldn't we? <https://discussion.fedoraproject.org/t/discourse-badges-should-we-or-shouldnt-we/34698>`_
1. `Discourse Badges - should we or shouldn't we?
<https://discussion.fedoraproject.org/t/discourse-badges-should-we-or-shouldnt-we/34698>`_
2. `Badges on Fedora Discussions <https://discussion.fedoraproject.org/badges>`_
3. `Exploring the idea of using Discourse as a badges frontend — the backend implications <https://discussion.fedoraproject.org/t/exploring-the-idea-of-using-discourse-as-a-badges-frontend-the-backend-implications/34887>`_
4. `Magical Experimental Fedora Badges Topic! <https://discussion.fedoraproject.org/t/magical-experimental-fedora-badges-topic/35007>`_
5. `Badges-to-Discourse experiment... notes on Discourse as a badges front-end <https://discussion.fedoraproject.org/t/badges-to-discourse-experiment-notes-on-discourse-as-a-badges-front-end/35262>`_
3. `Exploring the idea of using Discourse as a badges frontend — the backend
implications
<https://discussion.fedoraproject.org/t/exploring-the-idea-of-using-discourse-as-a-badges-frontend-the-backend-implications/34887>`_
4. `Magical Experimental Fedora Badges Topic!
<https://discussion.fedoraproject.org/t/magical-experimental-fedora-badges-topic/35007>`_
5. `Badges-to-Discourse experiment... notes on Discourse as a badges front-end
<https://discussion.fedoraproject.org/t/badges-to-discourse-experiment-notes-on-discourse-as-a-badges-front-end/35262>`_

123
docs/badges/exploring_the_development_environment.rst
View file

@ -1,104 +1,101 @@
.. _exploring_the_development_environment:
Exploring the development environment
====
=====================================
This document will go through all repositories of Badges project
and describe the state of development environment and how it could be improved.
This document will go through all repositories of Badges project and describe the state
of development environment and how it could be improved.
Tahrir
----
------
`Tahrir <https://github.com/fedora-infra/tahrir>`_ is a Fedora badges frontend.
The guide for setting up development environment is described in
`DEVELOPING.md <https://github.com/fedora-infra/tahrir/blob/develop/DEVELOPING.md>`_
and it's using `Vagrant <https://www.vagrantup.com/>`_.
`Tahrir <https://github.com/fedora-infra/tahrir>`_ is a Fedora badges frontend. The
guide for setting up development environment is described in `DEVELOPING.md
<https://github.com/fedora-infra/tahrir/blob/develop/DEVELOPING.md>`_ and it's using
`Vagrant <https://www.vagrantup.com/>`_.
Vagrantfile.example is using F29, which is no longer available. Updated this to F36,
but encountered issue when tried to provision the machine by ansible
`Failed to connect to the host via ssh: Shared connection to xxx.xxx.xxx.xxx closed.`
Solved by defining the domain of VM in Vagrantfile::
Vagrantfile.example is using F29, which is no longer available. Updated this to F36, but
encountered issue when tried to provision the machine by ansible `Failed to connect to
the host via ssh: Shared connection to xxx.xxx.xxx.xxx closed.` Solved by defining the
domain of VM in Vagrantfile:
config.vm.define "tahrir" do |tahrir|
tahrir.vm.host_name = "tahrir.example.com"
.. code-block::
tahrir.vm.provider :libvirt do |domain|
# Season to taste
domain.cpus = 4
domain.graphics_type = "spice"
domain.memory = 2048
domain.video_type = "qxl"
config.vm.define "tahrir" do |tahrir|
tahrir.vm.host_name = "tahrir.example.com"
tahrir.vm.provider :libvirt do |domain|
# Season to taste
domain.cpus = 4
domain.graphics_type = "spice"
domain.memory = 2048
domain.video_type = "qxl"
end
end
end
The installation of the tahrir needed a specific version of setuptools (57.5.0),
later version doesn’t have 2to3 in it.
The installation of the tahrir needed a specific version of setuptools (57.5.0), later
version doesn’t have 2to3 in it.
The provisioning steps in the ansible needed to be done manually, because of this setuptools issue.
Installation in a virtual environment inside the vagrant machine was finished successfully.
The provisioning steps in the ansible needed to be done manually, because of this
setuptools issue. Installation in a virtual environment inside the vagrant machine was
finished successfully.
Initialization of the database failed on
`ImportError: cannot import name 'ZopeTransactionExtension' from 'zope.sqlalchemy'`.
To get over this I needed to remove `extension=ZopeTransactionExtension()` and corresponding import
from `.venv/lib64/python3.8/site-packages/tahrir_api-0.8.1-py3.8.egg/tahrir_api/model.py`.
Initialization of the database failed on `ImportError: cannot import name
'ZopeTransactionExtension' from 'zope.sqlalchemy'`. To get over this I needed to remove
`extension=ZopeTransactionExtension()` and corresponding import from
`.venv/lib64/python3.8/site-packages/tahrir_api-0.8.1-py3.8.egg/tahrir_api/model.py`.
Next issue during the initialization of DB was `ModuleNotFoundError: No module named 'utils'`
Fixed this by adding `.` before local imports in
Next issue during the initialization of DB was `ModuleNotFoundError: No module named
'utils'` Fixed this by adding `.` before local imports in
`.venv/lib64/python3.8/site-packages/tahrir_api-0.8.1-py3.8.egg/tahrir_api/dbapi.py`
This was the end of the provisioning phase.
When trying to run `pserve --reload development.ini` I ended up with error
`TypeError: SignedCookieSessionFactory() got an unexpected keyword argument 'cookie_secure'`
Fixed by removing `cookie_` prefix from
`SignedCookieSessionFactory` call in `/vagrant/tahrir/__init__.py`
When trying to run `pserve --reload development.ini` I ended up with error `TypeError:
SignedCookieSessionFactory() got an unexpected keyword argument 'cookie_secure'` Fixed
by removing `cookie_` prefix from `SignedCookieSessionFactory` call in
`/vagrant/tahrir/__init__.py`
Another error
`ImportError: cannot import name 'authenticated_userid' from 'pyramid.security' (unknown location)`
Fixed this by changing the dependency `pyramid < 2.0` in `setup.py`
See https://github.com/stevearc/pypicloud/issues/274 for more info
Another error `ImportError: cannot import name 'authenticated_userid' from
'pyramid.security' (unknown location)` Fixed this by changing the dependency `pyramid <
2.0` in `setup.py` See https://github.com/stevearc/pypicloud/issues/274 for more info
After that the instance is running, but it’s not accessible outside of the VM.
When trying curl http://0.0.0.0:8000 it throws error
`TypeError: __init__() got an unexpected keyword argument 'extension'`
After that the instance is running, but it’s not accessible outside of the VM. When
trying curl http://0.0.0.0:8000 it throws error `TypeError: __init__() got an unexpected
keyword argument 'extension'`
At this point we wouldn't want to put more effort in it, because it means starting to fix
issues in app itself and this is not part of the investigation.
At this point we wouldn't want to put more effort in it, because it means starting to
fix issues in app itself and this is not part of the investigation.
Recommendation
^^^^
~~~~~~~~~~~~~~
Before fixing the development environment Tahrir needs to be updated to python 3.0, so
it could run no never versions of Fedora.
The development environment itself could be used with few enhancements. See investigation
above.
The development environment itself could be used with few enhancements. See
investigation above.
tahrir_api
----
----------
tahrir_api is part of Fedora Badges backend and provides API and database to work with.
The guide for setting up development environment is available in
`README <https://github.com/fedora-infra/tahrir-api#readme>`_ and it's using Python
virtual environment.
The guide for setting up development environment is available in `README
<https://github.com/fedora-infra/tahrir-api#readme>`_ and it's using Python virtual
environment.
The guide is working without issue, but it's missing any tools to work with tahrir_api
itself.
Recommendation
^^^^
Provide guide or tools to work with standalone tahrir_api in development environment.
**Recommendation**
Provide guide or tools to work with standalone tahrir_api in development
environment.
fedbadges
----
---------
fedbadges is part of Fedora Badges backend and provides consumer for fedmsg messages.
There is no guide or any description of development environment.
Recommendation
^^^^
Create a development environment that allows you to work with fedbadges and document
it.
**Recommendation**
Create a development environment that allows you to work with fedbadges and document
it.

121
docs/badges/index.rst
View file

@ -1,94 +1,93 @@
Fedora Badges
====
=============
Purpose
----
-------
Fedora Badges is a service that grants virtual accolades for milestones and
completing tasks within the Fedora Project community. For example, a community
member may collect badges for testing package updates on Bodhi when they test
1, 5, 10, 20, 40, 80, 125, 250, 500 and 1000 updates.
Fedora Badges is a service that grants virtual accolades for milestones and completing
tasks within the Fedora Project community. For example, a community member may collect
badges for testing package updates on Bodhi when they test 1, 5, 10, 20, 40, 80, 125,
250, 500 and 1000 updates.
Community members can also gather badges for attending events, or other badges
that are arbitrarily granted by users of the service, such as the badge the
Fedora Project Leader can grant whenever they want to.
Community members can also gather badges for attending events, or other badges that are
arbitrarily granted by users of the service, such as the badge the Fedora Project Leader
can grant whenever they want to.
Background
----
----------
It appears that Fedora Badges was initially designed closely in step with
`Open Badges <https://en.wikipedia.org/wiki/Mozilla_Open_Badges>`_ which now
has become `Badgr <https://badgr.com/>`_. As far as we can tell, the idea was
previously to be able to export Fedora Badges into Mozilla Backpack (or now,
Badgr Backpack) but this export facility was either never implemented or
deployed.
It appears that Fedora Badges was initially designed closely in step with `Open Badges
<https://en.wikipedia.org/wiki/Mozilla_Open_Badges>`_ which now has become `Badgr
<https://badgr.com/>`_. As far as we can tell, the idea was previously to be able to
export Fedora Badges into Mozilla Backpack (or now, Badgr Backpack) but this export
facility was either never implemented or deployed.
At some point in time, there also appears to have been an
`free and open source implementation of the Badgr server <https://github.com/concentricsky/badgr-server>`_
itself, which may have been a solution to replace the Fedora Badges setup, but
this project is either no longer available or set to be private on GitHub, so
it is not known what it was or is. For now, Badgr is just a service that
allows users to collate their badges from different issues into their
"backpack".
At some point in time, there also appears to have been an `free and open source
implementation of the Badgr server <https://github.com/concentricsky/badgr-server>`_
itself, which may have been a solution to replace the Fedora Badges setup, but this
project is either no longer available or set to be private on GitHub, so it is not known
what it was or is. For now, Badgr is just a service that allows users to collate their
badges from different issues into their "backpack".
Resources
----
---------
* `Fedora Badges backend <https://github.com/fedora-infra/fedbadges/>`_
* `Fedora Badges frontend <https://github.com/fedora-infra/tahrir>`_
* `Issue ticket about the ongoing efforts of revitalization <https://github.com/fedora-infra/fedbadges/issues/90>`_
* `Infrastructure developer guide <https://docs.fedoraproject.org/en-US/infra/developer_guide/>`_
* `Badges documentation in Fedora docs <https://docs.fedoraproject.org/en-US/badges/>`_
- `Fedora Badges backend <https://github.com/fedora-infra/fedbadges/>`_
- `Fedora Badges frontend <https://github.com/fedora-infra/tahrir>`_
- `Issue ticket about the ongoing efforts of revitalization
<https://github.com/fedora-infra/fedbadges/issues/90>`_
- `Infrastructure developer guide
<https://docs.fedoraproject.org/en-US/infra/developer_guide/>`_
- `Badges documentation in Fedora docs <https://docs.fedoraproject.org/en-US/badges/>`_
Index
----
-----
.. toctree::
:maxdepth: 1
current_implementation
exploring_the_development_environment
expectations_and_wishes
proposal_rewrite
proposal_revitalize
discourse_integration
Conclusions
----
-----------
Having explored both the options (i.e. of rewriting the project that consitute
the system from ground up and of revitalizing the existing codebase), we have
come to a conclusion that it makes a lot more sense to inherit and expand upon
the methodologies employed in the current codebase but implement the same from
groundup in a new functional rewrite.
Having explored both the options (i.e. of rewriting the project that consitute the
system from ground up and of revitalizing the existing codebase), we have come to a
conclusion that it makes a lot more sense to inherit and expand upon the methodologies
employed in the current codebase but implement the same from groundup in a new
functional rewrite.
Proposed roadmap
----
----------------
* Step 1 - Understand the project remit of the system to decide on the scope
* Step 2 - Get started with creating/inheriting the database schema for users
* Step 3 - Dump a snapshot of the existing database according to the new schema
* Step 4 - Brainstorm and document the interactions expected with the system
* Step 5 - Connect with the Fedora Design team to begin with the mockup designs
* Step 6 - Develop and document the Messages Consumer alongside Accolades API
* Step 7 - Test both against the dumped database and the existing Collection
* Step 8 - Develop and document the Accolades CLI and test its functionality
* Step 9 - Build Liberation frontend alongside the Fedora Websites & Apps Team
* Step 10 - Document and Test the frontend against the above mentioned entities
* Step 11 - Deploy and document the system on STAGING with the Fedora Infra team
* Step 12 - Release Accolades CLI as a Python package on PyPI and as RPM
* Step 13 - Announce public testing invites for the staging deployment
* Step 14 - Announce deprecation status for the existing Fedora Badges system
* Step 15 - Migrate database changes continually to keep up with the changes
* Step 16 - Switch the environment to production and... PROFIT?
- Step 1 - Understand the project remit of the system to decide on the scope
- Step 2 - Get started with creating/inheriting the database schema for users
- Step 3 - Dump a snapshot of the existing database according to the new schema
- Step 4 - Brainstorm and document the interactions expected with the system
- Step 5 - Connect with the Fedora Design team to begin with the mockup designs
- Step 6 - Develop and document the Messages Consumer alongside Accolades API
- Step 7 - Test both against the dumped database and the existing Collection
- Step 8 - Develop and document the Accolades CLI and test its functionality
- Step 9 - Build Liberation frontend alongside the Fedora Websites & Apps Team
- Step 10 - Document and Test the frontend against the above mentioned entities
- Step 11 - Deploy and document the system on STAGING with the Fedora Infra team
- Step 12 - Release Accolades CLI as a Python package on PyPI and as RPM
- Step 13 - Announce public testing invites for the staging deployment
- Step 14 - Announce deprecation status for the existing Fedora Badges system
- Step 15 - Migrate database changes continually to keep up with the changes
- Step 16 - Switch the environment to production and... PROFIT?
Of course, there are and will be more things to account for than what meets
the eye but from a Mount Everest high perspective - these are the steps we
would want to suggest in the roadmap.
Of course, there are and will be more things to account for than what meets the eye but
from a Mount Everest high perspective - these are the steps we would want to suggest in
the roadmap.
Estimate of work
----
----------------
Being a remake of a system with multiple internal entities working together,
it is estimated for the system to take at least 4 quarters to hit the staging
environment and 1 more quarter to make it to the production one.
Being a remake of a system with multiple internal entities working together, it is
estimated for the system to take at least 4 quarters to hit the staging environment and
1 more quarter to make it to the production one.

210
docs/badges/prop_rewrite_entities.rst
View file

@ -1,146 +1,132 @@
.. _prop_rewrite_entities:
Entities involved
====
=================
Let us dive deep into the entities that would come together to make the Fedora
Badges project functional. We will call them "entities" for the context of this
discussion. Also, the names used for the entities here are temporary in nature
and are, for the most parts, only representative of the functions that these
entities perform.
Let us dive deep into the entities that would come together to make the Fedora Badges
project functional. We will call them "entities" for the context of this discussion.
Also, the names used for the entities here are temporary in nature and are, for the most
parts, only representative of the functions that these entities perform.
Here is a diagram exhibiting the proposed architecture.
.. image:: ../_static/badges-proposed-architecture.png
:target: ../_images/badges-proposed-architecture.png
Internal entities
----
-----------------
**Accolades API** - Backend service
1. Succeeds the existing
`Tahrir <https://github.com/fedora-infra/tahrir>`_'s backend API and/or
is planned to be a reimplementation of the same.
2. This is planned to act as the backend service for the entire project and
has direct interactions with its neighbouring internal entities (i.e.
Collection, Database, Liberation, Messages Consumer, Accolades CLI).
1. Succeeds the existing `Tahrir <https://github.com/fedora-infra/tahrir>`_'s
backend API and/or is planned to be a reimplementation of the same.
2. This is planned to act as the backend service for the entire project and has
direct interactions with its neighbouring internal entities (i.e. Collection,
Database, Liberation, Messages Consumer, Accolades CLI).
**Accolades CLI** - Client application
1. Succeeds the existing
`Tahrir API <https://github.com/fedora-infra/tahrir-api>`_ client and/or
is planned to be a reimplementation of the same.
2. This is planned to act as a client application and/or library, usable for
automating purposes like pushing of badges (and their related awarding
conditions) to the Collection via the Accolades API, and other such high
level interactions offered by the Accolades API.
3. This is planned to be a standalone entity with just one possible
interaction with the neighbouring internal entity (i.e. Accolades API)
and three possible interactions with the neighbouring external entity
(i.e. community users, badge owners and service admins).
1. Succeeds the existing `Tahrir API <https://github.com/fedora-infra/tahrir-api>`_
client and/or is planned to be a reimplementation of the same.
2. This is planned to act as a client application and/or library, usable for
automating purposes like pushing of badges (and their related awarding
conditions) to the Collection via the Accolades API, and other such high level
interactions offered by the Accolades API.
3. This is planned to be a standalone entity with just one possible interaction with
the neighbouring internal entity (i.e. Accolades API) and three possible
interactions with the neighbouring external entity (i.e. community users, badge
owners and service admins).
**Liberation** - Web interface
1. Succeeds the existing
`Tahrir <https://github.com/fedora-infra/tahrir>`_'s frontend part and/or
is planned to be a reimplementation of the same.
2. This is planned to act as an interactive client application, accessible
via modern web browsers, usable by community members and service admins
for purposes like looking up the Fedora Badges leaderboard, checking
badges awarded to self or someone else etc. and adding new badges (and
their related awarding conditions) etc. respectively by interacting with
the Accolades API.
3. This is planned to be a standalone entity with just one possible
interaction with the neighbouring internal entity (i.e. Accolades API)
and three possible interactions with the neighbouring external entity
(i.e. community users, badge owners and service admins).
1. Succeeds the existing `Tahrir <https://github.com/fedora-infra/tahrir>`_'s
frontend part and/or is planned to be a reimplementation of the same.
2. This is planned to act as an interactive client application, accessible via
modern web browsers, usable by community members and service admins for purposes
like looking up the Fedora Badges leaderboard, checking badges awarded to self or
someone else etc. and adding new badges (and their related awarding conditions)
etc. respectively by interacting with the Accolades API.
3. This is planned to be a standalone entity with just one possible interaction with
the neighbouring internal entity (i.e. Accolades API) and three possible
interactions with the neighbouring external entity (i.e. community users, badge
owners and service admins).
**Collection** - Artworks and rules
1. Succeeds the existing `Fedora Badges <https://pagure.io/fedora-badges>`_
repository and/or is planned to be a reimplementation of the same.
2. This is planned to be a repository of supporting assets (artworks,
awarding conditions, consumer rules etc.) for the badges available for
being awarded to the community members, which can be read from and
updated by the interactions with the Accolades API entity and the
Liberation entity as well as by admins having relevant accesses to the
repository.
3. This is planned to be a standalone entity with just one possible
interaction with the neighbouring internal entity (i.e. Accolades API)
and one possible interaction with the neighbouring external entity (i.e.
repository members).
1. Succeeds the existing `Fedora Badges <https://pagure.io/fedora-badges>`_
repository and/or is planned to be a reimplementation of the same.
2. This is planned to be a repository of supporting assets (artworks, awarding
conditions, consumer rules etc.) for the badges available for being awarded to
the community members, which can be read from and updated by the interactions
with the Accolades API entity and the Liberation entity as well as by admins
having relevant accesses to the repository.
3. This is planned to be a standalone entity with just one possible interaction with
the neighbouring internal entity (i.e. Accolades API) and one possible
interaction with the neighbouring external entity (i.e. repository members).
**Database** - Achievements storage
1. Succeeds the existing Fedora Badges database storage for storing the
badges awarded to community members, date of felicitation and other
details and/or is planned to be a reimplementation of the same.
2. A huge chunk of the existing database is planned to be reimported into
the newer schema and the columns specific to the Open Badges (or Badgr)
compatibility will not be taken into consideration. This can be read
into and updated by the interactions with the Accolades API only.
3. This is planned to be a standalone entity with just one possible
interaction with the neighbouring internal entity (i.e. Accolades API)
and one possible interaction with the neighbouring external entity (i.e.
service admins).
1. Succeeds the existing Fedora Badges database storage for storing the badges
awarded to community members, date of felicitation and other details and/or is
planned to be a reimplementation of the same.
2. A huge chunk of the existing database is planned to be reimported into the newer
schema and the columns specific to the Open Badges (or Badgr) compatibility will
not be taken into consideration. This can be read into and updated by the
interactions with the Accolades API only.
3. This is planned to be a standalone entity with just one possible interaction with
the neighbouring internal entity (i.e. Accolades API) and one possible
interaction with the neighbouring external entity (i.e. service admins).
**Messages consumer** - Conditions listener
1. Succeeds the existing
`fedbadges <https://github.com/fedora-infra/fedbadges>`_ fedmsg listener
and/or is planned to be a reimplementation of the same.
2. This is planned to act as a messages consumer, listening into the Fedora
Messaging bus matching the schemas that it is configured for and
comparing the messages against the awarding conditions available on the
Collection, and on a successful match, making a request to the Accolades
API for awarding the said badge to a certain contributor who have met the
conditions specified in the related badge rule.
3. This is planned to be a standalone entity with two possible interactions
with the neighbouring internal entities (i.e. Accolades API and
Collection) and no possible interaction with the neighbouring external
entities.
1. Succeeds the existing `fedbadges <https://github.com/fedora-infra/fedbadges>`_
fedmsg listener and/or is planned to be a reimplementation of the same.
2. This is planned to act as a messages consumer, listening into the Fedora
Messaging bus matching the schemas that it is configured for and comparing the
messages against the awarding conditions available on the Collection, and on a
successful match, making a request to the Accolades API for awarding the said
badge to a certain contributor who have met the conditions specified in the
related badge rule.
3. This is planned to be a standalone entity with two possible interactions with the
neighbouring internal entities (i.e. Accolades API and Collection) and no
possible interaction with the neighbouring external entities.
External entities
----
-----------------
**Service admins** - Access Level IV
1. Consists of people belonging to the
`Badges Administrators <https://accounts.fedoraproject.org/group/sysadmin-badges/>`_
group.
2. People have access to the deployment environments (staging, development,
production etc.) and can control most of the aspects of all the internal
entities.
1. Consists of people belonging to the `Badges Administrators
<https://accounts.fedoraproject.org/group/sysadmin-badges/>`_ group.
2. People have access to the deployment environments (staging, development,
production etc.) and can control most of the aspects of all the internal
entities.
**Badge owners** - Access Level III
1. Consists of people who either lead or represent certain subcommunity, SIG
or subproject within the Fedora Project community, who want to make new
badges available and set rules for awarding.
2. People have an elevated access to the Liberation and Accolades CLI, which
enables them to access, create, change, award and delete badges that
they "own" (not those that they "have been awarded").
3. If there does not exist a designated IPA group for marking out these
entities, a new one can be created and they can be added to the same for
easing access control processes.
1. Consists of people who either lead or represent certain subcommunity, SIG or
subproject within the Fedora Project community, who want to make new badges
available and set rules for awarding.
2. People have an elevated access to the Liberation and Accolades CLI, which enables
them to access, create, change, award and delete badges that they "own" (not
those that they "have been awarded").
3. If there does not exist a designated IPA group for marking out these entities, a
new one can be created and they can be added to the same for easing access
control processes.
**Repository members** - Access Level II
1. Consists of people who either design, create and/or facilitate new badges
and want to make them available and set rules for awarding.
2. These are the people who can fall under the "Badge owners" category too
but that might not necessarily be the case always (for eg. badge
designers who do not lead or represent another subcommunity, SIG or
subproject but are tasked to create and upload badge assets).
3. There need not be a designated IPA group for marking out these entities
as their access is restricted to accessing, creating, changing and
deleting badges assets available on the Collection entity, which is
simply a version control system mediated repository.
1. Consists of people who either design, create and/or facilitate new badges and
want to make them available and set rules for awarding.
2. These are the people who can fall under the "Badge owners" category too but that
might not necessarily be the case always (for eg. badge designers who do not lead
or represent another subcommunity, SIG or subproject but are tasked to create and
upload badge assets).
3. There need not be a designated IPA group for marking out these entities as their
access is restricted to accessing, creating, changing and deleting badges assets
available on the Collection entity, which is simply a version control system
mediated repository.
**Community Users** - Access Level I
1. Consists of generally everyone from the Fedora Project community who have
a valid and activated, `IPA account <https://accounts.fedoraproject.org/>`_
and have signed the
`Fedora Project Contributor Agreement <https://accounts.fedoraproject.org/user/t0xic0der/settings/agreements/>`_.
2. These are the people who are eligible to only receive badges for their
recordable actions (i.e. those which either trigger a message on the
Fedora Messaging bus or are noticed by a Badge Owner entity) within the
Fedora Project community.
1. Consists of generally everyone from the Fedora Project community who have a valid
and activated, `IPA account <https://accounts.fedoraproject.org/>`_ and have
signed the `Fedora Project Contributor Agreement
<https://accounts.fedoraproject.org/user/t0xic0der/settings/agreements/>`_.
2. These are the people who are eligible to only receive badges for their recordable
actions (i.e. those which either trigger a message on the Fedora Messaging bus or
are noticed by a Badge Owner entity) within the Fedora Project community.
**NOTE** - These access levels are not exclusive in nature. A person who has an
Access Level IV, can (but not necessarily will) have those beneath it too and
by default, every FPCA signed member of the Fedora Project community, has at
least, Access Level I.
**NOTE** - These access levels are not exclusive in nature. A person who has an Access
Level IV, can (but not necessarily will) have those beneath it too and by default, every
FPCA signed member of the Fedora Project community, has at least, Access Level I.

319
docs/badges/prop_rewrite_interactions.rst
View file

@ -1,241 +1,228 @@
.. _prop_rewrite_interactions:
Interactions possible
====
=====================
The interactions between the previously mentioned entities would dictate the
workflow of the project and the direction of the flow of information among
multiple entities involved in an interaction. They are denoted by the line
connecting the entities and can be distinguished using the labels written on
the top of the aforementioned joining lines.
The interactions between the previously mentioned entities would dictate the workflow of
the project and the direction of the flow of information among multiple entities
involved in an interaction. They are denoted by the line connecting the entities and can
be distinguished using the labels written on the top of the aforementioned joining
lines.
Internal-only interactions
----
--------------------------
Interactions involving only internal entities are termed, in this context, as
internal-only interactions.
internal-only interactions.
.. image:: ../_static/badges-proposed-architecture.png
:target: ../_images/badges-proposed-architecture.png
AA
^^^^
~~
1. Defines the interaction between entities, Accolades CLI and Accolades API.
2. Accolades CLI can help abstract reading, creating, changing and deleting of
badge related assets or information with the help of the endpoints that the
Accolades API provides.
3. This interaction causes DA and CA interactions to take place, as the data
requested is read from and data modified is changed into the Database and
Collection entities. For eg. fetching information about the badges awarded
to a certain user from the Database entity (DA) and automating adding new
badges with the awarding conditions to the Collection entity (CA).
4. This interaction affects LA and MA interactions as changes made to the
Accolades API would affect how it reacts to the actions made by the
Liberation and Message Consumer entities. For eg. new badges added into the
Collection entity might show up on the catalog of the Liberation entity (LA)
and the awarding condition added to the Collection entity would change the
way the Message Consumer behaves in awarding badges (MA).
2. Accolades CLI can help abstract reading, creating, changing and deleting of badge
related assets or information with the help of the endpoints that the Accolades API
provides.
3. This interaction causes DA and CA interactions to take place, as the data requested
is read from and data modified is changed into the Database and Collection entities.
For eg. fetching information about the badges awarded to a certain user from the
Database entity (DA) and automating adding new badges with the awarding conditions to
the Collection entity (CA).
4. This interaction affects LA and MA interactions as changes made to the Accolades API
would affect how it reacts to the actions made by the Liberation and Message Consumer
entities. For eg. new badges added into the Collection entity might show up on the
catalog of the Liberation entity (LA) and the awarding condition added to the
Collection entity would change the way the Message Consumer behaves in awarding
badges (MA).
LA
^^^^
~~
1. Defines the interaction between entities, Liberation and Accolades API.
2. Liberation provides an interactive web interface for abstracting reading,
creating, changing, awarding and deleting of badge related assets or
information with the help of the endpoints that the Accolades API provides.
3. This interaction causes DA and CA interactions to take place, as the data
requested is read from and data modified is changed into the Database and
Collection entities. For eg. displaying the leaderboard of the top 100
community members by fetching it from the Database entity (DA) and adding
new badges with the awarding conditions to the Collection entity (CA).
4. This interaction affects AA and MA interactions as changes made to the
Accolades API would affect how it reacts to the actions made by the
Accolades CLI and Message Consumer entities. For eg. newly awarded badge
from Liberation would show up on the Accolades CLI for the user querying
about that information (AA) and the awarding condition added to the
Collection entity would change the way the Message Consumer behaves in
awarding badges (MA).
2. Liberation provides an interactive web interface for abstracting reading, creating,
changing, awarding and deleting of badge related assets or information with the help
of the endpoints that the Accolades API provides.
3. This interaction causes DA and CA interactions to take place, as the data requested
is read from and data modified is changed into the Database and Collection entities.
For eg. displaying the leaderboard of the top 100 community members by fetching it
from the Database entity (DA) and adding new badges with the awarding conditions to
the Collection entity (CA).
4. This interaction affects AA and MA interactions as changes made to the Accolades API
would affect how it reacts to the actions made by the Accolades CLI and Message
Consumer entities. For eg. newly awarded badge from Liberation would show up on the
Accolades CLI for the user querying about that information (AA) and the awarding
condition added to the Collection entity would change the way the Message Consumer
behaves in awarding badges (MA).
DA
^^^^
~~
1. Defines the interaction between entities, Database and Accolades API.
2. Database stores the information of the achievements made by the community
members by their recordable actions within the Fedora Project community,
along with the metadata of when the badges were awarded etc.
3. This interaction cannot be directly triggered and can only happen as a cause
of LA, AA and MA interactions. As a result, this interaction does not become
a causative agent for any other interaction. For eg. awarding a user with a
badge from the Liberation entity would lead to changes made in the Database
entity (LA), querying about the badges achieved by a user in the Accolades
CLI entity requires reading information from the Database entity (AA) and
conditioned awards made from the Message Consumer entity would be reflected
on the Database entity (MA).
4. This interaction affects only those interactions, that cause it to happen in
the first place. This can be explained as the consequences of the
aforementioned example interactions - for eg. Liberation entity would be
able to see the badge under the username that it was awarded to recently
(LA) and Accolades CLI entity would be able to retrieve the information it
requested for (AA) but the MA interaction would stay unaffected.
CA
^^^^
1. Defines the interaction between entities, Collection and Accolades API.
2. Collection entity stores the badge assets (artworks, badge rules, awarding
conditions etc.) that the Accolades API can read content from, add new
badges, change/update and delete/remove existing ones.
3. This interaction cannot be directly triggered and can only happen as a
cause of internal interactions like LA, AA, DA and MA as well as external
interactions like changes made into the Collection entity by external
entities like Repository Members etc. For eg. adding new badges for
distribution using the Liberation entity (LA) and doing so using the
Accolades CLI (AA) would lead to changes in the Collection entity, changes
in the database due to the awarding of badges would require reading
information from the Collection entity (DA) and rules on how the Message
Consumer entity would award badges would be described by the conditions
mentioned in the Collection entity (MA).
4. This interaction affects only those interactions, that cause it to happen
in the first place. This can be explained as the consequences of the
aforementioned examples - for eg. addition of new badge for distribution
would cause it to be accessible on Liberation entity (LA) and on Accolades
API (AA), Message Consumer entity would now have new rules as a result to
changes in the Collection entity (MA) but the DA interaction would stay
2. Database stores the information of the achievements made by the community members by
their recordable actions within the Fedora Project community, along with the metadata
of when the badges were awarded etc.
3. This interaction cannot be directly triggered and can only happen as a cause of LA,
AA and MA interactions. As a result, this interaction does not become a causative
agent for any other interaction. For eg. awarding a user with a badge from the
Liberation entity would lead to changes made in the Database entity (LA), querying
about the badges achieved by a user in the Accolades CLI entity requires reading
information from the Database entity (AA) and conditioned awards made from the
Message Consumer entity would be reflected on the Database entity (MA).
4. This interaction affects only those interactions, that cause it to happen in the
first place. This can be explained as the consequences of the aforementioned example
interactions - for eg. Liberation entity would be able to see the badge under the
username that it was awarded to recently (LA) and Accolades CLI entity would be able
to retrieve the information it requested for (AA) but the MA interaction would stay
unaffected.
MA
^^^^
CA
~~
1. Defines the interaction between entities, Messages Consumer and Accolades
API.
2. Message Consumer listens in to the Fedora Messaging bus and compares the
messages against the awarding conditions, and when the said condition is
satisfied, it makes a request to the Accolades API to award an external
entity, a certain Community User with the relevant badge.
3. This interaction cannot be directly triggered and can only happen as a
cause of internal interactions like CM and CA. For eg. any new additions
made to the Collection entity would change the way the Message Consumer
entity checks for conditions for badges (CA) and the Message Consumer would
read the content regarding the badges from the Collection entity (CM).
4. This interaction affects DA, LA and AA interactions as changes made to the
Accolades API entity by the Messages Consumer entity would affect how it
reacts to the actions made into the Database entity, by the Liberation
entity and Message Consumer entities. For eg. badges awarded automatically
by the Messsage Consumer entity's interaction would cause a change to be
made on the Database entity (DA) and lead them to be visible on the
Liberation entity (LA) and accessible on the Accolades CLI entity (AA).
1. Defines the interaction between entities, Collection and Accolades API.
2. Collection entity stores the badge assets (artworks, badge rules, awarding conditions
etc.) that the Accolades API can read content from, add new badges, change/update and
delete/remove existing ones.
3. This interaction cannot be directly triggered and can only happen as a cause of
internal interactions like LA, AA, DA and MA as well as external interactions like
changes made into the Collection entity by external entities like Repository Members
etc. For eg. adding new badges for distribution using the Liberation entity (LA) and
doing so using the Accolades CLI (AA) would lead to changes in the Collection entity,
changes in the database due to the awarding of badges would require reading
information from the Collection entity (DA) and rules on how the Message Consumer
entity would award badges would be described by the conditions mentioned in the
Collection entity (MA).
4. This interaction affects only those interactions, that cause it to happen in the
first place. This can be explained as the consequences of the aforementioned examples
- for eg. addition of new badge for distribution would cause it to be accessible on
Liberation entity (LA) and on Accolades API (AA), Message Consumer entity would now
have new rules as a result to changes in the Collection entity (MA) but the DA
interaction would stay unaffected.
MA
~~
1. Defines the interaction between entities, Messages Consumer and Accolades API.
2. Message Consumer listens in to the Fedora Messaging bus and compares the messages
against the awarding conditions, and when the said condition is satisfied, it makes a
request to the Accolades API to award an external entity, a certain Community User
with the relevant badge.
3. This interaction cannot be directly triggered and can only happen as a cause of
internal interactions like CM and CA. For eg. any new additions made to the
Collection entity would change the way the Message Consumer entity checks for
conditions for badges (CA) and the Message Consumer would read the content regarding
the badges from the Collection entity (CM).
4. This interaction affects DA, LA and AA interactions as changes made to the Accolades
API entity by the Messages Consumer entity would affect how it reacts to the actions
made into the Database entity, by the Liberation entity and Message Consumer
entities. For eg. badges awarded automatically by the Messsage Consumer entity's
interaction would cause a change to be made on the Database entity (DA) and lead them
to be visible on the Liberation entity (LA) and accessible on the Accolades CLI
entity (AA).
CM
^^^^
~~
1. Defines the interaction between entities, Collection and Message Consumer.
2. In order for the Message Consumer to obtain badge assets (artworks, rules,
awarding conditions etc.), it has to interact with the Collection entity.
3. This interaction cannot be directly triggered and can only happen as a cause
of internal interactions like CA and external interactions like Repository
Members making changes to the Collection entity. For eg. internal changes
made to the Collection entity and external changes made to the Collection
entity (for eg. by the Repository Members) would change the way the Messages
Consumer entity would check for awarding conditions for the badges (CA).
4. The interaction does not directly affect any other internal interaction but
can indirectly affect interactions like MA. For eg. changes in the
Collection entity can change the frequency and cases when the Messages
Consumer would interact with the Accolades API (MA).
2. In order for the Message Consumer to obtain badge assets (artworks, rules, awarding
conditions etc.), it has to interact with the Collection entity.
3. This interaction cannot be directly triggered and can only happen as a cause of
internal interactions like CA and external interactions like Repository Members
making changes to the Collection entity. For eg. internal changes made to the
Collection entity and external changes made to the Collection entity (for eg. by the
Repository Members) would change the way the Messages Consumer entity would check for
awarding conditions for the badges (CA).
4. The interaction does not directly affect any other internal interaction but can
indirectly affect interactions like MA. For eg. changes in the Collection entity can
change the frequency and cases when the Messages Consumer would interact with the
Accolades API (MA).
External-Internal interactions
----
------------------------------
Interactions involving both external and internal entities are termed, in this
context, as external-internal interactions.
Interactions involving both external and internal entities are termed, in this context,
as external-internal interactions.
Accolades API interacting with external entities
^^^^
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. image:: ../_static/badges-proposed-api-ext-interactions.png
:target: ../_images/badges-proposed-api-ext-interactions.png
1. Service Admins [Access Level IV] would have a direct control on the
deployment environments (staging, development, production etc.).
1. Service Admins [Access Level IV] would have a direct control on the deployment
environments (staging, development, production etc.).
Accolades CLI interacting with external entities
^^^^
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. image:: ../_static/badges-proposed-cli-ext-interactions.png
:target: ../_images/badges-proposed-cli-ext-interactions.png
1. Service Admins [Access Level IV] would have a direct control on the
deployment environments (staging, development, production etc.).
2. Badge Owners [Access Level III] would have an elevated access to the
Accolades API entity using the Accolades CLI entity where they can
automate addition of new badges for distribution within the community,
create, access, modify and remove the badges that they "own" (not the ones
that they "have been awarded").
3. Community Users [Access Level I] would have a limited access to the
Accolades API entity using the Accolades CLI entity where they can view
the badges received by them (and by others), access the catalog of
available badges, view leaderboards and other such similar tasks.
1. Service Admins [Access Level IV] would have a direct control on the deployment
environments (staging, development, production etc.).
2. Badge Owners [Access Level III] would have an elevated access to the Accolades API
entity using the Accolades CLI entity where they can automate addition of new badges
for distribution within the community, create, access, modify and remove the badges
that they "own" (not the ones that they "have been awarded").
3. Community Users [Access Level I] would have a limited access to the Accolades API
entity using the Accolades CLI entity where they can view the badges received by them
(and by others), access the catalog of available badges, view leaderboards and other
such similar tasks.
Liberation interacting with external entities
^^^^
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. image:: ../_static/badges-proposed-web-ext-interactions.png
:target: ../_images/badges-proposed-web-ext-interactions.png
1. Service Admins [Access Level IV] would have a direct control on the
deployment environments (staging, development, production etc.).
2. Badge Owners [Access Level III] would have an elevated access to the
Accolades API entity using the Liberation entity where they can manually
add new badges for distribution within the community, create, access,
modify and remove the badges that they "own" (not the ones that they "have
been awarded").
3. Community Users [Access Level I] would have a limited access to the
Accolades API entity using the Liberation entity where they can view the
badges received by them (and by others), access the catalog of available
badges, view leaderboards and other such similar tasks.
1. Service Admins [Access Level IV] would have a direct control on the deployment
environments (staging, development, production etc.).
2. Badge Owners [Access Level III] would have an elevated access to the Accolades API
entity using the Liberation entity where they can manually add new badges for
distribution within the community, create, access, modify and remove the badges that
they "own" (not the ones that they "have been awarded").
3. Community Users [Access Level I] would have a limited access to the Accolades API
entity using the Liberation entity where they can view the badges received by them
(and by others), access the catalog of available badges, view leaderboards and other
such similar tasks.
Collection interacting with external entities
^^^^
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. image:: ../_static/badges-proposed-col-ext-interactions.png
:target: ../_images/badges-proposed-col-ext-interactions.png
1. Repository Members [Access Level II] would have complete access to the
Collection entity where they can access, create, modify and remove badge
assets (i.e. artworks, badge rules, awarding conditions etc.). As the
access is unrestricted, they have access to the assets created by someone
else too, which belong to the entity.
1. Repository Members [Access Level II] would have complete access to the Collection
entity where they can access, create, modify and remove badge assets (i.e. artworks,
badge rules, awarding conditions etc.). As the access is unrestricted, they have
access to the assets created by someone else too, which belong to the entity.
Database interacting with external entities
^^^^
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. image:: ../_static/badges-proposed-dtb-ext-interactions.png
:target: ../_images/badges-proposed-dtb-ext-interactions.png
1. Service Admins [Access Level IV] would have a direct control on the
deployment environments (staging, development, production etc.).
1. Service Admins [Access Level IV] would have a direct control on the deployment
environments (staging, development, production etc.).
Messages Consumer interacting with external entities
^^^^
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. image:: ../_static/badges-proposed-msg-ext-interactions.png
:target: ../_images/badges-proposed-msg-ext-interactions.png
1. Service Admins [Access Level IV] would have a direct control on the
deployment environments (staging, development, production etc.).
1. Service Admins [Access Level IV] would have a direct control on the deployment
environments (staging, development, production etc.).
External-only interactions
----
--------------------------
Interactions involving only external entities are termed, in this context, as
external-only interactions.
1. Badge Owners [Access Level III] might need to interact with Repository
Members [Access Level II] for assistance with changing badge assets in
the Collection entity.
2. Community User [Access Level I] might need to interact with the Badge
Owners [Access Level III] to obtain badges for the action that they have
done within the community.
1. Badge Owners [Access Level III] might need to interact with Repository Members
[Access Level II] for assistance with changing badge assets in the Collection entity.
2. Community User [Access Level I] might need to interact with the Badge Owners [Access
Level III] to obtain badges for the action that they have done within the community.

55
docs/badges/prop_rewrite_technologies.rst
View file

@ -1,52 +1,57 @@
.. _prop_rewrite_technologies:
Technologies suggested
====
======================
Database
----
--------
*Suggested using:*
| Database: Postgres
| Database: Postgres
Accolades API
----
-------------
*Suggested using:*
| Web framework: `FastAPI <https://fastapi.tiangolo.com/>`_ or `Flask <https://flask.palletsprojects.com/>`_
| CLI compositor: `Click <https://click.palletsprojects.com/>`_
| Database abstraction: `Psycopg2 <https://www.psycopg.org/docs/>`_
| ORM and SQL library: `SQLAlchemy <https://sqlalchemy.org/>`_
| Configuration parsing: `PyYAML <https://pyyaml.org/wiki/PyYAML>`_ or `Tomllib <https://docs.python.org/3/library/tomllib.html>`_
| Caching and indexing: `Redis <https://redis.io/>`_
| Web framework: `FastAPI <https://fastapi.tiangolo.com/>`_ or `Flask
<https://flask.palletsprojects.com/>`_
| CLI compositor: `Click <https://click.palletsprojects.com/>`_
| Database abstraction: `Psycopg2 <https://www.psycopg.org/docs/>`_
| ORM and SQL library: `SQLAlchemy <https://sqlalchemy.org/>`_
| Configuration parsing: `PyYAML <https://pyyaml.org/wiki/PyYAML>`_ or `Tomllib
<https://docs.python.org/3/library/tomllib.html>`_
| Caching and indexing: `Redis <https://redis.io/>`_
Accolades CLI
----
-------------
*Suggested using:*
| CLI compositor: `Click <https://click.palletsprojects.com/>`_
| HTTP library: `Requests <https://requests.readthedocs.io/>`_
| Configuration parsing: `PyYAML <https://pyyaml.org/wiki/PyYAML>`_ or `Tomllib <https://docs.python.org/3/library/tomllib.html>`_
| CLI compositor: `Click <https://click.palletsprojects.com/>`_
| HTTP library: `Requests <https://requests.readthedocs.io/>`_
| Configuration parsing: `PyYAML <https://pyyaml.org/wiki/PyYAML>`_ or `Tomllib
<https://docs.python.org/3/library/tomllib.html>`_
Liberation
----
----------
*Suggested using:*
| Frontend library: `VueJS <https://vuejs.org/>`_
| Frontend framework: `Vuetify <https://vuetifyjs.com/>`_
| Server: `Vue server <https://vuejs.org/>`_
| Frontend library: `VueJS <https://vuejs.org/>`_
| Frontend framework: `Vuetify <https://vuetifyjs.com/>`_
| Server: `Vue server <https://vuejs.org/>`_
Collection
----
----------
*Suggested using:*
| Version controlled forge: `GitLab <https://gitlab.com/>`_
| Version controlled forge: `GitLab <https://gitlab.com/>`_
Messages Consumer
-----
-----------------
*Suggested using:*
| Listener: `Fedora Messaging <https://fedora-messaging.readthedocs.io/en/stable/>`_
| CLI compositor: `Click <https://click.palletsprojects.com/>`_
| HTTP library: `Requests <https://requests.readthedocs.io/>`_
| Configuration parsing: `PyYAML <https://pyyaml.org/wiki/PyYAML>`_ or `Tomllib <https://docs.python.org/3/library/tomllib.html>`_
| Listener: `Fedora Messaging
<https://fedora-messaging.readthedocs.io/en/stable/>`_
| CLI compositor: `Click <https://click.palletsprojects.com/>`_
| HTTP library: `Requests <https://requests.readthedocs.io/>`_
| Configuration parsing: `PyYAML <https://pyyaml.org/wiki/PyYAML>`_ or `Tomllib
<https://docs.python.org/3/library/tomllib.html>`_

69
docs/badges/proposal_revitalize.rst
View file

@ -1,50 +1,45 @@
.. _proposal_revitalize:
Revitalize Fedora Badges
====
========================
| *At this point I don’t think we should put in more effort,*
| *it seems that a complete rewrite is needed.*
| -- **zlopez**
| *At this point I don’t think we should put in more effort,*
| *it seems that a complete rewrite is needed.*
| -- **zlopez**
Why we think revitalizing is not a good idea
------
--------------------------------------------
1. Conversion of tahrir codebase from python2 into python3 would be a huge effort.
Most of the code wasn’t touched in for over 3 years. The development
environment could be set up, but needs plenty of updates. There is almost
no documentation, so this needs to be created as well. The codebase is small,
around 2000 lines of code, but it’s heavily dependent on the pyramid framework,
which doesn’t have a great documentation and we no longer have people with
the knowledge of pyramid in the CPE Team. We also don’t have knowledge in the
team about the mako templates, but they are easy to comprehend.
The CI probably worked in the past (.cico.pipeline file is available),
1. Conversion of tahrir codebase from python2 into python3 would be a huge effort. Most
of the code wasn’t touched in for over 3 years. The development environment could be
set up, but needs plenty of updates. There is almost no documentation, so this needs
to be created as well. The codebase is small, around 2000 lines of code, but it’s
heavily dependent on the pyramid framework, which doesn’t have a great documentation
and we no longer have people with the knowledge of pyramid in the CPE Team. We also
don’t have knowledge in the team about the mako templates, but they are easy to
comprehend. The CI probably worked in the past (.cico.pipeline file is available),
but it’s no longer working, recommending to use either Zuul CI or GitHub Actions.
:What needs to be done:
- Port from python2 to python3
- Fix the dev environment
- Add CI
- Add dependency management (Optional)
- Add tests
- Convert from fedmsg to fedora messaging
- Add documentation
- Convert from Pyramid to Flask (Optional)
- Use poetry (Optional)
:What needs to be done: - Port from python2 to python3
- Fix the dev environment
- Add CI
- Add dependency management (Optional)
- Add tests
- Convert from fedmsg to fedora messaging
- Add documentation
- Convert from Pyramid to Flask (Optional)
- Use poetry (Optional)
2. tahrir_api code is tested against python 3.5, 3.6 and 3.7 and test coverage is 74%.
CI is using github actions. The repo needs some cleaning. There are still
Travis CI and .cico.pipeline config. The database is using SQLAlchemy and
alembic for migration.
Tahrir-api doesn’t have any dev environment where you can test it out.
It has only README as a documentation.
Has no dependency management, I’m recommending renovate.
API is using pyramid as a framework, which brings disadvantages mentioned
CI is using github actions. The repo needs some cleaning. There are still Travis CI
and .cico.pipeline config. The database is using SQLAlchemy and alembic for
migration. Tahrir-api doesn’t have any dev environment where you can test it out. It
has only README as a documentation. Has no dependency management, I’m recommending
renovate. API is using pyramid as a framework, which brings disadvantages mentioned
earlier.
:What needs to be done:
- Convert from Pyramid to Flask (Optional)
- Add some tools to test it out in dev environment
- Add dependency management (Optional)
- Improve documentation
- Use poetry (Optional)
:What needs to be done: - Convert from Pyramid to Flask (Optional)
- Add some tools to test it out in dev environment
- Add dependency management (Optional)
- Improve documentation
- Use poetry (Optional)

92
docs/badges/proposal_rewrite.rst
View file

@ -1,64 +1,64 @@
.. _proposal_rewrite:
Rewrite Fedora Badges From The Ground Up
====
========================================
| *Something which is state-of-the-art right now,*
| *will eventually and inevitably become a tech debt tomorrow.*
| -- **Pierre-Yves Chibbon**, Sometime in 2021
| *Something which is state-of-the-art right now,*
| *will eventually and inevitably become a tech debt tomorrow.*
| -- **Pierre-Yves Chibbon**, Sometime in 2021
We are proposing a rewrite for the project from the ground up.
Justification
----
1. The web interface and the API service for Fedora Badges is written in
Python 2 which has gone `EOL <https://www.python.org/doc/sunset-python-2/>`_
on January 1st, 2020. We could have proposed a 1:1 rewrite of the same
functionality in Python 3 but reimplementing the features in ways that are
more relevant now, makes more sense.
2. The `messages consumer <https://github.com/fedora-infra/fedbadges>`_
is bound to the `fedmsg <https://github.com/fedora-infra/fedmsg>`_ and needs
to be reimplemented to be compatible with
`Fedora Messaging <https://github.com/fedora-infra/fedora-messaging>`_.
As these two projects are inherently different from each other in their
function, not a lot of code can be salvaged from the previous implementation
of the messsages consumer, even though the strategy/approach can be.
3. The web interface and the API service for Fedora Badges is written using
the `Pyramid web framework <https://trypyramid.com/>`_ and makes use of
`Mako templating system <https://www.makotemplates.org/>`_ which are not as
`popular <https://gustavwillig.medium.com/python-web-development-in-2021-which-web-frameworks-are-the-most-popular-by-github-stars-e07b1d7ef6f7>`_
as their alternatives, `Flask <https://flask.palletsprojects.com/>`_ or
`FastAPI <https://fastapi.tiangolo.com/>`_ and
`Jinja <https://jinja.palletsprojects.com/>`_ respectively are.
* Maintaining the codebase in its current state can be a challenge in
the absence of comprehensive documentation, popular community support
and frequent question/answer activity on forums regarding the topics
related to the Pyramid web framework and Mako templating system.
* Finding interested community members (or getting people interested to
contribute to the project) can be difficult if a set of comparatively
obscure or unpopular technologies are used, which might deincentivize
participation here due to a relatively steep learning curve.
4. The frontend of the web interface is written in a form of a meta-application
(i.e. the frontend is supposed to behave like an application and yet is
implemented like a website) using (now, dated) templating systems, plain
HTML, CSS3 frameworks and Javascript libraries. These could use a rewrite
for improved application-like functionality and interactivity.
5. The current codebase has residual and/or partial implementation to
accommodate Open Badges (or Badgr) standards for storing artworks data,
awarding conditions, awardees etc. which have potentially never been
completed and/or deployed. Cleaning up the said codebase or completing it
before maintaining the project in its current state would require lots of
effort.
-------------
1. The web interface and the API service for Fedora Badges is written in Python 2 which
has gone `EOL <https://www.python.org/doc/sunset-python-2/>`_ on January 1st, 2020.
We could have proposed a 1:1 rewrite of the same functionality in Python 3 but
reimplementing the features in ways that are more relevant now, makes more sense.
2. The `messages consumer <https://github.com/fedora-infra/fedbadges>`_ is bound to the
`fedmsg <https://github.com/fedora-infra/fedmsg>`_ and needs to be reimplemented to
be compatible with `Fedora Messaging
<https://github.com/fedora-infra/fedora-messaging>`_. As these two projects are
inherently different from each other in their function, not a lot of code can be
salvaged from the previous implementation of the messsages consumer, even though the
strategy/approach can be.
3. The web interface and the API service for Fedora Badges is written using the `Pyramid
web framework <https://trypyramid.com/>`_ and makes use of `Mako templating system
<https://www.makotemplates.org/>`_ which are not as `popular
<https://gustavwillig.medium.com/python-web-development-in-2021-which-web-frameworks-are-the-most-popular-by-github-stars-e07b1d7ef6f7>`_
as their alternatives, `Flask <https://flask.palletsprojects.com/>`_ or `FastAPI
<https://fastapi.tiangolo.com/>`_ and `Jinja <https://jinja.palletsprojects.com/>`_
respectively are.
- Maintaining the codebase in its current state can be a challenge in the absence of
comprehensive documentation, popular community support and frequent question/answer
activity on forums regarding the topics related to the Pyramid web framework and
Mako templating system.
- Finding interested community members (or getting people interested to contribute to
the project) can be difficult if a set of comparatively obscure or unpopular
technologies are used, which might deincentivize participation here due to a
relatively steep learning curve.
4. The frontend of the web interface is written in a form of a meta-application (i.e.
the frontend is supposed to behave like an application and yet is implemented like a
website) using (now, dated) templating systems, plain HTML, CSS3 frameworks and
Javascript libraries. These could use a rewrite for improved application-like
functionality and interactivity.
5. The current codebase has residual and/or partial implementation to accommodate Open
Badges (or Badgr) standards for storing artworks data, awarding conditions, awardees
etc. which have potentially never been completed and/or deployed. Cleaning up the
said codebase or completing it before maintaining the project in its current state
would require lots of effort.
Implementation
----
--------------
Here is how we are planning to have the project redeveloped.
.. toctree::
:maxdepth: 1
prop_rewrite_entities
prop_rewrite_interactions
prop_rewrite_technologies