Add boilerplate for the Fedora Badges
Signed-off-by: Akashdeep Dhar <akashdeep.dhar@gmail.com>
This commit is contained in:
Akashdeep Dhar
t0xic0der
parent
40fea8c307
commit
062b64273c
8 changed files with 250 additions and 117 deletions
22
docs/badges/current_implementation.rst
Normal file
22
docs/badges/current_implementation.rst
Normal file
|
|
@ -0,0 +1,22 @@
|
|||
.. _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 -
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
|
||||
current_implementation_databases_and_api
|
||||
current_implementation_frontend
|
||||
current_implementation_messages_consumer
|
||||
|
||||
In addition to these main operational parts, there are also the following -
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
|
||||
current_implementation_artwork_and_rules
|
||||
current_implementation_badge_issuer_scripts
|
||||
14
docs/badges/current_implementation_artwork_and_rules.rst
Normal file
14
docs/badges/current_implementation_artwork_and_rules.rst
Normal file
|
|
@ -0,0 +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 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/>`_
|
||||
|
||||
19
docs/badges/current_implementation_badge_issuer_scripts.rst
Normal file
19
docs/badges/current_implementation_badge_issuer_scripts.rst
Normal file
|
|
@ -0,0 +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.
|
||||
|
||||
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
|
||||
|
||||
39
docs/badges/current_implementation_databases_and_api.rst
Normal file
39
docs/badges/current_implementation_databases_and_api.rst
Normal file
|
|
@ -0,0 +1,39 @@
|
|||
.. _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.
|
||||
|
||||
* Source repository: `https://github.com/fedora-infra/tahrir-api <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.
|
||||
|
||||
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.
|
||||
|
||||
+----------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|
||||
| 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". |
|
||||
+----------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|
||||
|
||||
|
||||
48
docs/badges/current_implementation_frontend.rst
Normal file
48
docs/badges/current_implementation_frontend.rst
Normal file
|
|
@ -0,0 +1,48 @@
|
|||
.. _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.
|
||||
|
||||
* 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>`_
|
||||
|
||||
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.
|
||||
|
||||
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)
|
||||
|
||||
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
|
||||
|
||||
40
docs/badges/current_implementation_messages_consumer.rst
Normal file
40
docs/badges/current_implementation_messages_consumer.rst
Normal file
|
|
@ -0,0 +1,40 @@
|
|||
.. _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.
|
||||
|
||||
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>`_.
|
||||
|
||||
* Source repository: `https://github.com/fedora-infra/fedbadges <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.
|
||||
|
||||
Technologies used
|
||||
----
|
||||
|
||||
The messages consumer is written in Python 2.
|
||||
|
||||
|
|
@ -1,117 +0,0 @@
|
|||
# Fedora Badges
|
||||
|
||||
Fedora Badges is a service that grants virtual "Badges" for milestones and completing tasks in the Fedora Community.
|
||||
For example, a user may collect badges for testing updates on Bodhi, and gets badges when they test 1, 5, 10, 20, 40, 80, 125, 250, 500, and 1000 updates.
|
||||
Users also gather badges for attending events, or other badges that are arbitrarily granted, such as the badge the Fedora Project Leader can grant whenever.
|
||||
|
||||
It appears that Fedora Badges was initially designed closely in step with [Open Badges which morphed into Badgr](https://en.wikipedia.org/wiki/Mozilla_Open_Badges). As far as we can tell, the idea was to be able to export Fedora badges into Mozilla Backpack / now Badgr Backpack, but this export facility was never implemented or deployed.
|
||||
|
||||
At some stage, there also appears to have been an [Open Source implementation of the Badgr server itself](https://github.com/concentricsky/badgr-server) (which may have been a solution to replace the fedora badges setup), but this is no longer on github, so cannot tell what it was/is. So now Badgr is just a service that allows users to collate their badges from different issuers into their "backpack"
|
||||
|
||||
|
||||
```{contents}
|
||||
```
|
||||
|
||||
## Current issues and limitations
|
||||
* Python 2
|
||||
* Pyramid
|
||||
* uses openid not oidc for authentication
|
||||
* Fedmsg consumer rather than Fedora Messaging.
|
||||
* Sends fedmsgs rather than Fedora Messages
|
||||
|
||||
## Current Implementation
|
||||
|
||||
The Fedora Badges service is currently split up into multiple parts that all work together to provide badges to Fedora contributors. These parts are:
|
||||
* The **Database and API**
|
||||
* The **Tahrir Frontend**
|
||||
* the **fedbadges fedmsg consumer** which consumes the messages from the queue and issues badges based on criteria
|
||||
|
||||
In addition to these main operational parts there is also the following:
|
||||
* **badge issuer scripts** run by cronjobs (these are stored in ansible)
|
||||
* the **fedora-badges repo**, which stores the badge artwork and fedbadges fedmsg Badge Rules
|
||||
|
||||
### The Database and API
|
||||
The database for Fedora Badges stores the Badge Definitions, and what users have been granted badges. There is also a python API for interacting with the database.
|
||||
|
||||
* **Source Repo**: [https://github.com/fedora-infra/tahrir-api](https://github.com/fedora-infra/tahrir-api)
|
||||
* **Production Location**: db01.iad2.fedoraproject.org/tahrir
|
||||
|
||||
#### Technology used
|
||||
The tahrir database and API is written in **Python 2** and uses **sqlalchemy** for database management. In production, a **postgres** database is used.
|
||||
|
||||
#### Basic Database Table information
|
||||
|
||||
The badges database appears to have been implemented with extra features for Open Badges / Badgr compatablity, but a lot of these tables are not really in use in the production Fedora Badges.
|
||||
|
||||
| DB Table | |
|
||||
| --- | --- |
|
||||
| **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 <br/>is not stored in the DB, it is just a link to an image on the backend server. <br/>Also, the criteria for a badge is only a URL to a criteria. |
|
||||
| **Assertion** | A table that maps users to badges allowing them to arbitrarily <br/>grant them. |
|
||||
| **Authorization** | A table that maps users to badges allowing them to arbitrarily <br/>grant them. |
|
||||
| **Issuer** | A table of the issuers that issue badges. In Fedora badges, <br/>there is only one issuer -- Fedora, so not really used. |
|
||||
| **Series** | A table to do with having series of badges -- can't find much <br/>documentation about it, but on production badges it is empty, so not in use. |
|
||||
| **Milestones** | Another table to do with having series of badges -- can't find much <br/>documentation about it, but on production badges it is empty, so not in use. |
|
||||
| **Team** | Yet another table to do with having series of badges -- can't <br/>find much documentation about it, but on production badges it <br/>only has one entry "Infrastructure". |
|
||||
|
||||
|
||||
### Tahrir Frontend
|
||||
Tahrir is the name given to the web frontend that allows users to view their badges, and view other peoples badges, and get be granted special badges.
|
||||
Additionally, Badge admins also use the tahrir interface to add new badges into the database.
|
||||
|
||||
* **Source Repo**: [https://github.com/fedora-infra/tahrir](https://github.com/fedora-infra/tahrir)
|
||||
* **Production URL**: [https://badges.fedoraproject.org/](https://badges.fedoraproject.org/)
|
||||
* **Production Location**: `badges-web01.iad2.fedoraproject.org`
|
||||
|
||||
```{note} The [badge images themselves are stored](https://pagure.io/fedora-badges/blob/master/f/pngs) in the [fedora-badges repo](https://pagure.io/Fedora-Badges), and, when new rules are added, copied over to the 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 tahrir frontend **Python 2** and uses **pyramid** as a web framework, and **mako** templates.
|
||||
|
||||
#### Usecases
|
||||
##### 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)
|
||||
##### 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
|
||||
|
||||
### fedbadges fedmsg consumer
|
||||
The fedbadges fedmsg consumer is the main piece of Fedora Badges that grants badges to 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. (the assumption here was that was done for performance reasons.)
|
||||
|
||||
The Badge Rules are defined in yaml files are defined in a custom specification that is documented in the [README in the fedbadges source](https://github.com/fedora-infra/fedbadges/blob/develop/README.rst). For Fedora badges, the [badge 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 [push-badges manual playbook](https://pagure.io/fedora-infra/ansible/blob/main/f/playbooks/manual/push-badges.yml).
|
||||
|
||||
* **Source Repo**: [https://github.com/fedora-infra/fedbadges](https://github.com/fedora-infra/fedbadges)
|
||||
* **Production Location**: badges-backend01.iad2.fedoraproject.org
|
||||
|
||||
```{note} The fedbadges fedmsg 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.
|
||||
```
|
||||
|
||||
#### Technology used
|
||||
The fedbadges fedmsg consumer is written in **Python 2**.
|
||||
|
||||
### Badge issuer scripts
|
||||
In addition to manually granting a badge in the web UI, and the fedmsg 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 fedmsg.
|
||||
|
||||
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 with a script.
|
||||
|
||||
* **Source Repo**: https://pagure.io/fedora-infra/ansible/blob/main/f/roles/badges/backend/files/cron
|
||||
* **Production Location**: badges-backend01.iad2.fedoraproject.org
|
||||
|
||||
|
||||
### fedora-badges repo
|
||||
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 Repo**: [https://pagure.io/fedora-badges/](https://pagure.io/fedora-badges/)
|
||||
68
docs/badges/index.rst
Normal file
68
docs/badges/index.rst
Normal file
|
|
@ -0,0 +1,68 @@
|
|||
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.
|
||||
|
||||
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.
|
||||
|
||||
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/>`_
|
||||
|
||||
Index
|
||||
----
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
|
||||
current_implementation
|
||||
exploring_the_development_environment
|
||||
expectations_and_wishes
|
||||
|
||||
Conclusions
|
||||
----
|
||||
|
||||
The best approach would be to pick the best approach and carry through it.
|
||||
|
||||
Proposed roadmap
|
||||
----
|
||||
|
||||
* Step 1 - Make Fedora Badges great again!
|
||||
* Step 2 - Ensure that Fedora Badges is indeed great
|
||||
* Step 3 - Profit
|
||||
|
||||
Estimate of work
|
||||
----
|
||||
|
||||
It will take as much time as needed.
|
||||
|
||||
Loading…
Add table
Add a link
Reference in a new issue