wip: chapter miscellaneous (#18)

* wip: chapter miscellaneous

* wip: chapter miscellaneous

* wip: docker

* wip: docker

* wip: docker

* wip: docker

* wip: docker

* wip: lowercase frontend / backend terms in thesis

* wip: github actions

* wip: fix issue with not displayed labels

* wip: Antidote 10 karcher

* wip: end chapter

Author: jy95

glossary.tex

@@ -46,6 +46,7 @@
 \newglossaryentry{frontend}
 {
     name={Frontend},
+    text={frontend},
     description={
         Il s'agit de la partie "émergée" de l'application (comparable à un iceberg). C'est l'interface graphique avec laquelle les utilisateurs finaux interagissent.  
     }
@@ -54,6 +55,7 @@
 \newglossaryentry{backend}
 {
     name={Backend},
+    text={backend},
     description={
         Il s'agit de la partie "immergée" de l'application (comparable à un iceberg) : notre \Gls{api}.
     }
@@ -172,4 +174,33 @@
     description={
         Ce terme désigne, comme expliqué par Wikipédia\cite{envvarDef}, "une variables dynamique utilisée par les différents processus d’un système d’exploitation".
     }
+}
+
+\newglossaryentry{deploiement}
+{
+    name={Déploiement},
+    text={déploiement},
+    description={
+        Ensemble d'activités permettant la mise en service du logiciel afin qu'il soit pret à être utilisé.
+    }
+}
+
+\newglossaryentry{maintenance}
+{
+    name={Maintenance},
+    text={maintenance},
+    description={
+        Ensemble d'activités permettant d'assurer le bon fonctionnement du logiciel.
+    }
+}
+
+\newglossaryentry{ci_cd}
+{
+    name={CI/CD},
+    description={
+        Abréviation anglophone pour "Continuous integration / Continuous Delivery", ce qui peut se traduire comme intégration continue / \gls{deploiement} continu.
+        Il s'agit donc de l'association de ces 2 concepts.
+        L'intégration continue consistant à vérifier que chaque modification du code source n'engendre pas de défauts, notamment par l'usage de tests.
+        Le \gls{deploiement} continu consistant à réaliser le \gls{deploiement} à chaque modification du code source, par le billet d'un système automatisé.
+    }
 }

images/serveur/CLI.jpg

@@ -1,3 +1,2 @@
-\includepdf[pages=1,pagecommand=\chapter{Analyse Bibliographique}, offset=0 -1cm, scale=0.8]{sections/annexes/analyseBibliographique/Analyse_Bibliographique.pdf}
-\label{annexe:AnalyseBiblio}
+\includepdf[pages=1,pagecommand=\chapter{Analyse Bibliographique}\label{annexe:AnalyseBiblio}, offset=0 -1cm, scale=0.8]{sections/annexes/analyseBibliographique/Analyse_Bibliographique.pdf}
 \includepdf[pages=2-,pagecommand={},width=1.2\textwidth]{sections/annexes/analyseBibliographique/Analyse_Bibliographique.pdf}

images/serveur/dockerHub.PNG

@@ -6,12 +6,14 @@ \chapter{Extraits de codes}
 %\lstinputlisting[label={}]{src/to/code.js}
 \lstinputlisting[
     style=ES6,
-    caption={Point d'entrée d'une application, sur base de Yargs}
+    caption={Point d'entrée d'une application, sur base de Yargs},
+    label={code:mainYargs}
 ]{codes/mainCLI.js}
 
 \lstinputlisting[
     style=ES6,
-    caption={Exemple d'une implémentation d'une commande "Yargs"}
+    caption={Exemple d'une implémentation d'une commande "Yargs"},
+    label={code:crawlerYargs}
 ]{codes/crawler.js}
 
 \lstinputlisting[

images/serveur/dockerTaxonomy.png

@@ -194,7 +194,7 @@ \subsection{Code coverage}
 
 Avec 48 tests, nous avons pu atteindre une couverture maximale (100\%), car chaque méthode a été testée extensivement avec le \textit{branch coverage}.\\
 
-Vous pouvez d'ailleurs consulter les résultats depuis \url{https://codecov.io/gh/SourceCodeOER/sourcecode_api/list/master/}.
+Vous pouvez d'ailleurs consulter les résultats depuis \url{https://codecov.io/gh/SourceCodeOER/sourcecode_api/branch/master}.
 
 
 

images/serveur/workflowGithubActions.PNG

@@ -130,8 +130,8 @@ \subsection*{Conception et implémentation}
 Contrairement à l'analyse, la conception et l'implémentation ont été réalisées en fonction du domaine spécifique de chacun : 
 
 \begin{description}
-    \item[Jacques] : responsable du \Gls{backend} et du \Gls{cli} : base de données, extraction et nettoyage des données, gestion de la performance et la sécurité.
-    \item[Alexandre] : responsable du \Gls{frontend} : prototypage de l'application, interface graphique.
+    \item[Jacques] : responsable du \gls{backend} et du \Gls{cli} : base de données, extraction et nettoyage des données, gestion de la performance et la sécurité.
+    \item[Alexandre] : responsable du \gls{frontend} : prototypage de l'application, interface graphique.
 \end{description}
 
 Le principal problème avec cette approche est la "compartimentation" qui favorise une connaissance limitée de la totalité des technologies utilisées. Ceci risque de provoquer un arrêt qui, temporairement ou non, nuit à la bonne réalisation de nos objectifs dans les délais fixés si un membre de notre équipe se retrouve dans l'incapacité sa part de travail pour l'une ou l'autre raison. \\

sections/annexes/analyseBibliographique/index.tex

@@ -18,23 +18,23 @@ \subsection{Structure du projet}
 \end{figure}
 
 Cette structure ne vous est peut-être pas inconnue, car il s'agit de la structure officielle de Sequelize\footnote{
-    \url{https://github.com/sequelize/cli} - command "sequelize init"
+    \url{https://github.com/sequelize/cli} - commande "sequelize init"
 }, sur laquelle nous avons ajouté quelques dossiers :
 
 % A voir s'il faut minimiser l'itemize
 % nosep,noitemsep,topsep=0pt,partopsep=0pt,after=\vspace*{2pt}
 \begin{itemize}
     \item openapi : nos fichiers \Gls{oas}, utilisés par openapi-enforcer (cf. figure \ref{fig:OASEnforcer})
     \item controllers : nos fichiers chargés de répondre aux requêtes \textbf{HTTP}, utilisés par openapi-enforcer (cf. figure \ref{fig:OASEnforcer})
-    \item tests : nos tests pour valider l'implémentation (cf. chap TODO)
+    \item tests : nos tests pour valider l'implémentation (cf. section \ref{section:validation})
     \item docs : la documentation de l'\Gls{api} en \textbf{HTML}\footnote{
         Celle-ci est automatiquement publiée sur 
         \href{https://sourcecodeoer.github.io/sourcecode\_api/}{https://sourcecodeoer.github.io/sourcecode\_api/}.
         Pour la générer en local, cela se fait via la commande : 
         npx redoc-cli bundle api.yml -o docs/index.html 
     } (cf. figure \ref{fig:exampleDoc} pour un exemple)
     \item upload / files : resp. lieu de stockage des fichiers importés / stockés 
-    \item .github : nos scripts d'automatisation (cf. section TODO) 
+    \item .github : nos scripts d'automatisation de type Github Actions (cf. section \ref{section:GithubActions}) 
     \item bin : du code n'entrant dans aucun autre dossier
 \end{itemize}
 
@@ -46,7 +46,7 @@ \subsubsection{Paramétrisation de l'\Gls{api}}
 Comme révélé en section \ref{section:AnalyseNonFonctionnelle}, il convient d'accorder un certain contrôle aux utilisateurs finaux.
 Une manière de configurer une telle application est d'utiliser des \glspl{envvar}, 
 qui permettent, contrairement à d'autres approches (comme les fichiers de configuration \textbf{JSON}, \textbf{YAML}, ...), 
-de changer de valeur directement, sans éteindre/rédémarrer l'application par exemple. \\
+de changer de valeur directement, sans éteindre/redémarrer l'application par exemple. \\
 
 Nous avons accordé les possibilités suivantes (la liste détaillée des \glspl{envvar} est disponible dans le fichier README.MD) :
 
@@ -84,7 +84,7 @@ \subsubsection{Documentation de l'\Gls{api}}
 \pagebreak
 \subsubsection{\Glspl{middleware}}
 
-Pour rappel (cf section \ref{section:choixTechnologiques}), Express a été le "squelette" sur lequel nous avons construit notre application.
+Pour rappel (cf. section \ref{section:choixTechnologiques}), Express a été le "squelette" sur lequel nous avons construit notre application.
 Une de ses particularités est l'usage de \glspl{middleware}\footnote{
     Par exemple, ceux en section \ref{section:choixTechnologiques} : Passport.js et OpenAPI-enforcer
 } dont nous pouvons expliquer le fonctionnement général par le biais de cette illustration :
@@ -145,7 +145,113 @@ \subsubsection{Recherche par \glspl{tag}}
 \section{Divers}
 \label{chapter:solutionDivers}
 
+Dans cette section, nous aborderons quelques éléments secondaires de \texttt{SourceCode}.
+En effet, en dehors du développement, il existe bien d'autres facettes importantes du cycle de vie\footnote{
+    En anglais, ce terme est connu sous le nom de "software lifecycle". (\url{https://web.maths.unsw.edu.au/~lafaye/CCM/genie-logiciel/cycle-de-vie.htm})
+} d'un logiciel : le \gls{deploiement} / la \gls{maintenance}  ...
+
 \subsection{\texorpdfstring{\Gls{cli}}{CLI}}
+
+Comme nous l'évoquions précédemment (cf. annexe \ref{annexe:AnalyseBiblio}), il convient de disposer d'outils pour indexer / mettre en ligne un nombre conséquent de 
+\glspl{resinfo}, provenant de diverses sources, en un minimum de temps. C'est pour répondre à ce besoin que nous avons développé un \Gls{cli}, sur base du framework Yargs
+(cf. section \ref{section:choixTechnologiques})\footnote{
+    Comme le montre le point d'entrée du \Gls{cli}, à savoir "index.js" (que nous avons inclus dans l'annexe \ref{code:mainYargs}), il sera aisé d'ajouter de nouvelles commandes à l'avenir.
+}.
+
+\begin{figure}[H]
+    \includegraphics[width=\textwidth,height=\textheight,keepaspectratio]{images/serveur/CLI.jpg}
+    \centering
+    \caption{\Gls{cli} - inventaire des commandes disponibles}
+    \label{fig:cliCommands}
+\end{figure}
+
+Chaque commande disposant naturellement de ses propres règles en matière d'arguments et/ou d'options.
+Fort heureusement, Yargs possède un éventail de fonctionnalités très diversifié, que nous allons illustrer un échantillon représentatif sur la commande "crawler" (cf. annexe \ref{code:crawlerYargs}) :
+\begin{itemize}[nosep,noitemsep,topsep=0pt,partopsep=0pt,after=\vspace*{2pt}]
+    \item La possibilité d'indiquer si une option est nécessaire ou non (ligne 28)
+    \item La possibilité de restreindre un choix uniquement à certaines valeurs (ligne 16)
+    \item La possibilité d'identifier quels options et arguments ont été donnés à la commande (lignes 59-62)
+    \item La possibilité de charger un fichier de configuration (lignes 39-40), permettant ainsi de ne pas devoir réécrire l'entièreté de la ligne de commande pour l'invoquer. 
+\end{itemize}
+Veuillez noter que nous avons appliqué le "principe ouvert/fermé"\footnote{
+    La lettre \textbf{O} dans l'anagramme \textbf{SOLID} (\url{https://fr.wikipedia.org/wiki/SOLID\_(informatique)}), qui présente quelques principes pour la programmation orientée objet
+} dans cette commande : en effet, il est possible d'utiliser des stratégies d'indexation déjà implémentées ou non (ex: "inginious-git" qui s'occupe de \glspl{resinfo} au format INGInious\footnote{
+    \url{https://inginious.info.ucl.ac.be/}
+}, disponibles via Git\footnote{
+    \url{https://git-scm.com/}
+}), tout en conservant le même comportement, quelque soit la situation. 
+
+Par respect de la norme que nous avons crée (cf. annexe \ref{annexe:AnalyseBiblio}), nous avons également adopté le \textbf{JSON} et les mêmes conventions d'écriture 
+pour les fichiers d'entrée / de sortie des différentes commandes, à quelques exceptions près que nous avons détaillé dans le fichier README.MD. 
+
+\pagebreak
 \subsection{Docker}
+\label{section:docker}
+
+Comme expliqué par son site officiel\footnote{
+    \url{https://www.docker.com/why-docker}
+}, il s'agit d'une plateforme de conteneurisation permettant de paqueter une application.
+Dans un conteneur sont contenus une application ainsi que tous les éléments dont elle a besoin pour fonctionner (code source, \glspl{library}, ...).
+Le \gls{deploiement} pouvant être réalisé sur n'importe quelle machine, tout en restant plus léger que des alternatives existantes
+\footnote{
+    Des explications sont disponibles sur \url{https://www.docker.com/resources/what-container}
+}.
+Voici un récapitulatif des concepts clés :
+
+\begin{figure}[H]
+    \includegraphics[width=\textwidth,height=0.38\textheight,keepaspectratio]{images/serveur/dockerTaxonomy.png}
+    \centering
+    \caption[Taxonomie des termes et concepts Docker]{Taxonomie des termes et concepts Docker \footnotemark}
+    \label{fig:dockerTaxonomy}
+\end{figure}
+\footnotetext{
+    \url{https://docs.microsoft.com/fr-fr/dotnet/architecture/microservices/container-docker-introduction/docker-containers-images-registries}
+}
+
+Nous avons ainsi découpé notre application en 3 images\footnote{
+    Elles sont disponibles sur Dockerhub (\url{https://hub.docker.com/}) 
+    et générées sur base de fichiers Dockerfile, présents dans chaque repository Github.
+    Notons enfin la présence dans le repository miscellaneous de fichiers docker-compose-***.yml pour déployer automatiquement l'entièreté de \texttt{SourceCode} avec Docker Compose, en fonction de l'environnement souhaité (plus d'informations dans le README.MD).
+} :
+
+\begin{itemize}[nosep,noitemsep,topsep=0pt,partopsep=0pt,after=\vspace*{2pt}]
+    \item sourcecode-front : le \gls{frontend} de \texttt{SourceCode}
+    \item sourcecode\_api : le \gls{backend} de \texttt{SourceCode}
+    \item sourcecode-postgres : une base de données en Postgresql, contenant des données extraites par le \Gls{cli}, pour la démonstration de notre solution (cf. section \ref{section:validation})
+\end{itemize}
+
+\begin{figure}[H]
+    \includegraphics[width=\textwidth,height=0.13\textheight]{images/serveur/dockerHub.PNG}
+    \centering
+    \caption{Docker - des images prêtes à l'emploi}
+    \label{fig:dockerImages}
+\end{figure}
+
+\pagebreak
 \subsection{Github Actions}
+\label{section:GithubActions}
 
+Vous avez peut-être noté la présence d'un dossier \textit{.github} dans chacun des repositories composant notre solution.
+Pour rappel (cf. section \ref{chapter:api}), ce dossier contient des scripts permettant d'automatiser un ensemble de tâches récurrentes, par le biais de Github Actions.
+Comme expliqué par Github\footnote{
+    \url{https://github.com/features/actions}
+}, Github Actions est une fonctionnalité permettant d'automatiser nos workflows\footnote{
+    Si ce terme vous êtes inconnu, nous vous invitons à le découvrir sur \url{https://fr.wikipedia.org/wiki/Workflow}
+}  
+directement sur base du code hébergé chez Github (dont notamment du \gls{ci_cd}).
+Ceci nous permettant de maintenir constantamment un niveau de qualité, via les quelques workflows que nous avons conçus :
+
+\begin{itemize}[nosep,noitemsep,topsep=0pt,partopsep=0pt,after=\vspace*{2pt}]
+    \item Créer une nouvelle image Docker, à chaque modification du code source (cf. section \ref{section:docker})
+    \item Tester le bon fonctionnement de l'\Gls{api}, à chaque modification du code source, par le biais de tests (cf. chapitre \ref{section:validation})
+    \item Vérifier la validité de la documentation en \Gls{oas}, à chaque modification du code source
+    \item Générer la documentation en \textbf{HTML} (cf. figure \ref{fig:exampleDoc})
+    \item Détecter et identifier les changements de l'\Gls{api} suggestibles d'impacter les clients l'utilisant, dont notamment le \gls{frontend}
+\end{itemize}
+
+\begin{figure}[H]
+    \includegraphics[width=\textwidth,height=\textheight,keepaspectratio]{images/serveur/workflowGithubActions.PNG}
+    \centering
+    \caption{Github Actions - exemple de workflows}
+    \label{fig:GithubActionsExample}
+\end{figure}