diff --git a/docs/github2fedmsg/rewrite.rst b/docs/github2fedmsg/rewrite.rst index dbdd193..f7f85af 100644 --- a/docs/github2fedmsg/rewrite.rst +++ b/docs/github2fedmsg/rewrite.rst @@ -1,21 +1,111 @@ .. _rewrite: -Complete rewrite of github2fedmsg application -============================================= +Complete Rewrite of github2fedmsg Application +==== This document will investigate the possibility of rewriting github2fedmsg from scratch. -Notes ------ +Elements that could use our attention +---- +**Project configuration** + | *Currently uses*: Setuptools (`setup.py `_) + | *Suggested using*: Poetry (`pyproject.toml `_) + | *Reason(s)*: Easier dependency management, project configuration, testing information etc. -The Good Points ---------------- +**Backend language** + | *Currently uses*: Python 2.7.x (now `EOLed `_) + | *Suggested using*: Python 3.10.x (and above) + | *Reason(s)*: Benefit from performance improvements, bug fixes, security patches etc. on the language -1. Good point +**Base framework** + | *Currently uses*: `Pyramid `_ + | *Suggested using*: `Flask `_ or `FastAPI `_ + | *Reason(s)*: More knowledge about the suggested ones in the team, streamlined development, more features etc. +**Templating implementation** + | *Currently uses*: `Mako `_ + | *Suggested using*: `Jinja `_ + | *Reason(s)*: More knowledge about the suggested ones in the team, standardized templating etc. -The Bad points --------------- +**Authentication library** + | *Currently uses*: `Velruse `_ + | *Suggested using*: `Authlib `_ + | *Reason(s)*: Authlib is actively maintained while Velruse had its last update `9 years ago `_. -1. Bad point +**Frontend CSS library** + | *Currently uses*: `Bootstrap 3.1.1 (Fedora) `_ + | *Suggested using*: Updated version of Bootstrap for eg. `Boostrap 5 `_ + | *Reason(s)*: Web interface looks/feels dated and is not responsive to variable widths. + +**Notification popups** + | *Currently uses*: `Messenger 1.4.1 `_ + | *Suggested using*: Updated version of Messenger or any maintained alternative + | *Reason(s)*: Library was last added `8 years back `_ and could use an update. + +**Interface interactivity** + | *Currently uses*: `JQuery 1.11.0 `_ + | *Suggested using*: Updated version of JQuery for eg. `JQuery 3.6.1 `_ + | *Reason(s)*: Library was last added `9 years back `_ and could use an update. + +**API modelling** + | *Currently uses*: In-place `creation of data structures `_ in worker functions + | *Suggested using*: Data validation and typing libraries like `Pydantic `_ + | *Reason(s)*: Better codebase modularity and readability, auto-validation of API data types etc. + +**Command line parsing** + | *Currently uses*: None. Just making do with `stdio` and `stdout`. + | *Suggested using*: `Click `_ or any other alternatives + | *Reason(s)*: Easy-to-use command line creation, handling of options and commands with auto-generated help etc. + +The good and the bad +---- + +**Advantages** + 1. In its current state, the project is written in (now EOLed) Python 2.7.x + and as Python 3 is currently in active development, the project can + benefit from the performance improvements, bug fixes and security patches + included in the language itself. + 2. The project makes use of a certain set of dependencies, the support of + which, have not been ported from Python 2 to Python 3. Porting into + Python 3 would necessitate the use of newer dependencies which would be + more updated, secure and maintained. + 3. In its current state, the project makes use of the + `Pyramid `_ web framework, the expertise of which + the team currently lacks, making it unmaintainable right now. A rewrite + using libraries and frameworks that the team is acquainted with would help. + 4. The web interface makes use of non-default + `Mako `_-based + `templates `_ + that work right now but due to their obscure nature, it can become + difficult to debug the templates later. A rewrite of templates using + a standardized + `Jinja `_ format would go a + long way. + 5. The web interface could use updated versions (or replacements) of + unmaintained JavaScript and CSS3 dependencies (for now, it has + `Bootstrap 3.1.1 `_, + `Messenger 1.4.1 `_, + `JQuery 1.11.0 `_ + etc.) in order to introduce responsiveness and provide a better look and + feel. + 6. The API model can be standardized with the use of typing and data + validation libraries such as + `Pydantic `_ instead of + `forming data structures `_ + in the worker function itself, making the code more modular and + maintainable in the long run. + +**Disadvantages** + 1. The move from Python 2 to Python 3 would require special attention into + the finding alternatives for the dependencies which either support only + Python 2 or are unmaintained as of 2022. Inability to find those would + render the rewrite unsuccessful. + 2. In the wake of new ways to interact with an API, some features (eg. web + interface, when API is suggested to be used by itself) of the current + version have become redundant and a 1:1 rewrite would not help as it + would frontport those features too. + 3. While reworking the database model, it is possible that the existing dump + cannot be fully imported due to the changes introduced in the database + schema to better work the newer reimplementation, thereby potentially + causing data loss.