add draft content for badges
add content on how badges works Signed-off-by: Ryan Lerch <rlerch@redhat.com>
This commit is contained in:
parent
bc92960b40
commit
87c29b9103
3 changed files with 121 additions and 4 deletions
117
docs/badges/index.md
Normal file
117
docs/badges/index.md
Normal file
|
|
@ -0,0 +1,117 @@
|
|||
# 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/)
|
||||
|
|
@ -27,8 +27,7 @@ author = 'Fedora-Infra'
|
|||
# Add any Sphinx extension module names here, as strings. They can be
|
||||
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
|
||||
# ones.
|
||||
extensions = [
|
||||
]
|
||||
extensions = ["myst_parser"]
|
||||
|
||||
# Add any paths that contain templates here, relative to this directory.
|
||||
templates_path = ['_templates']
|
||||
|
|
@ -44,7 +43,7 @@ exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
|
|||
# The theme to use for HTML and HTML Help pages. See the documentation for
|
||||
# a list of builtin themes.
|
||||
#
|
||||
html_theme = 'alabaster'
|
||||
html_theme = 'sphinx_rtd_theme'
|
||||
|
||||
# Add any paths that contain custom static files (such as style sheets) here,
|
||||
# relative to this directory. They are copied after the builtin static files,
|
||||
|
|
|
|||
|
|
@ -10,6 +10,7 @@ Drafts
|
|||
:maxdepth: 1
|
||||
|
||||
fmn/index
|
||||
badges/index
|
||||
|
||||
Completed review
|
||||
----------------
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue