mirror of
https://github.com/ae-utbm/sith.git
synced 2025-07-11 20:39:23 +00:00
Cleaned doc folder as it was unused
This commit is contained in:
Théo DURR
@ -1,29 +0,0 @@
|
||||
Introduction
|
||||
============
|
||||
|
||||
Le but de ce projet est de fournir à l'Association des Étudiants de l'UTBM une plate-forme pratique et centralisée de ses services. Le Sith de l'AE tient à jour le registre des cotisations à l'association, prend en charge la trésorerie, les ventes de produits et services, la diffusion d’événements, la gestion de la laverie et bien plus encore. Il est conçu de manière suffisamment générique pour être facilement adaptable à une autre association.
|
||||
|
||||
C'est un projet bénévole qui tire ses origines des années 2000. Il s'agit de la troisième version du site de l'association initiée en 2015. C'est une réécriture complète en rupture totale des deux versions qui l'ont précédée.
|
||||
|
||||
Pourquoi réécrire le site
|
||||
-------------------------
|
||||
|
||||
L'ancienne version du site, sobrement baptisée `ae2 <https://github.com/ae-utbm/sith2>`_ présentait un nombre impressionnant de fonctionnalités. Il avait été écrit en PHP et se basait sur son propre framework maison.
|
||||
|
||||
Malheureusement, son entretiens était plus ou moins hasardeux et son framework reposait sur des principes assez différents de ce qui se fait aujourd'hui, rendant la maintenance difficile. De plus, la version de PHP qu'il utilisait était plus que déprécié et à l'heure de l'arrivée de PHP 7 et de sa non rétrocompatibilité il était vital de faire quelque chose. Il a donc été décidé de le réécrire.
|
||||
|
||||
La philosophie du projet
|
||||
------------------------
|
||||
|
||||
Pour éviter les erreurs du passé, ce projet met l'accent sur la maintenabilité. Le choix des technologies ne s'est donc pas fait uniquement sur le fait qu'elle soit récentes, mais également sur leur robustesse, leur fiabilité et leur potentiel à être maintenu loin dans le futur.
|
||||
|
||||
La maintenabilité passe également par le choix minutieux des dépendances qui doivent eux aussi passer l'épreuve du temps pour éviter qu'elles ne mettent le projet en danger.
|
||||
|
||||
Cela passe également par la minimisation des frameworks employés de manière à réduire un maximum les connaissances nécessaires pour contribuer au projet et donc simplifier la prise en main. La simplicité est à privilégier si elle est possible.
|
||||
|
||||
Le projet doit être simple à installer et à déployer.
|
||||
|
||||
Le projet étant à destination d'étudiants, il est préférable de minimiser les ressources utilisées par l'utilisateur final. Il faut qu'il soit au maximum économe en bande passante et calcul côté client.
|
||||
|
||||
|
||||
Le projet est un logiciel libre et est sous licence GPL. Aucune dépendance propriétaire ne sera acceptée.
|
||||
@ -1,178 +0,0 @@
|
||||
Technologies utilisées
|
||||
======================
|
||||
|
||||
Bien choisir ses technologies est crucial puisqu'une fois que le projet est suffisamment avancé, il est très difficile voir impossible de revenir en arrière.
|
||||
|
||||
En novembre 2015, plusieurs choix s'offraient à nous :
|
||||
|
||||
* Continuer avec du PHP
|
||||
* S'orienter vers un langage web plus moderne et à la mode comme le Python ou le Ruby
|
||||
* Baser le site sur un framework Javascript
|
||||
|
||||
Le PHP 5, bientôt 7, de l'époque étant assez discutable comme `cet article <https://eev.ee/blog/2012/04/09/php-a-fractal-of-bad-design/>`__ et l'ancien site ayant laissé un goût amer à certains développeurs, celui-ci a été mis de côté.
|
||||
|
||||
L'écosystème Javascript étant à peine naissant et les frameworks allant et venant en seulement quelques mois, il était impossible de prédire avec certitude si ceux-ci passeraient l'épreuve du temps, il était inconcevable de tout parier là dessus.
|
||||
|
||||
Ne restait plus que le Python et le Ruby avec les frameworks Django et Ruby On Rails. Ruby ayant une réputation d'être très "cutting edge", c'est Python, un langage bien implanté et ayant fait ses preuves, qui a été retenu.
|
||||
|
||||
Backend
|
||||
-------
|
||||
|
||||
Python 3
|
||||
~~~~~~~~
|
||||
|
||||
`Site officiel <https://www.python.org/>`__
|
||||
|
||||
Le python est un langage de programmation interprété multi paradigme sorti en 1991. Il est très populaire pour sa simplicité d'utilisation, sa puissance, sa stabilité, sécurité ainsi que sa grande communauté de développeur. Sa version 3, non rétro compatible avec sa version 2, a été publiée en 2008.
|
||||
|
||||
.. note::
|
||||
|
||||
Puisque toutes les dépendances du backend sont des packages Python, elles sont toutes ajoutées directement dans le fichier **requirements.txt** à la racine du projet.
|
||||
|
||||
Django
|
||||
~~~~~~
|
||||
|
||||
| `Site officiel <https://www.djangoproject.com/>`__
|
||||
| `Documentation <https://docs.djangoproject.com/en/1.11/>`__
|
||||
|
||||
Django est un framework web pour Python apparu en 2005. Il fourni un grand nombre de fonctionnalités pour développer un site rapidement et simplement. Cela inclu entre autre un serveur Web de développement, un parseur d'URLs pour le routage des différentes URI du site, un ORM (Object-Relational Mapper) pour la gestion de la base de donnée ainsi qu'un moteur de templates pour le rendu HTML. Django propose une version LTS (Long Term Support) qui reste stable et est maintenu sur des cycles plus longs, ce sont ces versions qui sont utilisées.
|
||||
|
||||
PostgreSQL / SQLite
|
||||
~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
| `Site officiel PostgreSQL <https://www.postgresql.org/>`__
|
||||
| `Site officiel SQLite <https://www.sqlite.org/index.html>`__
|
||||
|
||||
Comme la majorité des sites internet, le Sith de l'AE enregistre ses données dans une base de donnée. Nous utilisons une base de donnée relationnelle puisque c'est la manière typique d'utiliser Django et c'est ce qu'utilise son ORM. Dans la pratique il arrive rarement dans le projet de se soucier de ce qui fonctionne derrière puisque le framework abstrait les requêtes au travers de son ORM. Cependant, il arrive parfois que certaines requêtes, lorsqu'on cherche à les optimiser, ne fonctionnent que sur un seul backend.
|
||||
|
||||
Le principal à retenir ici est :
|
||||
|
||||
* Sur la version de production nous utilisons PostgreSQL, c'est cette version qui doit fonctionner en priorité
|
||||
* Sur les versions de développement, pour faciliter l'installation du projet, nous utilisons la technologie SQLite qui ne requiert aucune installation spécifique. Certaines instructions ne sont pas supportées par cette technologie et il est parfois nécessaire d'installer PostgreSQL pour le développement de certaines parties du site.
|
||||
|
||||
Frontend
|
||||
--------
|
||||
|
||||
Jinja2
|
||||
~~~~~~
|
||||
|
||||
`Site officiel <https://jinja.palletsprojects.com/en/2.10.x/>`__
|
||||
|
||||
Jinja2 est un moteur de template écrit en Python qui s'inspire fortement de la syntaxe des templates de Django. Ce moteur apporte toutefois son lot d'améliorations non négligeables. Il permet par exemple l'ajout de macros, sortes de fonctions écrivant du HTML.
|
||||
|
||||
Un moteur de templates permet de générer du contenu textuel de manière procédural en fonction des données à afficher, cela permet de pouvoir inclure du code proche du Python dans la syntaxe au milieu d'un document contenant principalement du HTML. On peut facilement faire des boucles ou des conditions ainsi même que de l'héritage de templates.
|
||||
|
||||
Attention : le rendu est fait côté serveur, si on souhaite faire des modifications côté client, il faut utiliser du Javascript, rien ne change à ce niveau là.
|
||||
|
||||
Exemple d'utilisation d'un template Jinja2
|
||||
|
||||
.. sourcecode:: html+jinja
|
||||
|
||||
<title>{% block title %}{% endblock %}</title>
|
||||
<ul>
|
||||
{% for user in users %}
|
||||
<li><a href="{{ user.url }}">{{ user.username }}</a></li>
|
||||
{% endfor %}
|
||||
</ul>
|
||||
|
||||
jQuery
|
||||
~~~~~~
|
||||
|
||||
`Site officiel <https://jquery.com/>`__
|
||||
|
||||
jQuery est une bibliothèque JavaScript libre et multiplateforme créée pour faciliter l'écriture de scripts côté client dans le code HTML des pages web. La première version est lancée en janvier 2006 par John Resig.
|
||||
|
||||
C'est une vieille technologie et certains feront remarquer à juste titre que le Javascript moderne permet d'utiliser assez simplement la majorité de ce que fourni jQuery sans rien avoir à installer. Cependant, de nombreuses dépendances du projet utilisent encore jQuery qui est toujours très implanté aujourd'hui. Le sucre syntaxique qu'offre cette libraire reste très agréable à utiliser et économise parfois beaucoup de temps. Ça fonctionne et ça fonctionne très bien. C'est maintenu, léger et pratique, il n'y a pas de raison particulière de s'en séparer.
|
||||
|
||||
Sass
|
||||
~~~~
|
||||
|
||||
`Site officiel <https://sass-lang.com/>`__
|
||||
|
||||
Sass (Syntactically Awesome Stylesheets) est un langage dynamique de génération de feuilles CSS apparu en 2006. C'est un langage de CSS "amélioré" qui permet l'ajout de variables (à une époque où le CSS ne les supportait pas), de fonctions, mixins ainsi qu'une syntaxe pour imbriquer plus facilement et proprement les règles sur certains éléments. Le Sass est traduit en CSS directement côté serveur et le client ne reçoit que du CSS.
|
||||
|
||||
C'est une technologie stable, mature et pratique qui ne nécessite pas énormément d'apprentissage.
|
||||
|
||||
Fontawesome
|
||||
~~~~~~~~~~~
|
||||
|
||||
`Site officiel <https://fontawesome.com>`__
|
||||
|
||||
Fontawesome regroupe tout un ensemble d'icônes libres de droits utilisables facilement sur n'importe quelle page web. Ils sont simple à modifier puisque modifiables via le CSS et présentent l'avantage de fonctionner sur tous les navigateurs contrairement à un simple icône unicode qui s'affiche lui différemment selon la plate-forme.
|
||||
|
||||
.. note::
|
||||
|
||||
C'est une dépendance capricieuse qu'il évolue très vite et qu'il faut très souvent mettre à jour.
|
||||
|
||||
.. warning::
|
||||
|
||||
Il a été décidé de **ne pas utiliser** de CDN puisque le site ralentissait régulièrement. Il est préférable de fournir cette dépendance avec le site.
|
||||
|
||||
Documentation
|
||||
-------------
|
||||
|
||||
Sphinx
|
||||
~~~~~~
|
||||
|
||||
`Site officiel <https://www.sphinx-doc.org/en/master/>`__
|
||||
|
||||
Sphinx est un outil qui permet la création de documentations intelligentes et très jolies. C'est cet outil qui permet d'écrire le documentation que vous êtes en train de lire actuellement. Développé en 2008 pour la communauté Python, c'est l'outil le plus répandu. Il est utilisé pour la documentation officielle de Python, pour celle de Django, Jinja2 et bien d'autres.
|
||||
|
||||
ReadTheDocs
|
||||
~~~~~~~~~~~
|
||||
|
||||
`Site officiel <https://www.sphinx-doc.org/en/master/>`__
|
||||
|
||||
C'est un site d'hébergement de documentations utilisant Sphinx. Il propose la génération de documentation à partir de sources et leur hébergement gracieusement pour tout projet open source. C'est le site le plus utilisé et sur lequel sont hébergées bon nombre de documentations comme par exemple celle de Django. La documentation sur ce site est automatiquement générée à chaque nouvelle modification du projet.
|
||||
|
||||
reStructuredText
|
||||
~~~~~~~~~~~~~~~~
|
||||
|
||||
`Site officiel <http://docutils.sourceforge.net/rst.html>`__
|
||||
|
||||
C'est un langage de balisage léger utilisé notamment dans la documentation du langage Python. C'est le langage dans lequel est écrit l'entièreté de la documentation ci-présente pour que Sphinx puisse la lire et la mettre en forme.
|
||||
|
||||
Workflow
|
||||
--------
|
||||
|
||||
Git
|
||||
~~~
|
||||
|
||||
`Site officiel <https://git-scm.com/>`__
|
||||
|
||||
Git est un logiciel de gestion de versions écrit par Linus Torsvald pour les besoins du noyau linux en 2005. C'est ce logiciel qui remplace svn anciennement utilisé pour gérer les sources du projet (rappelez vous, l'ancien site date d'avant 2005). Git est plus complexe à utiliser mais est bien plus puissant, permet de gérer plusieurs version en parallèle et génère des codebases vraiment plus légères puisque seules les modifications sont enregistrées (contrairement à svn qui garde une copie de la codebase par version).
|
||||
|
||||
GitLab
|
||||
~~~~~~
|
||||
|
||||
| `Site officiel <https://about.gitlab.com/>`__
|
||||
| `Instance de l'AE <https://github.com/ae-utbm/>`__
|
||||
|
||||
GitLab est une alternative libre à GitHub. C'est une plate-forme avec interface web permettant de déposer du code géré avec Git offrant également de l'intégration continue et du déploiement automatique.
|
||||
|
||||
C'est au travers de cette plate-forme que le Sith de l'AE est géré, sur une instance hébergée directement sur nos serveurs.
|
||||
|
||||
Sentry
|
||||
~~~~~~
|
||||
|
||||
| `Site officiel <https://sentry.io>`__
|
||||
| `Instance de l'AE <https://ae2.utbm.fr>`__
|
||||
|
||||
Sentry est une plate-forme libre qui permet de se tenir informer des bugs qui ont lieu sur le site. À chaque crash du logiciel (erreur 500), une erreur est envoyée sur la plate-forme et est indiqué précisément à quelle ligne de code celle-ci a eu lieu, à quelle heure, combien de fois, avec quel navigateur la page a été visitée et même éventuellement un commentaire de l'utilisateur qui a rencontré le bug.
|
||||
|
||||
Poetry
|
||||
~~~~~~~~~~
|
||||
|
||||
`Utiliser Poetry <https://python-poetry.org/docs/basic-usage/>`__
|
||||
|
||||
Poetry est un utilitaire qui permet de créer et gérer des environements Python de manière simple et intuitive. Il permet également de gérer et mettre à jour le fichier de dépendances.
|
||||
L'avantage d'utiliser poetry (et les environnements virtuels en général) est de pouvoir gérer plusieurs projets différents en parallèles puisqu'il permet d'avoir sur sa machine plusieurs environnements différents et donc plusieurs versions d'une même dépendance dans plusieurs projets différent sans impacter le système sur lequel le tout est installé.
|
||||
|
||||
Black
|
||||
~~~~~
|
||||
|
||||
`Site officiel <https://black.readthedocs.io/en/stable/>`__
|
||||
|
||||
Pour faciliter la lecture du code, il est toujours appréciable d'avoir une norme d'écriture cohérente. C'est généralement à l'étape de relecture des modifications par les autres contributeurs que sont repérées ces fautes de normes qui se doivent d'être corrigées pour le bien commun.
|
||||
|
||||
Imposer une norme est très fastidieux, que ce soit pour ceux qui relisent ou pour ceux qui écrivent. C'est pour cela que nous utilisons black qui est un formateur automatique de code. Une fois l'outil lancé, il parcours la codebase pour y repérer les fautes de norme et les corrige automatiquement sans que l'utilisateur ai à s'en soucier. Bien installé, il peut effectuer ce travail à chaque sauvegarde d'un fichier dans son éditeur, ce qui est très agréable pour travailler.
|
||||
@ -1,36 +0,0 @@
|
||||
Le versioning
|
||||
=============
|
||||
|
||||
Dans le monde du développement, nous faisons face à un problème relativement étrange pour un domaine aussi avancé : on est brouillon.
|
||||
|
||||
On teste, on envoie, ça marche pas, on reteste, c'est ok. Par contre, on a oublie plein d'exceptions. Et on refactor. Ça marche mieux mais c'est moins rapide, etc, etc.
|
||||
|
||||
Et derrière tout ça, on fait des trucs qui marchent puis on se retrouve dans la mouise parce qu'on a effacé un morceau de code qui nous aurait servi plus tard.
|
||||
|
||||
Pour palier à ce problème, le programmeur a créé un principe révolutionnaire (ouais... à mon avis, on s'est inspiré d'autres trucs, mais on va dire que c'est nous les créateurs) : le Versioning (*Apparition inexpliquée*).
|
||||
|
||||
D'après projet-isika (c'est pas wikipedia ouais, ils étaient pas clairs eux), le versioning (ou versionnage en français mais c'est quand même vachement dégueu comme mot) consiste à travailler directement sur le code source d'un projet, en gardant toutes les versions précédentes. Les outils du versioning aident les développeurs à travailler parallèlement sur différentes parties du projet et à revenir facilement aux étapes précédentes de leur travail en cas de besoin. L’utilisation d’un logiciel de versioning est devenue quasi-indispensable pour tout développeur, même s’il travaille seul.
|
||||
|
||||
Un versioning pour les gouverner tous
|
||||
-------------------------------------
|
||||
|
||||
On va vite fait passer sur les différents logiciels de contrôle de version avant de revenir à l'essentiel, le vrai, le beau, l'unique et l'ultime : Git.
|
||||
|
||||
**Source Code Control System (SCCS)**) : Développé en 1972 dans les labos d'IBM, il a été porté sur Unix pour ensuite donner naissance à RCS.
|
||||
**GNU RCS (Revision Control System)** : RCS est à l'origine un projet universitaire, initié au début des années 1980, et maintenu pendant plus d'une décennie par Walter F. Tichy au sein de l'université Purdue.
|
||||
|
||||
Ce logiciel représente à l'époque une alternative libre au système SCCS, et une évolution technique, notamment par son interface utilisateur, plus conviviale, et une récupération des données, plus rapide, par l'amélioration du stockage des différentes versions. Ce gain de performance provient d'un algorithme appelé en anglais « reverse differences » (ou plus simplement « deltas ») et consiste à stocker la copie complète des versions les plus récentes et conserver uniquement les changements réalisés.
|
||||
|
||||
**CVS (Concurrent Versions System)** : En gros, c'est la première fois qu'on essaie de fusionner des versions *concurrentes* (dis-donc, quel hasard que ce soit des concurrents vu le nom du système !) de fichiers sources. C'était pas forcément compliqué : en gros, il y avait un serveur qui prenait à chaque fois la dernière version de chaque fichier, les développeurs devaient toujours avoir la dernière version du fichier s'ils voulaient éditer celui-ci. Si c'était pas le cas, le serveur les envoyait paitre.
|
||||
|
||||
**SVN (Subversion)** : En gros, c'est comme CVS mais avec quelques améliorations du fait du refactoring complet fait par Apache. Subversion permet notamment le renommage et le déplacement de fichiers ou de répertoires sans en perdre l'historique. On a aussi un versioning sur les metadatas (genre les changements de permissions des fichiers.
|
||||
|
||||
**Git** : Enfin le voilà. Le versioning ultime. Créé par Linus Torvalds en 2005, il permet notamment au bordel qu'est Linux d'être maintenu par des développeurs du monde entier grâce à un système original de version : en gros, chaque ordinateur a une version du code source et il n'y a pas forcément un serveur central qui garde tout (et demande un compte à chaque fois. Bon, maintenant on est de retour au format minitel avec Github mais on va vous montrer comment s'en sortir). Il y a également un système de branche pour pouvoir gérer différentes versions du code en parallèle. Tout est fait sous forme de petits fichiers de versioning qui vont faire des copies des fichiers correspondant à la modification proposée. Bref, c'est trop bien et on a pas fait mieux.
|
||||
|
||||
C'est pas forcément utile de comprendre le fonctionnement interne de Git pour développer (la preuve, je n'ai pas franchement chercher au tréfond du bousin) mais c'est en revanche indispensable de comprendre comment l'utiliser avant de faire n'importe quoi. Du coup, on va voir ci-dessous comment utiliser Git et comment on l'utilise sur le site AE.
|
||||
|
||||
TLDR
|
||||
----
|
||||
|
||||
Un système de versioning permet de faire de la merde dans votre code et de pouvoir revenir en arrière malgré tout. Ça permet aussi de coder à plusieurs.
|
||||
Git est le meilleur système de gestion de version (ou système de versioning) que vous pourrez trouver à l'heure actuelle. Utilisez-le.
|
||||
Reference in New Issue
Block a user