diff --git a/docs/_static/badges-proposed-api-ext-interactions.png b/docs/_static/badges-proposed-api-ext-interactions.png new file mode 100644 index 0000000..098403a Binary files /dev/null and b/docs/_static/badges-proposed-api-ext-interactions.png differ diff --git a/docs/_static/badges-proposed-architecture.png b/docs/_static/badges-proposed-architecture.png new file mode 100644 index 0000000..beaf1c5 Binary files /dev/null and b/docs/_static/badges-proposed-architecture.png differ diff --git a/docs/_static/badges-proposed-cli-ext-interactions.png b/docs/_static/badges-proposed-cli-ext-interactions.png new file mode 100644 index 0000000..2e32223 Binary files /dev/null and b/docs/_static/badges-proposed-cli-ext-interactions.png differ diff --git a/docs/_static/badges-proposed-col-ext-interactions.png b/docs/_static/badges-proposed-col-ext-interactions.png new file mode 100644 index 0000000..facb7b2 Binary files /dev/null and b/docs/_static/badges-proposed-col-ext-interactions.png differ diff --git a/docs/_static/badges-proposed-dtb-ext-interactions.png b/docs/_static/badges-proposed-dtb-ext-interactions.png new file mode 100644 index 0000000..4f7eb8e Binary files /dev/null and b/docs/_static/badges-proposed-dtb-ext-interactions.png differ diff --git a/docs/_static/badges-proposed-msg-ext-interactions.png b/docs/_static/badges-proposed-msg-ext-interactions.png new file mode 100644 index 0000000..b65c19e Binary files /dev/null and b/docs/_static/badges-proposed-msg-ext-interactions.png differ diff --git a/docs/_static/badges-proposed-web-ext-interactions.png b/docs/_static/badges-proposed-web-ext-interactions.png new file mode 100644 index 0000000..ec27b71 Binary files /dev/null and b/docs/_static/badges-proposed-web-ext-interactions.png differ diff --git a/docs/badges/index.rst b/docs/badges/index.rst index aaf1b55..a39bad9 100644 --- a/docs/badges/index.rst +++ b/docs/badges/index.rst @@ -49,6 +49,7 @@ Index current_implementation exploring_the_development_environment expectations_and_wishes + proposal_rewrite Conclusions ---- diff --git a/docs/badges/prop_rewrite_entities.rst b/docs/badges/prop_rewrite_entities.rst new file mode 100644 index 0000000..d8ac0cf --- /dev/null +++ b/docs/badges/prop_rewrite_entities.rst @@ -0,0 +1,144 @@ +.. _prop_rewrite_entities: + +Proposed Entities +==== + +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 `_'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 `_ 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 `_'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 `_ + 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 and 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). + +**Messages consumer** - Conditions listener + 1. Succeeds the existing + `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 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 `_ + 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. + +**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. + +**Community Users** - Access Level I + 1. Consists of generally everyone from the Fedora Project community who have + a valid and activated, `IPA account `_ + and have signed the + `Fedora Project Contributor Agreement `_. + 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. diff --git a/docs/badges/prop_rewrite_interactions.rst b/docs/badges/prop_rewrite_interactions.rst new file mode 100644 index 0000000..fe65cee --- /dev/null +++ b/docs/badges/prop_rewrite_interactions.rst @@ -0,0 +1,124 @@ +.. _prop_rewrite_interactions: + +Proposed Interactions +==== + +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. + +.. 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). + +**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). + +**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. + +**** + + +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 + + +**Accolades CLI** interacting with external entities + +.. image:: ../_static/badges-proposed-cli-ext-interactions.png + :target: ../_images/badges-proposed-cli-ext-interactions.png + + +**Liberation** interacting with external entities + +.. image:: ../_static/badges-proposed-web-ext-interactions.png + :target: ../_images/badges-proposed-web-ext-interactions.png + + +**Collection** interacting with external entities + +.. image:: ../_static/badges-proposed-col-ext-interactions.png + :target: ../_images/badges-proposed-col-ext-interactions.png + + +**Database** interacting with external entities + +.. image:: ../_static/badges-proposed-dtb-ext-interactions.png + :target: ../_images/badges-proposed-dtb-ext-interactions.png + + +**Messages consumer** interacting with external entities + +.. image:: ../_static/badges-proposed-msg-ext-interactions.png + :target: ../_images/badges-proposed-msg-ext-interactions.png + + +External-only interactions +---- diff --git a/docs/badges/prop_rewrite_technologies.rst b/docs/badges/prop_rewrite_technologies.rst new file mode 100644 index 0000000..e69de29 diff --git a/docs/badges/proposal_rewrite.rst b/docs/badges/proposal_rewrite.rst new file mode 100644 index 0000000..c8fa312 --- /dev/null +++ b/docs/badges/proposal_rewrite.rst @@ -0,0 +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 + +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 `_ + 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 `_ + is bound to the `fedmsg `_ and needs + to be reimplemented to be compatible with + `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 `_ and makes use of + `Mako templating system `_ which are not as + `popular `_ + as their alternatives, `Flask `_ or + `FastAPI `_ and + `Jinja `_ 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 +