From 20880f84eeea3885b3f3eab35c6d5c99ce48b489 Mon Sep 17 00:00:00 2001 From: jy95 Date: Thu, 21 May 2020 17:28:10 +0200 Subject: [PATCH 01/10] fix: don't use multitoc but multicol directly --- commonPreamble.sty | 16 ++++++++++++++-- structure.tex | 2 +- 2 files changed, 15 insertions(+), 3 deletions(-) diff --git a/commonPreamble.sty b/commonPreamble.sty index e708663..3063ccd 100644 --- a/commonPreamble.sty +++ b/commonPreamble.sty @@ -292,10 +292,22 @@ literate=% \makeatother % Pour la toc -\usepackage[toc]{multitoc} -\renewcommand*{\multicolumntoc}{2} +\usepackage{multicol} +\newcommand*{\multicolumntoc}{2} \setlength{\columnseprule}{0.5pt} +\makeatletter + +\newcommand\beautifultableofcontents{% + \begin{multicols}{\multicolumntoc}[\section*{\contentsname + \@mkboth{% + \MakeUppercase\contentsname}{\MakeUppercase\contentsname}}]% + \@starttoc{toc}% + \end{multicols}% + } + +\makeatother + % Pour ignorer des figures / tables des tables % C'est uniquement pour les annexes, pour ne pas polluer le tout % \captionsetup{list=no} pour cacher diff --git a/structure.tex b/structure.tex index 49445c0..6806fef 100644 --- a/structure.tex +++ b/structure.tex @@ -15,7 +15,7 @@ \startlist[main]{lot}% starts main list of tables % Table des matières -\tableofcontents +\beautifultableofcontents % Le glossaire % Pour forcer l'affichage de tout ( mais pas idéal car cela n'affiche pas les bonnes pages pour les termes ): https://tex.stackexchange.com/a/492011/129702 From 4047a774e80724158338ccf33701a9b5cb0fa459 Mon Sep 17 00:00:00 2001 From: jy95 Date: Thu, 21 May 2020 19:15:55 +0200 Subject: [PATCH 02/10] wip: first modifications --- sections/chapters/analyseCritique/index.tex | 52 ++++++++++++--------- 1 file changed, 29 insertions(+), 23 deletions(-) diff --git a/sections/chapters/analyseCritique/index.tex b/sections/chapters/analyseCritique/index.tex index 8fb518d..ee9d467 100644 --- a/sections/chapters/analyseCritique/index.tex +++ b/sections/chapters/analyseCritique/index.tex @@ -1,14 +1,6 @@ % Truc qu'Olivier a tellement insisté \chapter{Analyse critique} -Prenons maintenant un peu de recul sur ce projet...\\ - -Au chapitre \ref{chapter:problematique}, nous avons d'abord défini les besoins clés d'une application de partage de \glspl{resinfo} en analysant une série de plateformes web existantes.\\ - -Après cela, en chapitre \ref{chapter:analyseDesBesoins}, nous nous sommes concentrés sur une analyse plus profonde de notre plateforme en y relatant les fonctionnalités à intégrer avec la méthode \textbf{\textit{MoSCoW}}, les besoins à satisfaire pour que la plateforme puisse être utilisée par le grand public, ainsi que les contraintes qui nous ont été imposées (en incluant celles que nous nous sommes imposées).\\ - -Dans le chapitre \ref{chapter:solution}, nous avons enfin expliqué notre solution à la problématique du partage de \glspl{resinfo} en détaillant l'architecture de \texttt{SourceCode} aussi bien du côté \gls{frontend} que du \gls{backend}.\\ - Dans ce chapitre-ci, nous nous efforçons d'avoir un regard critique sur \texttt{SourceCode}. Par la validation du projet (test avec des utilisateurs externes, test de la qualité du code) et les différentes métriques du projet, nous voulons nous assurer que notre prototype ait un sens et contribue utilement à la problématique des \glspl{resinfo}. \section{Validation} @@ -17,10 +9,11 @@ \section{Validation} \subsection{Validation externe} \label{section:validationExterne} -Pour valider notre travail, nous avions initialement planifié deux séances de validation afin de récolter les avis d'un panel d'utilisateurs suffisamment large. -Pour cause de COVID-19, il n'a été possible d'organiser qu'une seule, avec sept utilisateurs. Chaque personne se voyait attribuer deux rôles différents (visiteur-utilisateur ou visiteur-administrateur) afin de prendre connaissance des fonctionnalités les plus importantes de \texttt{SourceCode}. Notre évaluation a pu être réalisée grâce à Google Forms (réponses, graphiques) et vous retrouverez l'intégralité de ce sondage dans l'annexe \ref{annexe:googleForm}\\ +Pour valider notre travail, nous avions initialement planifié deux séances de validation afin de récolter les avis d'un panel d'utilisateurs suffisamment large et diversifié. +Pour cause de COVID-19, nous n'avons pu organiser qu'une seule séance via Teams avec les utilisateurs disponibles : la partie professorale du panel ne disposant généralement plus d'assez de disponibilités à nous accorder. +Chaque personne se voyait attribuer deux rôles différents (visiteur-utilisateur ou visiteur-administrateur) afin de prendre connaissance des fonctionnalités les plus importantes de \texttt{SourceCode}. Notre évaluation a pu être réalisée grâce à Google Forms (réponses, graphiques) et vous retrouverez l'intégralité de ce sondage dans l'annexe \ref{annexe:googleForm}.\\ -Parmi les participants, six d'entre eux font partie de l'\textit{UCLouvain} de la faculté \textit{EPL}, dont quatre étudiants de master en sciences informatiques et deux doctorants. La septième personne est une professeure en section informatique à la \textit{HELHa} de Mons.\\ +Parmi les participants, six d'entre eux font partie de la faculté \textit{EPL} de l'\textit{UCLouvain}, dont quatre étudiants de master en sciences informatiques et deux doctorants. La septième personne est une professeure en section informatique à la \textit{HELHa} de Mons.\\ Un des premiers objectifs de cette séance fut de faire comprendre le but de la plateforme, son utilité. Cela semblait être acquis par la majorité sauf pour une personne. Il n'est pas exclu de penser que cette dernière était biaisée par la plateforme \textit{INGInious} de l'\textit{UCLouvain}, car elle l'a prise comme point de référence pour juger \texttt{SourceCode}.\\ @@ -37,7 +30,8 @@ \subsubsection*{Bibliothèque} \item Le texte de la barre de recherche est trop petit, et en bleu trop clair. \textbf{(corrigé)} \item Un peu difficile de scroller dans la liste des tags (jusqu'à 3 scrollbars). \textbf{(corrigé)} \end{itemize} -\bigskip + +Nos observations : \begin{enumerate} \item La gestion des fautes de frappe ou recherche approximative est une fonctionnalité qui pourrait être très utile pour la bibliothèque (le but étant de faciliter la recherche au maximum). @@ -50,7 +44,7 @@ \subsubsection*{Favoris} \item Quand on crée un favori puis le modifie, difficile de se souvenir de quelle catégorie appartient le tag qu'on a sélectionné précédemment : soit renommer le tag, soit créer un moyen de savoir de quelle catégorie le tag appartient. (1) \end{itemize} -\bigskip +Nos observations : \begin{enumerate} \item Lors de l'édition d'un favori ou d'une \gls{resinfo}, les \glspl{tag} ajoutés sont affichés dans une section du formulaire en mode pêle-mêle (sans les catégories auxquels ils se rapportent). Le seul moyen de vérifier la catégorie à laquelle un \gls{tag} appartient est de naviguer dans le panneau à onglets. Nous discuterons des futures améliorations possibles dans le chapitre \ref{chapter:pourAllerPlusLoin}. @@ -66,11 +60,12 @@ \subsubsection*{Création de \glspl{resinfo}} \item Un peu difficile d'utiliser le panneau des tags (c'est une première) (3) \end{itemize} -\bigskip +Nos observations : + \begin{enumerate} \item Actuellement, il faut d'abord créer un bloc de code puis copier-coller le code que l'on veut formater dedans. La \gls{library} d'édition de texte que nous utilisons (Tiptap) ne gère pas nativement ce qui a été soulevé dans la remarque. En revanche, cette même \gls{library} est extensible et autorise la modification/l'ajout de fonctionnalités de manière aisée. Il est donc tout à fait envisageable de corriger le tir dans une prochaine mise à jour de l'application. \item Certaines personnes se plaignaient que la boîte d'édition était trop petite (ou trop grande). Dans son état actuel, \texttt{SourceCode} n'est pas responsive, et dans la perspective où elle le serait, ce problème sera certainement réglé pour tout écran. - \item Comme cela a déjà été soulevé dans la section concernant la bibliothèque, le panneau des \glspl{tag} est un peu lourd à l'utilisation. Il y avait jusqu'à 3 scrollbars pour naviguer dans le panneau, ce qui diminuait considérablement l'accessibilité. Nous avons donc changé ce comportement en faisant en sorte d'afficher une seule scrollbar, avec un accès plus clair à la barre de recherche sous chaque \glspl{tagCat}. + \item Comme cela a déjà été soulevé dans la section concernant la bibliothèque, le panneau des \glspl{tag} est un peu lourd à l'utilisation. Il y avait jusqu'à 3 scrollbars pour naviguer dans le panneau, ce qui diminuait considérablement l'accessibilité. Nous avons donc corrigé ce comportement en faisant en sorte d'afficher une seule scrollbar, avec un accès plus clair à la barre de recherche sous chaque \glspl{tagCat}. \end{enumerate} \subsubsection*{Esthétique et ergonomie} @@ -80,7 +75,9 @@ \subsubsection*{Esthétique et ergonomie} \item Le bouton retour dans le header est un peu perturbant, car on ne le remarque pas avant d'avoir vraiment pris en main le site. \textbf{(corrigé)} \item Un dark mode (1) \end{itemize} -\bigskip + +Nos observations : + \begin{enumerate} \item Le dark mode n'est pas une fonctionnalité nécessaire à la plateforme, mais elle pourrait ajouter un plus côté attractivité. \end{enumerate} @@ -97,7 +94,9 @@ \subsubsection*{Points forts} \item Le système de tags (utilisé correctement par les utilisateurs) semble flexible et potentiellement très utile. \item Visuellement attrayant. \end{itemize} -\bigskip + +Nos observations : + \begin{enumerate} \item La grande communauté dépendra surtout de la qualité de l'application et de son utilité. Les exercices que nous avons utilisés pour la séance de validation étaient importés à partir de quatre cours hébergés sur la plateforme \textit{INGInious}. Nous pouvons donc aisément fournir plus de contenu rien qu'en important tous les cours stockés sur cette même plateforme avec l'avantage d'un système de \glspl{tag} plus avancé. \end{enumerate} @@ -110,11 +109,12 @@ \subsubsection*{Points faibles} \item L'application est très complète, mais le souci vient justement de cela : la courbe d'apprentissage est assez pentue, mais après cela, l'outil deviendrait très puissant (difficulté pour les professeurs un peu moins "tech savvy"). (3) \end{itemize} -\bigskip +Nos observations : + \begin{enumerate} \item \texttt{SourceCode} pourra très rapidement posséder une riche bibliothèque de \glspl{resinfo} rien qu'avec les exercices stockés sur la plateforme \textit{INGInious}. Avec la promotion de la plateforme auprès d'autres institutions scolaires, \texttt{SourceCode} pourrait alors prétendre à une popularité certaine dans le monde des ressources partagées. Il s'agit alors de savoir vendre son produit avec les bons arguments... \item Nous n'avions pas pensé à cela pour le prototype. Nous voulions d'abord créer un système cohérent et fonctionnel au niveau de la gestion des \glspl{resinfo} et \glspl{tag}. Les différents statuts attribuables à ces mêmes \glspl{resinfo} et \glspl{tag} jouent déjà un rôle majeur dans la gestion (ex: trier les \glspl{resinfo} non valides ou en attente de validation ...). En termes d'améliorations, nous pourrions automatiser le processus de validation afin que les administrateurs ne soient pas débordés (cf. chapitre \ref{chapter:pourAllerPlusLoin}). - \item C'est un point intéressant pour nous. \texttt{SourceCode} est une application qui tente de faciliter le plus possible la recherche et la gestion de \glspl{resinfo} (système de filtres, historique, favoris ...). Malheureusement, ajouter une pléthore de fonctionnalités peut aussi devenir une barrière à l'utilisation, car l'utilisateur doit d'abord apprendre à les maîtriser. Une des premières solutions que nous avons mises en place était la création d'une section tutoriel sur la plateforme, mais cela n'est qu'une solution de contournement. Il faut que la plateforme puisse évoluer en termes d'ergonomie pour rendre l'interface plus accessible aux utilisateurs. + \item C'est un point intéressant pour nous. \texttt{SourceCode} est une application qui tente de faciliter le plus possible la recherche et la gestion de \glspl{resinfo} (système de filtres, historique, favoris ...). Malheureusement, ajouter une pléthore de fonctionnalités peut aussi devenir une barrière à l'utilisation, car l'utilisateur doit d'abord apprendre à les maîtriser. Une des premières solutions que nous avons mises en place était la création d'une section tutoriel sur la plateforme, mais cela n'est qu'une solution de contournement. Une autre idée serait de prévoir une interface en fonction du public ciblé (débutant, "tech savvy" ...). \end{enumerate} \subsubsection*{Que pouvons-nous faire pour améliorer l'application ?} @@ -125,7 +125,9 @@ \subsubsection*{Que pouvons-nous faire pour améliorer l'application ?} \item Améliorer l'agencement des menus. (1) \item Une fonction mot de passe oublié pour les utilisateurs. (2) \end{itemize} -\bigskip + +Nos observations : + \begin{enumerate} \item Dans les retours d'utilisation, les testeurs étaient perturbés avec le menu principal et le panneau latéral. La confusion venait du fait que le menu principal comportait des chevrons, ce qui laissait penser à une structure à plusieurs niveaux (listes). Le panneau de filtres contenait aussi ces mêmes chevrons, alors nous avons supprimé ces derniers sur le menu principal pour enlever cette confusion. \item C'est une fonctionnalité importante pour ce genre d'application, mais nous n'avons pas pris le temps de l'intégrer. Nous l'ajoutons dans le chapitre \ref{chapter:pourAllerPlusLoin}. @@ -140,7 +142,9 @@ \subsubsection*{Que manquerait-il pour que cette plateforme ne soit plus un prot \item Pour moi c'est plus qu'un prototype au stade où elle en est. S'il fallait vraiment une fonctionnalité en plus, ça serait de pouvoir ajouter ses solutions sur la plateforme. (1) \item Une manière d'interagir entre les étudiants et les "créateurs d'exercices" ? Histoire de pouvoir au moins poser des questions et ne pas être aussi détachés. (2) \end{itemize} -\bigskip + +Nos observations : + \begin{enumerate} \item \texttt{SourceCode} n'est pas prévu pour résoudre des exercices depuis la plateforme. À ce stade-ci, on peut la considérer comme un référenceur de \glspl{resinfo} qui faciliterait la recherche de ressources particulière avec un système de recherche complet. Dans une perspective future, \texttt{SourceCode} pourrait avoir son propre correcteur d'exercices si la ressource nécessite une résolution. Dans ce cas, cela profiterait aux étudiants pour s'évaluer. \item Certaines plateformes comme Hackerrank ou Coderbyte ont prévu une section forum pour chaque exercice/challenge. C'est une fonctionnalité intéressante, mais elle va de pair avec le point précédent. @@ -153,7 +157,9 @@ \subsubsection*{Pensez-vous que cette application ait un réel impact dans le mo \item Il faudrait juste voir comment gérer l'accès entre votre plateforme et celles qui permettent la correction des exercices (Inginious). Par exemple un moyen de linker votre plateforme avec les autres, pour qu'en un clic on arrive directement sur l'exercice inginious en étant déjà connecté dessus. \item Sans être intégrée à une plateforme automatisée de correction de code, et sans une gestion de parcours et de lien entre les exercices, sans doute pas beaucoup. Elle sera limitée à une utilisation par les enseignants pour créer leurs propres cours. (1) \end{itemize} -\bigskip + +Nos observations : + \begin{enumerate} \item La plateforme est d'abord créée pour l'équipe pédagogique, prônant le partage de \glspl{resinfo} dans une bibliothèque triée par \glspl{tag}. Une prochaine étape serait alors d'intégrer un système de correction d'exercices directement depuis la plateforme. Nous n'avions pas eu le temps d'intégrer une telle fonctionnalité, mais cela pourrait définitivement être utile aux étudiants. \end{enumerate} @@ -240,7 +246,7 @@ \subsection{Graphe d'activité} \subsection{Conclusion} -Ce chapitre était agréable à rédiger, car nous avons pu constater si \texttt{SourceCode} est un projet qui tient la route à son stade de développement.\\ +À travers ce chapitre, nous avons pu constater si \texttt{SourceCode} est un projet qui tient la route à son stade de développement.\\ La séance de validation nous a été extrêmement bénéfique, car les remarques étaient constructives. Cela nous conforte dans l'idée que notre plateforme a des chances de devenir mature et utilisable par une communauté. Quoi qu'il en soit, notre projet est \textit{Open Source} et pourra donc toujours évoluer avec sa communauté. C'est d'ailleurs notre plus grand souhait pour cette plateforme.\\ From df5a899c7ec45dc20965f1cb87344118b9eae6c1 Mon Sep 17 00:00:00 2001 From: jy95 Date: Fri, 22 May 2020 02:47:32 +0200 Subject: [PATCH 03/10] wip: refactoring metrics (TODO) --- sections/chapters/analyseCritique/index.tex | 245 +----------------- .../analyseCritique/validationExterne.tex | 172 ++++++++++++ .../analyseCritique/validationInterne.tex | 57 ++++ .../chapters/solution/choixTechno/index.tex | 2 +- 4 files changed, 234 insertions(+), 242 deletions(-) create mode 100644 sections/chapters/analyseCritique/validationExterne.tex create mode 100644 sections/chapters/analyseCritique/validationInterne.tex diff --git a/sections/chapters/analyseCritique/index.tex b/sections/chapters/analyseCritique/index.tex index ee9d467..56bf34f 100644 --- a/sections/chapters/analyseCritique/index.tex +++ b/sections/chapters/analyseCritique/index.tex @@ -1,250 +1,13 @@ -% Truc qu'Olivier a tellement insisté \chapter{Analyse critique} - -Dans ce chapitre-ci, nous nous efforçons d'avoir un regard critique sur \texttt{SourceCode}. Par la validation du projet (test avec des utilisateurs externes, test de la qualité du code) et les différentes métriques du projet, nous voulons nous assurer que notre prototype ait un sens et contribue utilement à la problématique des \glspl{resinfo}. - -\section{Validation} \label{section:validation} -\subsection{Validation externe} -\label{section:validationExterne} - -Pour valider notre travail, nous avions initialement planifié deux séances de validation afin de récolter les avis d'un panel d'utilisateurs suffisamment large et diversifié. -Pour cause de COVID-19, nous n'avons pu organiser qu'une seule séance via Teams avec les utilisateurs disponibles : la partie professorale du panel ne disposant généralement plus d'assez de disponibilités à nous accorder. -Chaque personne se voyait attribuer deux rôles différents (visiteur-utilisateur ou visiteur-administrateur) afin de prendre connaissance des fonctionnalités les plus importantes de \texttt{SourceCode}. Notre évaluation a pu être réalisée grâce à Google Forms (réponses, graphiques) et vous retrouverez l'intégralité de ce sondage dans l'annexe \ref{annexe:googleForm}.\\ - -Parmi les participants, six d'entre eux font partie de la faculté \textit{EPL} de l'\textit{UCLouvain}, dont quatre étudiants de master en sciences informatiques et deux doctorants. La septième personne est une professeure en section informatique à la \textit{HELHa} de Mons.\\ - -Un des premiers objectifs de cette séance fut de faire comprendre le but de la plateforme, son utilité. Cela semblait être acquis par la majorité sauf pour une personne. Il n'est pas exclu de penser que cette dernière était biaisée par la plateforme \textit{INGInious} de l'\textit{UCLouvain}, car elle l'a prise comme point de référence pour juger \texttt{SourceCode}.\\ - -Les sous-sections suivantes résument les critiques émises sur \texttt{SourceCode}. Certaines remarques suggéraient des améliorations et corrections. Avec le temps qui nous restait, nous avons essayé de les prendre en compte pour rendre l'utilisation de la plateforme un peu plus immersive et plus fonctionnelle. Vous retrouverez alors un "\textbf{(corrigé)}" quand nous avons pu prendre en considération la remarque. - -\subsubsection*{Bibliothèque} - -\begin{itemize} - \item Système de recherche intuitif, rapide et riche en filtres. - \item La barre de recherche n'est pas bien placée, car elle laisse penser que c'est pour lancer une recherche sur tout le domaine du site web. \textbf{(corrigé)} - \item Dans la création de favoris depuis le panneau, au lieu de cliquer sur OK, appuyer sur enter pour valider le nom du nouveau favori. \textbf{(corrigé)} - \item Ajouter quelques tags + titre de recherche plutôt que juste le nom du favori dans la partie onglet "favoris". \textbf{(corrigé)} - \item Recherche : Gestion des fautes de frappe et/ou recherche approximative. (1) - \item Le texte de la barre de recherche est trop petit, et en bleu trop clair. \textbf{(corrigé)} - \item Un peu difficile de scroller dans la liste des tags (jusqu'à 3 scrollbars). \textbf{(corrigé)} -\end{itemize} - -Nos observations : - -\begin{enumerate} - \item La gestion des fautes de frappe ou recherche approximative est une fonctionnalité qui pourrait être très utile pour la bibliothèque (le but étant de faciliter la recherche au maximum). -\end{enumerate} - -\subsubsection*{Favoris} - -\begin{itemize} - \item Pas nécessaire d'avoir obligatoirement un tag pour créer un favori. \textbf{(corrigé)} - \item Quand on crée un favori puis le modifie, difficile de se souvenir de quelle catégorie appartient le tag qu'on a sélectionné précédemment : soit renommer le tag, soit créer un moyen de savoir de quelle catégorie le tag appartient. (1) -\end{itemize} - -Nos observations : - -\begin{enumerate} - \item Lors de l'édition d'un favori ou d'une \gls{resinfo}, les \glspl{tag} ajoutés sont affichés dans une section du formulaire en mode pêle-mêle (sans les catégories auxquels ils se rapportent). Le seul moyen de vérifier la catégorie à laquelle un \gls{tag} appartient est de naviguer dans le panneau à onglets. Nous discuterons des futures améliorations possibles dans le chapitre \ref{chapter:pourAllerPlusLoin}. -\end{enumerate} - - -\subsubsection*{Création de \glspl{resinfo}} - -\begin{itemize} - \item Frustrant de ne pas pouvoir créer un bloc de code directement depuis plusieurs lignes sélectionnées. (1) - \item Ajouter un pour l'édition du code. \textbf{(corrigé)} - \item Possibilité d'agrandir la boîte d'édition de texte. (2) - \item Un peu difficile d'utiliser le panneau des tags (c'est une première) (3) -\end{itemize} - -Nos observations : - -\begin{enumerate} - \item Actuellement, il faut d'abord créer un bloc de code puis copier-coller le code que l'on veut formater dedans. La \gls{library} d'édition de texte que nous utilisons (Tiptap) ne gère pas nativement ce qui a été soulevé dans la remarque. En revanche, cette même \gls{library} est extensible et autorise la modification/l'ajout de fonctionnalités de manière aisée. Il est donc tout à fait envisageable de corriger le tir dans une prochaine mise à jour de l'application. - \item Certaines personnes se plaignaient que la boîte d'édition était trop petite (ou trop grande). Dans son état actuel, \texttt{SourceCode} n'est pas responsive, et dans la perspective où elle le serait, ce problème sera certainement réglé pour tout écran. - \item Comme cela a déjà été soulevé dans la section concernant la bibliothèque, le panneau des \glspl{tag} est un peu lourd à l'utilisation. Il y avait jusqu'à 3 scrollbars pour naviguer dans le panneau, ce qui diminuait considérablement l'accessibilité. Nous avons donc corrigé ce comportement en faisant en sorte d'afficher une seule scrollbar, avec un accès plus clair à la barre de recherche sous chaque \glspl{tagCat}. -\end{enumerate} - -\subsubsection*{Esthétique et ergonomie} - -\begin{itemize} - \item Très chouette. - \item Le bouton retour dans le header est un peu perturbant, car on ne le remarque pas avant d'avoir vraiment pris en main le site. \textbf{(corrigé)} - \item Un dark mode (1) -\end{itemize} - -Nos observations : - -\begin{enumerate} - \item Le dark mode n'est pas une fonctionnalité nécessaire à la plateforme, mais elle pourrait ajouter un plus côté attractivité. -\end{enumerate} - -\subsubsection*{Points forts} - -\begin{itemize} - \item Ergonomique et riche en filtres de recherche. - \item Très complète. - \item Très utile, s'il y a une grande communauté et qu'il y a beaucoup d'exercices. (1) - \item La sélection dynamique est top (pour la recherche). - \item Design, visuel, fluidité. - \item L'idée de rassembler toutes les ressources informatiques au même endroit semble pertinente et utile. - \item Le système de tags (utilisé correctement par les utilisateurs) semble flexible et potentiellement très utile. - \item Visuellement attrayant. -\end{itemize} - -Nos observations : - -\begin{enumerate} - \item La grande communauté dépendra surtout de la qualité de l'application et de son utilité. Les exercices que nous avons utilisés pour la séance de validation étaient importés à partir de quatre cours hébergés sur la plateforme \textit{INGInious}. Nous pouvons donc aisément fournir plus de contenu rien qu'en important tous les cours stockés sur cette même plateforme avec l'avantage d'un système de \glspl{tag} plus avancé. -\end{enumerate} - -\subsubsection*{Points faibles} - -\begin{itemize} - \item S'il y a peu d'exercices, la plateforme aura peu de sens. (1) - \item S'il y a trop d'exercices, les administrateurs pourraient peut-être demeurer débordés pour la modération. (2) - \item L'application est très complète, mais le souci vient justement de cela : la courbe d'apprentissage est assez pentue, mais après cela, l'outil deviendrait très puissant (difficulté pour les professeurs un peu moins "tech savvy"). (3) -\end{itemize} - -Nos observations : - -\begin{enumerate} - \item \texttt{SourceCode} pourra très rapidement posséder une riche bibliothèque de \glspl{resinfo} rien qu'avec les exercices stockés sur la plateforme \textit{INGInious}. Avec la promotion de la plateforme auprès d'autres institutions scolaires, \texttt{SourceCode} pourrait alors prétendre à une popularité certaine dans le monde des ressources partagées. Il s'agit alors de savoir vendre son produit avec les bons arguments... - \item Nous n'avions pas pensé à cela pour le prototype. Nous voulions d'abord créer un système cohérent et fonctionnel au niveau de la gestion des \glspl{resinfo} et \glspl{tag}. Les différents statuts attribuables à ces mêmes \glspl{resinfo} et \glspl{tag} jouent déjà un rôle majeur dans la gestion (ex: trier les \glspl{resinfo} non valides ou en attente de validation ...). En termes d'améliorations, nous pourrions automatiser le processus de validation afin que les administrateurs ne soient pas débordés (cf. chapitre \ref{chapter:pourAllerPlusLoin}). - \item C'est un point intéressant pour nous. \texttt{SourceCode} est une application qui tente de faciliter le plus possible la recherche et la gestion de \glspl{resinfo} (système de filtres, historique, favoris ...). Malheureusement, ajouter une pléthore de fonctionnalités peut aussi devenir une barrière à l'utilisation, car l'utilisateur doit d'abord apprendre à les maîtriser. Une des premières solutions que nous avons mises en place était la création d'une section tutoriel sur la plateforme, mais cela n'est qu'une solution de contournement. Une autre idée serait de prévoir une interface en fonction du public ciblé (débutant, "tech savvy" ...). -\end{enumerate} - -\subsubsection*{Que pouvons-nous faire pour améliorer l'application ?} - -\begin{itemize} - \item Il s'agit d'un produit bien abouti ! Vous êtes à un stade où ça sera les utilisateurs de la plateforme qui vous feront des feedbacks sur ce qui serait bien à ajouter/améliorer. - \item Clarifier l'interface. L'UI représente cependant beaucoup de travail. Vous avez priorisé les bonnes choses. - \item Améliorer l'agencement des menus. (1) - \item Une fonction mot de passe oublié pour les utilisateurs. (2) -\end{itemize} - -Nos observations : - -\begin{enumerate} - \item Dans les retours d'utilisation, les testeurs étaient perturbés avec le menu principal et le panneau latéral. La confusion venait du fait que le menu principal comportait des chevrons, ce qui laissait penser à une structure à plusieurs niveaux (listes). Le panneau de filtres contenait aussi ces mêmes chevrons, alors nous avons supprimé ces derniers sur le menu principal pour enlever cette confusion. - \item C'est une fonctionnalité importante pour ce genre d'application, mais nous n'avons pas pris le temps de l'intégrer. Nous l'ajoutons dans le chapitre \ref{chapter:pourAllerPlusLoin}. -\end{enumerate} - -\subsubsection*{Que manquerait-il pour que cette plateforme ne soit plus un prototype en termes de fonctionnalités ?} - -\begin{itemize} - \item Je ne vous rejoins pas sur l'idée que Source Code en est au stade de "prototype". Ça ressemble bien plus à un produit fini, en une première version, qui peut être concernée par d'éventuelles mises à jour par la suite. - \item Pas grand-chose, et beaucoup à la fois. Il s'agit du lent travail de lisser les bugs et les surprises que peuvent rencontrer les utilisateurs. - \item Peut-être la complétion automatique dans la barre de recherche - \item Pour moi c'est plus qu'un prototype au stade où elle en est. S'il fallait vraiment une fonctionnalité en plus, ça serait de pouvoir ajouter ses solutions sur la plateforme. (1) - \item Une manière d'interagir entre les étudiants et les "créateurs d'exercices" ? Histoire de pouvoir au moins poser des questions et ne pas être aussi détachés. (2) -\end{itemize} - -Nos observations : - -\begin{enumerate} - \item \texttt{SourceCode} n'est pas prévu pour résoudre des exercices depuis la plateforme. À ce stade-ci, on peut la considérer comme un référenceur de \glspl{resinfo} qui faciliterait la recherche de ressources particulière avec un système de recherche complet. Dans une perspective future, \texttt{SourceCode} pourrait avoir son propre correcteur d'exercices si la ressource nécessite une résolution. Dans ce cas, cela profiterait aux étudiants pour s'évaluer. - \item Certaines plateformes comme Hackerrank ou Coderbyte ont prévu une section forum pour chaque exercice/challenge. C'est une fonctionnalité intéressante, mais elle va de pair avec le point précédent. -\end{enumerate} - -\subsubsection*{Pensez-vous que cette application ait un réel impact dans le monde des ressources partagées ?} - -\begin{itemize} - \item Oui (de la part de la majorité) - \item Il faudrait juste voir comment gérer l'accès entre votre plateforme et celles qui permettent la correction des exercices (Inginious). Par exemple un moyen de linker votre plateforme avec les autres, pour qu'en un clic on arrive directement sur l'exercice inginious en étant déjà connecté dessus. - \item Sans être intégrée à une plateforme automatisée de correction de code, et sans une gestion de parcours et de lien entre les exercices, sans doute pas beaucoup. Elle sera limitée à une utilisation par les enseignants pour créer leurs propres cours. (1) -\end{itemize} - -Nos observations : - -\begin{enumerate} - \item La plateforme est d'abord créée pour l'équipe pédagogique, prônant le partage de \glspl{resinfo} dans une bibliothèque triée par \glspl{tag}. Une prochaine étape serait alors d'intégrer un système de correction d'exercices directement depuis la plateforme. Nous n'avions pas eu le temps d'intégrer une telle fonctionnalité, mais cela pourrait définitivement être utile aux étudiants. -\end{enumerate} - -\subsubsection*{Utiliseriez-vous cette plateforme ? Quelle serait votre activité principale ?} - -\begin{itemize} - \item Je pense que pour des professeurs, cela peut être très utile pour trouver et donner des exercices à des étudiants (ou d'avoir des idées). - \item Trouver des idées d'exercices pour compléter mes cours. - \item Je pense que ça s'appliquerait surtout au domaine éducatif. - \item Oui, en tant que professeur/enseignant, pourvu que les solutions soient mises à dispositions. -\end{itemize} - -\subsubsection*{Conclusion} - -Cette séance de validation a globalement été positive et instructive. Le message d'une plateforme de partage de \glspl{resinfo} à destination d'une équipe pédagogique semble être acquis par la majorité. -Nous avons appris que la plateforme dispose d'un design et d'une ergonomie satisfaisants. Il faut néanmoins y apporter quelques mises à jour pour rendre le projet mature, notamment au niveau de l'ergonomie. -Certaines des fonctionnalités mentionnées dans les critiques ont pu être intégrées à \texttt{SourceCode} pour l'améliorer le plus possible. Pour celles qui n'ont pas été ajoutées, nous les avons référencées dans le chapitre \ref{chapter:pourAllerPlusLoin}. - -\subsection{Code coverage} -\label{section:codeCoverage} - -Le \gls{backend} a aussi eu sa forme de validation avec un ensemble de tests pour s'assurer que l'\gls{api} fait bien ce qu'on attend d'elle.\\ - -Nous avons principalement utilisé le \textit{branch coverage}, dont nous allons vous expliquer son fonctionnement avec un exemple.\\ - -\begin{figure}[H] - \includegraphics[width=\textwidth,height=0.3\textheight,keepaspectratio]{images/analyseCritique/CFG.png} - \centering - \caption[Exemple d'un CFG pour le branch coverage]{Exemple d'un CFG pour le branch coverage \cite{concept_cfg}} -\end{figure} - -Sur cette image illustrant la méthode \texttt{binsearch} (recherche binaire), nous pouvons découper en plusieurs parties le code afin de dessiner le schéma présenté sur la droite. Ce dernier désigne un graphe de flot de contrôle (GFC) représentant tous les chemins qui peuvent être suivis par un programme lors de son exécution.\\ - -Pour le \textit{branch coverage}, on dit que chaque branche doit être exécutée au moins une fois. Dans le cas du GFC, cela se traduit par le passage sur chaque arête au moins une fois.\\ - -Mesure : $ C_{branche} = \frac{\# \; branches \; exécutées}{\# \; branches} $\\ - -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/branch/master}. - - - -\section{Métriques} - -Cette section traduit notre implication sur ce projet. Pour ce faire, nous avons repris des statistiques des répertoires GitHub du \gls{frontend} et de l'\gls{api}. La notion la plus intéressante à prendre en compte sera le graphe d'activité pour les deux répertoires, car nous avons tenté de respecter le planning imposé (voir \ref{pic:ganttChart}). - -\subsection{Statistiques} - -\begin{itemize} - \item Nombre de lignes de code (frontend + backend) : 21685 + 10158 = 31843 - \begin{itemize} - \item Le nombre de lignes de code a été calculé en retirant tous les fichiers générés automatiquement par un script (ex : npm install qui va créer un fichier \textit{package-lock.json}). - \end{itemize} - \item Nombre de pull requests résolues (frontend + backend) : 49 + 79 = 128 - \begin{itemize} - \item Nous avons beaucoup utilisé les pull requests avec GitHub, car nous voulions garder une trace des mises à jour importantes effectuées. Elles ont aussi été extrêmement utiles avec l'intégration continue de \textit{Docker} qui nous permettait de rapidement tester l'application avec l'une d'elles. - \end{itemize} -\end{itemize} - -\subsection{Graphe d'activité} - -\texttt{SourceCode} a connu un développement plus ou moins constant durant l'année académique 2019-2020. Étant donné que le \gls{frontend} et le \gls{backend} sont intimement liés, vous pourrez constater sur le graphe \ref{figure:frontendActivity} et \ref{figure:backendActivity} que la forte activité de l'un compense l'activité au ralenti de l'autre répertoire. - -\begin{figure}[H] - \includegraphics[width=\textwidth,height=0.3\textheight,keepaspectratio]{images/analyseCritique/graph_frontend.png} - \centering - \caption{GitHub : graphe d'activité (frontend)} - \label{figure:frontendActivity} -\end{figure} - -Les fonctionnalités les plus importantes comme la recherche dans la bibliothèque, la consultation d'une \gls{fiche} et la gestion des \glspl{resinfo} ont été intégrées durant la période d'octobre à janvier, après quoi nous avons amélioré l'expérience d'utilisation de l'application en appliquant quelques mises à jour et corrections de bugs jusqu'au mois de mai.\\ - -\begin{figure}[H] - \includegraphics[width=\textwidth,height=0.3\textheight,keepaspectratio]{images/analyseCritique/graph_backend.png} - \centering - \caption{GitHub : graphe d'activité (backend)} - \label{figure:backendActivity} -\end{figure} +Dans ce chapitre-ci, nous nous efforçons d'avoir un regard critique sur \texttt{SourceCode}. Par la validation du projet (test avec des utilisateurs externes, test de la qualité du code) et les différentes métriques du projet, nous voulons nous assurer que notre prototype ait un sens et contribue utilement à la problématique des \glspl{resinfo}. +\import{sections/chapters/analyseCritique/}{validationExterne} -Globalement, nous avons respecté le planning \ref{pic:ganttChart} que nous nous sommes imposé. Nous avons cependant effectué une dernière mise à jour prenant en compte un maximum des remarques relatées en section \ref{section:validationExterne}, car nous voulions prouver que \texttt{SourceCode} est capable de s'adapter aux besoins des utilisateurs. +\import{sections/chapters/analyseCritique/}{validationInterne} -\subsection{Conclusion} +\section{Conclusion} À travers ce chapitre, nous avons pu constater si \texttt{SourceCode} est un projet qui tient la route à son stade de développement.\\ diff --git a/sections/chapters/analyseCritique/validationExterne.tex b/sections/chapters/analyseCritique/validationExterne.tex new file mode 100644 index 0000000..6f0c9d0 --- /dev/null +++ b/sections/chapters/analyseCritique/validationExterne.tex @@ -0,0 +1,172 @@ +\section{Validation externe} +\label{section:validationExterne} + +Pour valider notre travail, nous avions initialement planifié deux séances de validation afin de récolter les avis d'un panel d'utilisateurs suffisamment large et diversifié. +Pour cause de COVID-19, nous n'avons pu organiser qu'une seule séance via Teams avec les utilisateurs disponibles : la partie professorale du panel ne disposant généralement plus d'assez de disponibilités à nous accorder. +Chaque personne se voyait attribuer deux rôles différents (visiteur-utilisateur ou visiteur-administrateur) afin de prendre connaissance des fonctionnalités les plus importantes de \texttt{SourceCode}. Notre évaluation a pu être réalisée grâce à Google Forms (réponses, graphiques) et vous retrouverez l'intégralité de ce sondage dans l'annexe \ref{annexe:googleForm}.\\ + +Parmi les participants, six d'entre eux font partie de la faculté \textit{EPL} de l'\textit{UCLouvain}, dont quatre étudiants de master en sciences informatiques et deux doctorants. La septième personne est une professeure en section informatique à la \textit{HELHa} de Mons.\\ + +Un des premiers objectifs de cette séance fut de faire comprendre le but de la plateforme, son utilité. Cela semblait être acquis par la majorité sauf pour une personne. Il n'est pas exclu de penser que cette dernière était biaisée par la plateforme \textit{INGInious} de l'\textit{UCLouvain}, car elle l'a prise comme point de référence pour juger \texttt{SourceCode}.\\ + +Les sous-sections suivantes résument les critiques émises sur \texttt{SourceCode}. Certaines remarques suggéraient des améliorations et corrections. Avec le temps qui nous restait, nous avons essayé de les prendre en compte pour rendre l'utilisation de la plateforme un peu plus immersive et plus fonctionnelle. Vous retrouverez alors un "\textbf{(corrigé)}" quand nous avons pu prendre en considération la remarque. + +\subsection*{Bibliothèque} + +\begin{itemize} + \item Système de recherche intuitif, rapide et riche en filtres. + \item La barre de recherche n'est pas bien placée, car elle laisse penser que c'est pour lancer une recherche sur tout le domaine du site web. \textbf{(corrigé)} + \item Dans la création de favoris depuis le panneau, au lieu de cliquer sur OK, appuyer sur enter pour valider le nom du nouveau favori. \textbf{(corrigé)} + \item Ajouter quelques tags + titre de recherche plutôt que juste le nom du favori dans la partie onglet "favoris". \textbf{(corrigé)} + \item Recherche : Gestion des fautes de frappe et/ou recherche approximative. (1) + \item Le texte de la barre de recherche est trop petit, et en bleu trop clair. \textbf{(corrigé)} + \item Un peu difficile de scroller dans la liste des tags (jusqu'à 3 scrollbars). \textbf{(corrigé)} +\end{itemize} + +Nos observations : + +\begin{enumerate} + \item La gestion des fautes de frappe ou recherche approximative est une fonctionnalité qui pourrait être très utile pour la bibliothèque (le but étant de faciliter la recherche au maximum). +\end{enumerate} + +\subsection*{Favoris} + +\begin{itemize} + \item Pas nécessaire d'avoir obligatoirement un tag pour créer un favori. \textbf{(corrigé)} + \item Quand on crée un favori puis le modifie, difficile de se souvenir de quelle catégorie appartient le tag qu'on a sélectionné précédemment : soit renommer le tag, soit créer un moyen de savoir de quelle catégorie le tag appartient. (1) +\end{itemize} + +Nos observations : + +\begin{enumerate} + \item Lors de l'édition d'un favori ou d'une \gls{resinfo}, les \glspl{tag} ajoutés sont affichés dans une section du formulaire en mode pêle-mêle (sans les catégories auxquels ils se rapportent). Le seul moyen de vérifier la catégorie à laquelle un \gls{tag} appartient est de naviguer dans le panneau à onglets. Nous discuterons des futures améliorations possibles dans le chapitre \ref{chapter:pourAllerPlusLoin}. +\end{enumerate} + + +\subsection*{Création de \glspl{resinfo}} + +\begin{itemize} + \item Frustrant de ne pas pouvoir créer un bloc de code directement depuis plusieurs lignes sélectionnées. (1) + \item Ajouter un pour l'édition du code. \textbf{(corrigé)} + \item Possibilité d'agrandir la boîte d'édition de texte. (2) + \item Un peu difficile d'utiliser le panneau des tags (c'est une première) (3) +\end{itemize} + +Nos observations : + +\begin{enumerate} + \item Actuellement, il faut d'abord créer un bloc de code puis copier-coller le code que l'on veut formater dedans. La \gls{library} d'édition de texte que nous utilisons (Tiptap) ne gère pas nativement ce qui a été soulevé dans la remarque. En revanche, cette même \gls{library} est extensible et autorise la modification/l'ajout de fonctionnalités de manière aisée. Il est donc tout à fait envisageable de corriger le tir dans une prochaine mise à jour de l'application. + \item Certaines personnes se plaignaient que la boîte d'édition était trop petite (ou trop grande). Dans son état actuel, \texttt{SourceCode} n'est pas responsive, et dans la perspective où elle le serait, ce problème sera certainement réglé pour tout écran. + \item Comme cela a déjà été soulevé dans la section concernant la bibliothèque, le panneau des \glspl{tag} est un peu lourd à l'utilisation. Il y avait jusqu'à 3 scrollbars pour naviguer dans le panneau, ce qui diminuait considérablement l'accessibilité. Nous avons donc corrigé ce comportement en faisant en sorte d'afficher une seule scrollbar, avec un accès plus clair à la barre de recherche sous chaque \glspl{tagCat}. +\end{enumerate} + +\subsubsection*{Esthétique et ergonomie} + +\begin{itemize} + \item Très chouette. + \item Le bouton retour dans le header est un peu perturbant, car on ne le remarque pas avant d'avoir vraiment pris en main le site. \textbf{(corrigé)} + \item Un dark mode (1) +\end{itemize} + +Nos observations : + +\begin{enumerate} + \item Le dark mode n'est pas une fonctionnalité nécessaire à la plateforme, mais elle pourrait ajouter un plus côté attractivité. +\end{enumerate} + +\subsection*{Points forts} + +\begin{itemize} + \item Ergonomique et riche en filtres de recherche. + \item Très complète. + \item Très utile, s'il y a une grande communauté et qu'il y a beaucoup d'exercices. (1) + \item La sélection dynamique est top (pour la recherche). + \item Design, visuel, fluidité. + \item L'idée de rassembler toutes les ressources informatiques au même endroit semble pertinente et utile. + \item Le système de tags (utilisé correctement par les utilisateurs) semble flexible et potentiellement très utile. + \item Visuellement attrayant. +\end{itemize} + +Nos observations : + +\begin{enumerate} + \item La grande communauté dépendra surtout de la qualité de l'application et de son utilité. Les exercices que nous avons utilisés pour la séance de validation étaient importés à partir de quatre cours hébergés sur la plateforme \textit{INGInious}. Nous pouvons donc aisément fournir plus de contenu rien qu'en important tous les cours stockés sur cette même plateforme avec l'avantage d'un système de \glspl{tag} plus avancé. +\end{enumerate} + +\subsection*{Points faibles} + +\begin{itemize} + \item S'il y a peu d'exercices, la plateforme aura peu de sens. (1) + \item S'il y a trop d'exercices, les administrateurs pourraient peut-être demeurer débordés pour la modération. (2) + \item L'application est très complète, mais le souci vient justement de cela : la courbe d'apprentissage est assez pentue, mais après cela, l'outil deviendrait très puissant (difficulté pour les professeurs un peu moins "tech savvy"). (3) +\end{itemize} + +Nos observations : + +\begin{enumerate} + \item \texttt{SourceCode} pourra très rapidement posséder une riche bibliothèque de \glspl{resinfo} rien qu'avec les exercices stockés sur la plateforme \textit{INGInious}. Avec la promotion de la plateforme auprès d'autres institutions scolaires, \texttt{SourceCode} pourrait alors prétendre à une popularité certaine dans le monde des ressources partagées. Il s'agit alors de savoir vendre son produit avec les bons arguments... + \item Nous n'avions pas pensé à cela pour le prototype. Nous voulions d'abord créer un système cohérent et fonctionnel au niveau de la gestion des \glspl{resinfo} et \glspl{tag}. Les différents statuts attribuables à ces mêmes \glspl{resinfo} et \glspl{tag} jouent déjà un rôle majeur dans la gestion (ex: trier les \glspl{resinfo} non valides ou en attente de validation ...). En termes d'améliorations, nous pourrions automatiser le processus de validation afin que les administrateurs ne soient pas débordés (cf. chapitre \ref{chapter:pourAllerPlusLoin}). + \item C'est un point intéressant pour nous. \texttt{SourceCode} est une application qui tente de faciliter le plus possible la recherche et la gestion de \glspl{resinfo} (système de filtres, historique, favoris ...). Malheureusement, ajouter une pléthore de fonctionnalités peut aussi devenir une barrière à l'utilisation, car l'utilisateur doit d'abord apprendre à les maîtriser. Une des premières solutions que nous avons mises en place était la création d'une section tutoriel sur la plateforme, mais cela n'est qu'une solution de contournement. Une autre idée serait de prévoir une interface en fonction du public ciblé (débutant, "tech savvy" ...). +\end{enumerate} + +\subsection*{Que pouvons-nous faire pour améliorer l'application ?} + +\begin{itemize} + \item Il s'agit d'un produit bien abouti ! Vous êtes à un stade où ça sera les utilisateurs de la plateforme qui vous feront des feedbacks sur ce qui serait bien à ajouter/améliorer. + \item Clarifier l'interface. L'UI représente cependant beaucoup de travail. Vous avez priorisé les bonnes choses. + \item Améliorer l'agencement des menus. (1) + \item Une fonction mot de passe oublié pour les utilisateurs. (2) +\end{itemize} + +Nos observations : + +\begin{enumerate} + \item Dans les retours d'utilisation, les testeurs étaient perturbés avec le menu principal et le panneau latéral. La confusion venait du fait que le menu principal comportait des chevrons, ce qui laissait penser à une structure à plusieurs niveaux (listes). Le panneau de filtres contenait aussi ces mêmes chevrons, alors nous avons supprimé ces derniers sur le menu principal pour enlever cette confusion. + \item C'est une fonctionnalité importante pour ce genre d'application, mais nous n'avons pas pris le temps de l'intégrer. Nous l'ajoutons dans le chapitre \ref{chapter:pourAllerPlusLoin}. +\end{enumerate} + +\subsection*{Que manquerait-il pour que cette plateforme ne soit plus un prototype en termes de fonctionnalités ?} + +\begin{itemize} + \item Je ne vous rejoins pas sur l'idée que Source Code en est au stade de "prototype". Ça ressemble bien plus à un produit fini, en une première version, qui peut être concernée par d'éventuelles mises à jour par la suite. + \item Pas grand-chose, et beaucoup à la fois. Il s'agit du lent travail de lisser les bugs et les surprises que peuvent rencontrer les utilisateurs. + \item Peut-être la complétion automatique dans la barre de recherche + \item Pour moi c'est plus qu'un prototype au stade où elle en est. S'il fallait vraiment une fonctionnalité en plus, ça serait de pouvoir ajouter ses solutions sur la plateforme. (1) + \item Une manière d'interagir entre les étudiants et les "créateurs d'exercices" ? Histoire de pouvoir au moins poser des questions et ne pas être aussi détachés. (2) +\end{itemize} + +Nos observations : + +\begin{enumerate} + \item \texttt{SourceCode} n'est pas prévu pour résoudre des exercices depuis la plateforme. À ce stade-ci, on peut la considérer comme un référenceur de \glspl{resinfo} qui faciliterait la recherche de ressources particulière avec un système de recherche complet. Dans une perspective future, \texttt{SourceCode} pourrait avoir son propre correcteur d'exercices si la ressource nécessite une résolution. Dans ce cas, cela profiterait aux étudiants pour s'évaluer. + \item Certaines plateformes comme Hackerrank ou Coderbyte ont prévu une section forum pour chaque exercice/challenge. C'est une fonctionnalité intéressante, mais elle va de pair avec le point précédent. +\end{enumerate} + +\subsection*{Pensez-vous que cette application ait un réel impact dans le monde des ressources partagées ?} + +\begin{itemize} + \item Oui (de la part de la majorité) + \item Il faudrait juste voir comment gérer l'accès entre votre plateforme et celles qui permettent la correction des exercices (Inginious). Par exemple un moyen de linker votre plateforme avec les autres, pour qu'en un clic on arrive directement sur l'exercice inginious en étant déjà connecté dessus. + \item Sans être intégrée à une plateforme automatisée de correction de code, et sans une gestion de parcours et de lien entre les exercices, sans doute pas beaucoup. Elle sera limitée à une utilisation par les enseignants pour créer leurs propres cours. (1) +\end{itemize} + +Nos observations : + +\begin{enumerate} + \item La plateforme est d'abord créée pour l'équipe pédagogique, prônant le partage de \glspl{resinfo} dans une bibliothèque triée par \glspl{tag}. Une prochaine étape serait alors d'intégrer un système de correction d'exercices directement depuis la plateforme. Nous n'avions pas eu le temps d'intégrer une telle fonctionnalité, mais cela pourrait définitivement être utile aux étudiants. +\end{enumerate} + +\subsection*{Utiliseriez-vous cette plateforme ? Quelle serait votre activité principale ?} + +\begin{itemize} + \item Je pense que pour des professeurs, cela peut être très utile pour trouver et donner des exercices à des étudiants (ou d'avoir des idées). + \item Trouver des idées d'exercices pour compléter mes cours. + \item Je pense que ça s'appliquerait surtout au domaine éducatif. + \item Oui, en tant que professeur/enseignant, pourvu que les solutions soient mises à dispositions. +\end{itemize} + +\subsection*{Conclusion} + +Cette séance de validation a globalement été positive et instructive. Le message d'une plateforme de partage de \glspl{resinfo} à destination d'une équipe pédagogique semble être acquis par la majorité. +Nous avons appris que la plateforme dispose d'un design et d'une ergonomie satisfaisants. Il faut néanmoins y apporter quelques mises à jour pour rendre le projet mature, notamment au niveau de l'ergonomie. +Certaines des fonctionnalités mentionnées dans les critiques ont pu être intégrées à \texttt{SourceCode} pour l'améliorer le plus possible. Pour celles qui n'ont pas été ajoutées, nous les avons référencées dans le chapitre \ref{chapter:pourAllerPlusLoin}. diff --git a/sections/chapters/analyseCritique/validationInterne.tex b/sections/chapters/analyseCritique/validationInterne.tex new file mode 100644 index 0000000..f97e5ba --- /dev/null +++ b/sections/chapters/analyseCritique/validationInterne.tex @@ -0,0 +1,57 @@ +\section{Métriques} +\label{section:codeMetrics} + +Cette section traduit notre implication sur ce projet. +Pour ce faire, nous avons repris des statistiques des répertoires GitHub du \gls{frontend} et de l'\gls{api}. +Une notion intéressante à prendre en compte sera le graphe d'activité pour les deux répertoires, car nous avons tenté de respecter le planning imposé (cf. \ref{pic:ganttChart}). + +\subsection{Statistiques} + +\begin{itemize}[nosep,noitemsep,topsep=0pt,partopsep=0pt,after=\vspace*{2pt}] + \item Nombre de lignes de code (\gls{frontend} + \gls{backend}) : 21685 + 10158 = 31843 + \begin{itemize} + \item Le nombre de lignes de code a été calculé en retirant tous les fichiers générés automatiquement (ex : npm install qui va créer un fichier \textit{package-lock.json}). + \end{itemize} + \item Nombre de pull requests résolues (\gls{frontend} + \gls{backend}) : 49 + 79 = 128 + \begin{itemize} + \item Nous avons beaucoup utilisé les pull requests pour garder une trace des mises à jour importantes effectuées. Cela a été extrêmement utile avec l'intégration continue en \textit{Docker} pour rapidement tester l'application avec l'une d'elles (cf. section \ref{section:docker}). + \end{itemize} + \item Nombre de tests fonctionnels (\gls{backend}) : 48 + \begin{itemize} + \item Plutôt que de tester individuellement chaque partie de l'application (comme le ferait des tests + unitaires\footnote{ + \href{https://fr.wikipedia.org/wiki/Test\_unitaire}{https://fr.wikipedia.org/wiki/Test\_unitaire} + }), nous avons choisi cette approche, de type boîte noire (c.-à-d. sans connaitre le code source), qui consiste à vérifier si les spécifications (cf. section \ref{section:analyseFonctionnelle}) sont respectées par le logiciel ainsi développé. + Cette vérification est notamment très utile en \gls{ci_cd} (cf. figure \ref{fig:GithubActionsExample}). + \end{itemize} + \item Couverture du code (\gls{backend}) : 100\% + \begin{itemize} + \item Il s'agit de mesurer la proportion du code source exécutée lors de tests : nous considérons ici la définition générale, car celle-ci peut se décliner sous d'autres formes\footnote{ + \href{https://fr.wikipedia.org/wiki/Couverture\_de\_code}{https://fr.wikipedia.org/wiki/Couverture\_de\_code}, \cite{concept_cfg}, ... + }. + Veuillez noter que nous avons exclu du calcul quelques lignes difficiles, voire impossible à tester afin d'avoir un taux plus réaliste. + \end{itemize} +\end{itemize} + +\subsection{Graphe d'activité} + +\texttt{SourceCode} a connu un développement plus ou moins constant durant l'année académique 2019-2020. Étant donné que le \gls{frontend} et le \gls{backend} sont intimement liés, vous pourrez constater sur le graphe \ref{figure:frontendActivity} et \ref{figure:backendActivity} que la forte activité de l'un compense l'activité au ralenti de l'autre répertoire. + +\begin{figure}[H] + \includegraphics[width=\textwidth,height=0.3\textheight,keepaspectratio]{images/analyseCritique/graph_frontend.png} + \centering + \caption{GitHub : graphe d'activité (frontend)} + \label{figure:frontendActivity} +\end{figure} + +Les fonctionnalités les plus importantes comme la recherche dans la bibliothèque, la consultation d'une \gls{fiche} et la gestion des \glspl{resinfo} ont été intégrées durant la période d'octobre à janvier, après quoi nous avons amélioré l'expérience d'utilisation de l'application en appliquant quelques mises à jour et corrections de bugs jusqu'au mois de mai.\\ + +\begin{figure}[H] + \includegraphics[width=\textwidth,height=0.3\textheight,keepaspectratio]{images/analyseCritique/graph_backend.png} + \centering + \caption{GitHub : graphe d'activité (backend)} + \label{figure:backendActivity} +\end{figure} + + +Globalement, nous avons respecté le planning \ref{pic:ganttChart} que nous nous sommes imposé. Nous avons cependant effectué une dernière mise à jour prenant en compte un maximum des remarques relatées en section \ref{section:validationExterne}, car nous voulions prouver que \texttt{SourceCode} est capable de s'adapter aux besoins des utilisateurs. diff --git a/sections/chapters/solution/choixTechno/index.tex b/sections/chapters/solution/choixTechno/index.tex index 5acc7a7..65ffc3b 100644 --- a/sections/chapters/solution/choixTechno/index.tex +++ b/sections/chapters/solution/choixTechno/index.tex @@ -391,6 +391,6 @@ \subsubsubsection{\Glspl{library} pour le \gls{backend}} \Gls{library} permettant de réaliser des assertions en HTTP de manière plus aisée. Une de ses particularités est d'être "framework-agnostic", ce qui permet d'utiliser le framework de test de notre choix, dont notamment celui de Facebook : Jest\footnote{ \url{https://jestjs.io/} -}. (nous reviendrons sur la dimension des tests de manière plus approfondie dans la section \ref{section:codeCoverage})\\ +}. (nous reviendrons sur la dimension des tests de manière plus approfondie dans la section \ref{section:codeMetrics})\\ \pagebreak \ No newline at end of file From 44147bcfc664755e1e831f0e8e4e063d06083e05 Mon Sep 17 00:00:00 2001 From: jy95 Date: Fri, 22 May 2020 03:00:57 +0200 Subject: [PATCH 04/10] wip: rewrite toc for readability --- sections/chapters/conclusion/index.tex | 1 + structure.tex | 14 ++++++++++++-- 2 files changed, 13 insertions(+), 2 deletions(-) create mode 100644 sections/chapters/conclusion/index.tex diff --git a/sections/chapters/conclusion/index.tex b/sections/chapters/conclusion/index.tex new file mode 100644 index 0000000..3533e97 --- /dev/null +++ b/sections/chapters/conclusion/index.tex @@ -0,0 +1 @@ +\chapter{Conclusion} \ No newline at end of file diff --git a/structure.tex b/structure.tex index 6806fef..7c0b1ae 100644 --- a/structure.tex +++ b/structure.tex @@ -37,11 +37,18 @@ \import{sections/chapters/problematique/}{index} \import{sections/chapters/approche/}{index} \import{sections/chapters/cahierDesCharges/}{index} + +% On limite ici la toc aux sections +\setcustomtocdepth{1} + \import{sections/chapters/solution/}{index} \import{sections/chapters/analyseCritique/}{index} -\import{sections/chapters/pourAllerPlusLoin/}{index} -\chapter{Conclusion} +% On limite ici la toc aux chapitres +\setcustomtocdepth{0} + +\import{sections/chapters/pourAllerPlusLoin/}{index} +\import{sections/chapters/conclusion/}{index} % Stop partial lists \stoplist[main]{lof}% stops main list of figures @@ -64,6 +71,9 @@ \chapter{Conclusion} % Pour marquer la séparation avec les extraits de code des annexes \appendixFix +% Ici on va limiter les annexes au niveau 1 (cad les sections) +\setcustomtocdepth{1} + % Annexes % Explications : https://texfaq.org/FAQ-appendix \begin{appendices} From 5e02aa0983f4f8ca5309272891591ab2e6fdd564 Mon Sep 17 00:00:00 2001 From: jy95 Date: Fri, 22 May 2020 03:29:02 +0200 Subject: [PATCH 05/10] fix: issue with formatting / hyperref links with added entries in toc --- commonPreamble.sty | 13 +++++++++---- sections/tablesAnnexes.tex | 3 +++ sections/tablesMain.tex | 3 +++ structure.tex | 1 - 4 files changed, 15 insertions(+), 5 deletions(-) diff --git a/commonPreamble.sty b/commonPreamble.sty index 3063ccd..6faa9be 100644 --- a/commonPreamble.sty +++ b/commonPreamble.sty @@ -299,10 +299,15 @@ literate=% \makeatletter \newcommand\beautifultableofcontents{% - \begin{multicols}{\multicolumntoc}[\section*{\contentsname - \@mkboth{% - \MakeUppercase\contentsname}{\MakeUppercase\contentsname}}]% - \@starttoc{toc}% + \begin{multicols}{\multicolumntoc} + [\chapter*{ + \contentsname + \@mkboth{% + \MakeUppercase\contentsname} + {\MakeUppercase\contentsname} + } + ]% + \@starttoc{toc}% \end{multicols}% } diff --git a/sections/tablesAnnexes.tex b/sections/tablesAnnexes.tex index d4ec585..0cb94a5 100644 --- a/sections/tablesAnnexes.tex +++ b/sections/tablesAnnexes.tex @@ -1,3 +1,6 @@ +\clearpage +\phantomsection +\addcontentsline{toc}{chapter}{Table des illustrations des annexes} % On imprime une table des figures / tables pour mieux naviguer ici \begingroup \let\clearpage\relax diff --git a/sections/tablesMain.tex b/sections/tablesMain.tex index e9fdb64..cb31244 100644 --- a/sections/tablesMain.tex +++ b/sections/tablesMain.tex @@ -1,3 +1,6 @@ +\clearpage +\phantomsection +\addcontentsline{toc}{chapter}{Table des illustrations} \begingroup \let\clearpage\relax % prints main list of figures diff --git a/structure.tex b/structure.tex index 7c0b1ae..93f55c4 100644 --- a/structure.tex +++ b/structure.tex @@ -86,6 +86,5 @@ % Tables des figures / tables / extraits de code [PRINCIPALE] \import{sections/}{tablesMain} -\pagebreak % Tables des figures / tables / extraits de code [ANNEXES] \import{sections/}{tablesAnnexes} \ No newline at end of file From 71c9687b5732d56f0fb5e5df92cae36a5b0c3d5c Mon Sep 17 00:00:00 2001 From: jy95 Date: Fri, 22 May 2020 11:14:13 +0200 Subject: [PATCH 06/10] wip: refactoring (TODO) --- .../analyseCritique/validationInterne.tex | 18 ++- sections/chapters/solution/api/index.tex | 117 +----------------- sections/chapters/solution/divers/index.tex | 115 +++++++++++++++++ sections/chapters/solution/index.tex | 4 +- sections/preambule.tex | 3 +- 5 files changed, 133 insertions(+), 124 deletions(-) create mode 100644 sections/chapters/solution/divers/index.tex diff --git a/sections/chapters/analyseCritique/validationInterne.tex b/sections/chapters/analyseCritique/validationInterne.tex index f97e5ba..15293df 100644 --- a/sections/chapters/analyseCritique/validationInterne.tex +++ b/sections/chapters/analyseCritique/validationInterne.tex @@ -9,15 +9,15 @@ \subsection{Statistiques} \begin{itemize}[nosep,noitemsep,topsep=0pt,partopsep=0pt,after=\vspace*{2pt}] \item Nombre de lignes de code (\gls{frontend} + \gls{backend}) : 21685 + 10158 = 31843 - \begin{itemize} + \begin{itemize}[nosep,noitemsep,topsep=0pt,partopsep=0pt,after=\vspace*{2pt}] \item Le nombre de lignes de code a été calculé en retirant tous les fichiers générés automatiquement (ex : npm install qui va créer un fichier \textit{package-lock.json}). \end{itemize} \item Nombre de pull requests résolues (\gls{frontend} + \gls{backend}) : 49 + 79 = 128 - \begin{itemize} + \begin{itemize}[nosep,noitemsep,topsep=0pt,partopsep=0pt,after=\vspace*{2pt}] \item Nous avons beaucoup utilisé les pull requests pour garder une trace des mises à jour importantes effectuées. Cela a été extrêmement utile avec l'intégration continue en \textit{Docker} pour rapidement tester l'application avec l'une d'elles (cf. section \ref{section:docker}). \end{itemize} \item Nombre de tests fonctionnels (\gls{backend}) : 48 - \begin{itemize} + \begin{itemize}[nosep,noitemsep,topsep=0pt,partopsep=0pt,after=\vspace*{2pt}] \item Plutôt que de tester individuellement chaque partie de l'application (comme le ferait des tests unitaires\footnote{ \href{https://fr.wikipedia.org/wiki/Test\_unitaire}{https://fr.wikipedia.org/wiki/Test\_unitaire} @@ -25,12 +25,18 @@ \subsection{Statistiques} Cette vérification est notamment très utile en \gls{ci_cd} (cf. figure \ref{fig:GithubActionsExample}). \end{itemize} \item Couverture du code (\gls{backend}) : 100\% - \begin{itemize} - \item Il s'agit de mesurer la proportion du code source exécutée lors de tests : nous considérons ici la définition générale, car celle-ci peut se décliner sous d'autres formes\footnote{ + \begin{itemize}[nosep,noitemsep,topsep=0pt,partopsep=0pt,after=\vspace*{2pt}] + \item Il s'agit de mesurer la proportion du code source exécutée lors de tests\footnote{ + Vous pouvez consulter les résultats depuis \href{https://codecov.io/gh/SourceCodeOER/sourcecode\_api/branch/master}{https://codecov.io/gh/SourceCodeOER/sourcecode\_api/branch/master} + } : nous considérons ici la définition générale, car celle-ci peut se décliner sous d'autres formes\footnote{ \href{https://fr.wikipedia.org/wiki/Couverture\_de\_code}{https://fr.wikipedia.org/wiki/Couverture\_de\_code}, \cite{concept_cfg}, ... }. Veuillez noter que nous avons exclu du calcul quelques lignes difficiles, voire impossible à tester afin d'avoir un taux plus réaliste. - \end{itemize} + \end{itemize} + \item Note Codacy de qualité du code (\gls{backend} + \gls{frontend}) : A / B + \begin{itemize}[nosep,noitemsep,topsep=0pt,partopsep=0pt,after=\vspace*{2pt}] + \item + \end{itemize} \end{itemize} \subsection{Graphe d'activité} diff --git a/sections/chapters/solution/api/index.tex b/sections/chapters/solution/api/index.tex index 49f327b..e412a12 100644 --- a/sections/chapters/solution/api/index.tex +++ b/sections/chapters/solution/api/index.tex @@ -137,119 +137,4 @@ \subsubsection{Recherche par \glspl{tag}} \end{tabular} \caption{Solution technique de la recherche par \glspl{tag}} \label{tab:fichesWithTagImpl} -\end{table} - -\pagebreak -\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, quelle que 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 Docker Hub (\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.15\textheight,keepaspectratio]{images/serveur/dockerHub.PNG} - \centering - \caption{Docker Hub - 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} \ No newline at end of file +\end{table} \ No newline at end of file diff --git a/sections/chapters/solution/divers/index.tex b/sections/chapters/solution/divers/index.tex new file mode 100644 index 0000000..f1b6d00 --- /dev/null +++ b/sections/chapters/solution/divers/index.tex @@ -0,0 +1,115 @@ +\pagebreak +\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, quelle que 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 Docker Hub (\url{https://hub.docker.com/}) + et générées sur base de fichiers Dockerfile, présents dans chaque repository Github de code. + 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.15\textheight,keepaspectratio]{images/serveur/dockerHub.PNG} + \centering + \caption{Docker Hub - 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} + \item Compiler les sources \textbf{LaTeX} du mémoire pour générer un \textbf{PDF} +\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} \ No newline at end of file diff --git a/sections/chapters/solution/index.tex b/sections/chapters/solution/index.tex index 5b81da2..3654a1c 100644 --- a/sections/chapters/solution/index.tex +++ b/sections/chapters/solution/index.tex @@ -8,4 +8,6 @@ \chapter{Solution} \import{sections/chapters/solution/client/}{index} % Partie API + Divers -\import{sections/chapters/solution/api/}{index} \ No newline at end of file +\import{sections/chapters/solution/api/}{index} + +\import{sections/chapters/solution/divers/}{index} \ No newline at end of file diff --git a/sections/preambule.tex b/sections/preambule.tex index 23299a9..c905a0d 100644 --- a/sections/preambule.tex +++ b/sections/preambule.tex @@ -17,7 +17,8 @@ \chapter*{Préambule} \item \href{https://github.com/SourceCodeOER/sourcecode-front}{https://github.com/SourceCodeOER/sourcecode-front} pour la partie \gls{frontend} \item \href{https://github.com/SourceCodeOER/sourcecode\_api}{https://github.com/SourceCodeOER/sourcecode\_api} pour la partie \Gls{api} \item \href{https://github.com/SourceCodeOER/cli}{https://github.com/SourceCodeOER/cli} pour la partie \Gls{cli} - \item \href{https://github.com/SourceCodeOER/miscellaneous}{https://github.com/SourceCodeOER/miscellaneous} pour notre base de données de test (pour la validation de notre solution par de vrais utilisateurs) et nos fichiers de configuration paramétrée pour déployer l'ensemble de notre prototype en mode production/démonstration avec \href{https://docs.docker.com/compose/}{Docker Compose} et ce n'importe où comme à l'UCLouvain. + \item \href{https://github.com/SourceCodeOER/miscellaneous}{https://github.com/SourceCodeOER/miscellaneous} pour notre base de données de test (pour la validation de notre solution par de vrais utilisateurs) et nos fichiers de configuration pour déployer l'ensemble de notre prototype en mode production/démonstration avec \href{https://docs.docker.com/compose/}{Docker Compose} et ce n'importe où comme à l'UCLouvain. + \item \href{https://github.com/SourceCodeOER/thesis}{https://github.com/SourceCodeOER/thesis} pour les sources du présent mémoire \end{itemize} Notre solution/prototype est hébergée par l'UCLouvain en mode démonstration à l'adresse suivante : \href{http://tfe-dewit-yakoub.info.ucl.ac.be/}{http://tfe-dewit-yakoub.info.ucl.ac.be/} \\ From 3a2be42f5ef2dcea6bb20c542fb10989dbd771e8 Mon Sep 17 00:00:00 2001 From: jy95 Date: Fri, 22 May 2020 12:11:38 +0200 Subject: [PATCH 07/10] wip : refactoring (TODO) --- .../chapters/analyseCritique/validationInterne.tex | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/sections/chapters/analyseCritique/validationInterne.tex b/sections/chapters/analyseCritique/validationInterne.tex index 15293df..d15c646 100644 --- a/sections/chapters/analyseCritique/validationInterne.tex +++ b/sections/chapters/analyseCritique/validationInterne.tex @@ -3,7 +3,6 @@ \section{Métriques} Cette section traduit notre implication sur ce projet. Pour ce faire, nous avons repris des statistiques des répertoires GitHub du \gls{frontend} et de l'\gls{api}. -Une notion intéressante à prendre en compte sera le graphe d'activité pour les deux répertoires, car nous avons tenté de respecter le planning imposé (cf. \ref{pic:ganttChart}). \subsection{Statistiques} @@ -14,7 +13,7 @@ \subsection{Statistiques} \end{itemize} \item Nombre de pull requests résolues (\gls{frontend} + \gls{backend}) : 49 + 79 = 128 \begin{itemize}[nosep,noitemsep,topsep=0pt,partopsep=0pt,after=\vspace*{2pt}] - \item Nous avons beaucoup utilisé les pull requests pour garder une trace des mises à jour importantes effectuées. Cela a été extrêmement utile avec l'intégration continue en \textit{Docker} pour rapidement tester l'application avec l'une d'elles (cf. section \ref{section:docker}). + \item Nous avons beaucoup utilisé les pull requests pour garder une trace des mises à jour importantes effectuées. Cela a été extrêmement utile avec l'intégration continue en \textit{Docker} pour tester rapidement l'application avec l'une d'elles (cf. section \ref{section:docker}). \end{itemize} \item Nombre de tests fonctionnels (\gls{backend}) : 48 \begin{itemize}[nosep,noitemsep,topsep=0pt,partopsep=0pt,after=\vspace*{2pt}] @@ -33,9 +32,12 @@ \subsection{Statistiques} }. Veuillez noter que nous avons exclu du calcul quelques lignes difficiles, voire impossible à tester afin d'avoir un taux plus réaliste. \end{itemize} - \item Note Codacy de qualité du code (\gls{backend} + \gls{frontend}) : A / B + \item Note Codacy\footnote{ + \href{https://www.codacy.com/}{https://www.codacy.com/} + } de qualité du code (\gls{backend} / \gls{frontend}) : A / B \begin{itemize}[nosep,noitemsep,topsep=0pt,partopsep=0pt,after=\vspace*{2pt}] - \item + \item Il s'agit d'une plateforme qui analyse le code source pour produire diverses mesures (pourcentage de code dupliqué, complexité du code ...). + Elle vérifie / analyse également la lisibilité du code en fonction de conventions de codage courantes. \end{itemize} \end{itemize} From 441a52e9ee95cb29c9069dfc20092b5d89be4153 Mon Sep 17 00:00:00 2001 From: jy95 Date: Fri, 22 May 2020 13:03:46 +0200 Subject: [PATCH 08/10] wip: refactoring (TODO) --- sections/chapters/analyseCritique/index.tex | 2 +- sections/chapters/analyseCritique/validationInterne.tex | 9 +++++---- 2 files changed, 6 insertions(+), 5 deletions(-) diff --git a/sections/chapters/analyseCritique/index.tex b/sections/chapters/analyseCritique/index.tex index 56bf34f..5c514de 100644 --- a/sections/chapters/analyseCritique/index.tex +++ b/sections/chapters/analyseCritique/index.tex @@ -9,7 +9,7 @@ \chapter{Analyse critique} \section{Conclusion} -À travers ce chapitre, nous avons pu constater si \texttt{SourceCode} est un projet qui tient la route à son stade de développement.\\ +À travers ce chapitre, nous avons pu constater si ce projet tient la route à son stade actuel.\\ La séance de validation nous a été extrêmement bénéfique, car les remarques étaient constructives. Cela nous conforte dans l'idée que notre plateforme a des chances de devenir mature et utilisable par une communauté. Quoi qu'il en soit, notre projet est \textit{Open Source} et pourra donc toujours évoluer avec sa communauté. C'est d'ailleurs notre plus grand souhait pour cette plateforme.\\ diff --git a/sections/chapters/analyseCritique/validationInterne.tex b/sections/chapters/analyseCritique/validationInterne.tex index d15c646..4804d65 100644 --- a/sections/chapters/analyseCritique/validationInterne.tex +++ b/sections/chapters/analyseCritique/validationInterne.tex @@ -32,12 +32,13 @@ \subsection{Statistiques} }. Veuillez noter que nous avons exclu du calcul quelques lignes difficiles, voire impossible à tester afin d'avoir un taux plus réaliste. \end{itemize} - \item Note Codacy\footnote{ - \href{https://www.codacy.com/}{https://www.codacy.com/} - } de qualité du code (\gls{backend} / \gls{frontend}) : A / B + \item Note Codacy de qualité du code (\gls{backend} / \gls{frontend}) : A / B \begin{itemize}[nosep,noitemsep,topsep=0pt,partopsep=0pt,after=\vspace*{2pt}] \item Il s'agit d'une plateforme qui analyse le code source pour produire diverses mesures (pourcentage de code dupliqué, complexité du code ...). - Elle vérifie / analyse également la lisibilité du code en fonction de conventions de codage courantes. + Elle vérifie / analyse également la lisibilité du code en fonction de conventions de codage courantes\footnote{ + Vous pouvez consulter ces rapports sur \href{https://app.codacy.com/gh/SourceCodeOER/sourcecode\_api/dashboard}{https://app.codacy.com/gh/SourceCodeOER/sourcecode\_api/dashboard} et + \href{https://app.codacy.com/gh/SourceCodeOER/sourcecode-front/dashboard}{https://app.codacy.com/gh/SourceCodeOER/sourcecode-front/dashboard} + }. \end{itemize} \end{itemize} From fa912ab560069172b9bb382ca0f888f585a6e4cc Mon Sep 17 00:00:00 2001 From: jy95 Date: Fri, 22 May 2020 16:11:06 +0200 Subject: [PATCH 09/10] wip: refactor ccl --- sections/chapters/analyseCritique/index.tex | 10 ++++++++-- 1 file changed, 8 insertions(+), 2 deletions(-) diff --git a/sections/chapters/analyseCritique/index.tex b/sections/chapters/analyseCritique/index.tex index 5c514de..6ba83ed 100644 --- a/sections/chapters/analyseCritique/index.tex +++ b/sections/chapters/analyseCritique/index.tex @@ -11,6 +11,12 @@ \section{Conclusion} À travers ce chapitre, nous avons pu constater si ce projet tient la route à son stade actuel.\\ -La séance de validation nous a été extrêmement bénéfique, car les remarques étaient constructives. Cela nous conforte dans l'idée que notre plateforme a des chances de devenir mature et utilisable par une communauté. Quoi qu'il en soit, notre projet est \textit{Open Source} et pourra donc toujours évoluer avec sa communauté. C'est d'ailleurs notre plus grand souhait pour cette plateforme.\\ +La séance de validation nous a été extrêmement bénéfique, car les remarques étaient constructives. +Cela nous conforte dans l'idée que notre plateforme a des chances de devenir mature et utilisable par une communauté. +Quoi qu'il en soit, notre projet est \textit{Open Source} et pourra donc toujours évoluer avec sa communauté. +C'est d'ailleurs notre plus grand souhait pour cette plateforme. +La qualité technique du code est assurée par les différentes métriques énoncés précédemment (cf. section \ref{section:codeMetrics}).\\ -Au niveau du planning, il semble que nous ayons respecté ce qui était initialement mis en place au vu de nos graphes d'activité. Nous avons tenté d'être constants tout au long du projet, car ce dernier demande beaucoup d'investissement en matière de recherche et de développement. Il semblerait que cela ait porté ses fruits. \ No newline at end of file +Au niveau du planning, il semble que nous ayons respecté ce qui était initialement mis en place au vu de nos graphes d'activité. +Nous avons tenté d'être constants tout au long du projet, car ce dernier demande beaucoup d'investissement en matière de recherche et de développement. +Il semblerait que cela ait porté ses fruits. \ No newline at end of file From 397a306ecc1f36974df1545a8be042c9edbd06be Mon Sep 17 00:00:00 2001 From: jy95 Date: Fri, 22 May 2020 16:21:32 +0200 Subject: [PATCH 10/10] wip: antidote 10 --- sections/chapters/analyseCritique/validationInterne.tex | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/sections/chapters/analyseCritique/validationInterne.tex b/sections/chapters/analyseCritique/validationInterne.tex index 4804d65..4bfd968 100644 --- a/sections/chapters/analyseCritique/validationInterne.tex +++ b/sections/chapters/analyseCritique/validationInterne.tex @@ -30,7 +30,7 @@ \subsection{Statistiques} } : nous considérons ici la définition générale, car celle-ci peut se décliner sous d'autres formes\footnote{ \href{https://fr.wikipedia.org/wiki/Couverture\_de\_code}{https://fr.wikipedia.org/wiki/Couverture\_de\_code}, \cite{concept_cfg}, ... }. - Veuillez noter que nous avons exclu du calcul quelques lignes difficiles, voire impossible à tester afin d'avoir un taux plus réaliste. + Veuillez noter que nous avons exclu du calcul quelques lignes difficiles, voire impossibles à tester afin d'avoir un taux plus réaliste. \end{itemize} \item Note Codacy de qualité du code (\gls{backend} / \gls{frontend}) : A / B \begin{itemize}[nosep,noitemsep,topsep=0pt,partopsep=0pt,after=\vspace*{2pt}]