1. Gestion de projet et documentation#

L’idée derrière ce premier module est de construire un site web et se familiariser à l’utilisation du logiciel de gestion de version “Git”. Dans ce module, ainsi que dans les suivants, les étapes qui ont été suivies pour réaliser les objectifs des modules seront documentés. Afin d’y voir plus clair concernant les outils qui vous seront utiles pour ce module, je vous invite à lire le document mis à notre disposition à cet effet. Cliquez ici pour y accéder

Prise en main de Git#

Téléchargement de Git#

La première étape consiste à installer l’outil de gestion de version Git. Pour cela, rien de plus simple. Il suffit de se rendre sur le site web de Git et de cliquer sur la version de Git qui correspond à votre système d’exploitation. Pour ma part, j’utilise Windows donc j’ai téléchargé la version la plus récente de Git pour Windows.

Configuration de Git#

Après avoir téléchargé Git et suivi les instructions d’installation par défaut de l’installateur, il est temps de configurer Git sur votre ordinateur. Pour ce faire, il faudra ouvrir Git Bash et entrer les commandes suivantes :

git config --global user.name "your_username"

et

git config --global user.email "your_email_address@example.com"

Où il faudra remplacer les éléments entre guillemets respectivement par votre nom d’utilisateur et l’adresse mail associée au compte GitLab que vous aurez précédemment créé.

Génération d’une paire de clés SSH#

Cette étape peut sembler étrange, voire inutile, mais Gitlab utilise le protocole de communication sécurisée SSH pour communiquer des informations entre les fichiers qui se trouvent localement sur votre PC et le serveur distant destiné à les héberger. Comme de nombreuses applications se voulant sécurisées, Git utilise un principe de cryptographie qui fait usage d’une paire de clés (une clé privée et une clé publique). La clé publique peut etre partagée entre différentes machines alors que la clé privée doit demeurer uniquement en votre possession.

Afin de générer ces clés qui assureront la sécurité de vos flux de données entre votre machine locale et votre serveur GitLab, il suffit d’ouvrir un terminal, pour ma part j’utilise Git Bash (qui s’installe quand vous installez Git) et de taper la commande suivante :

ssh-keygen

Vos clés seront alors générées et devront etre stockées dans un fichier quelque part sur votre ordinateur. Un emplacement de sauvegarde du fichier créé vous sera proposé par défaut. Vous pouvez choisir de le garder ou de choisir un autre emplacement pour sauvegarder ce fichier en introduisant le chemin du dossier désiré. Il vous sera ensuite proposé de choisir un mot de passe (je vous conseille de ne pas en entrer et de confirmer avec la touche Enter car ce mot de passe vous sera par la suite systématiquement demandé pour effectuer des commandes Git, ce qui est loin d’etre pratique).

Une fois ces étapes terminées, rendez-vous à l’emplacement où le fichier contenant les clés a été enregistré sur votre ordinateur. Vous aurez peut-etre besoin d’afficher les dossiers cachés via l’onglet affichage de votre explorateur de fichier (dans le cas de Windows) car par défaut, le fichier sera stocké dans un dossier caché sur votre ordinateur (dossier dont le nom commence par “.”). Ouvrez le fichier et copié la clé générée, il s’agit d’une longue chaine de caractères commençant par “ssh-rsa”. Rendez-vous ensuite sur votre navigateur web, dans les paramètres utilisateurs de votre compte GitLab et cherchez l’onglet “Clé SSH”. Cet onglet devrait apparaitre à gauche après avoir cliqué sur votre photo de profil puis sur “modifier le profil”. Collez votre clé à l’emplacement prévu à cet effet sous “Ajouter une clé SSH” dans le cadre “Clé” et confirmez.

Copie locale du repository (Git Clone)#

Maintenant que la communication entre votre compte GitLab et votre machine a été établie et authentifiée, il est temps de commencer à travailler avec Git. La première étape consiste à créer une copie locale de votre repository (répertoire de fichiers), dans le cas présent, le dossier contenant votre site web. Pour le moment ce dossier se situe uniquement sur GitLab. Afin de pouvoir travailler dessus depuis votre ordinateur, rendez-vous sur votre compte GitLab et sélectionnez le projet à votre nom dans votre liste de projets. Vous devriez voir apparaitre un bouton “Clone” en bleu. Cliquez dessus et copiez l’URL qui apparait en dessous de “Cloner avec SSH”.

Ouvrez ensuite Git Bash depuis un dossier vide dans lequel vous voudrez accueillir une copie de votre repository. Sur Windows ceci peut etre fait en vous rendant à l’emplacement désiré, en faisant un clic droit et en sélectionnant “Open Git Bash here”. Tapez ensuite la commande suivante :

git clone git@gitlab.com:fablab-ulb/enseignements/2023-2024/fabzero-experiments/students/mohamed.ouamar.git

Évidemment, vous devrez entrer le lien de votre propre repository après “git clone”, ici j’ai marqué le lien du mien pour l’exemple. Une fois le clonage terminé, vous pourrez modifier localement les fichiers de votre site web via l’éditeur de texte de votre choix. J’utilise personnellement l’environnement de développement Intellij Idea car c’est un outil puissant qui intègre des fonctionnalités Git permettant d’éviter de taper manuellement les instructions Git habituelles. Il permet également de visualiser le résultat des fichiers Markdown édités en temps réel. Les étudiants de l’ULB peuvent obtenir gratuitement une licence pour ce produit grâce à leur adresse mai ULB.

Les commandes Git principales sont les suivantes :

• Git pull: Cette commande permet de récupérer la dernière version du projet disponible sur le GitLab
• Git add -A: Cette commande permet d’ajouter toutes les modifications effectuées pour le commit
• Git commit -m “COMMENT TO DESCRIBE THE INTENTION OF THE COMMIT”: Cette commande permet de soumettre (commit) les changements effectués localement créant ainsi une nouvelle version locale du projet et d’accompagner ces modifications d’un commentaire décrivant les modifications effectuées
• Git push: Cette commande permet de soumettre les modifications effectuées sur la version locale au serveur distant en vue de mettre à jour la version distante du projet pour y inclure les modifications effectuées sur la version locale du projet

Modification du projet#

Pour modifier les pages des modules du site web, rien de plus facile. Il suffit dans un premier temps de modifier les fichiers “.md” correspondant au module souhaité. Les fichiers “.md” sont des fichiers de type “Markdown”, il s’agit d’un type de fichier simple et très utile d’utilisation pour ajouter du texte, inclure des images, des vidéos, des tables, etc. dans son site web. Afin d’effectuer ces différentes actions, il faut respecter la syntaxe appropriée. Personnellement j’ai ajouté cette page à mes favoris. Elle reprend de façon très succincte les quelques éléments de syntaxe qui vous seront utiles pour modifier vos fichiers Markdown.

Une fois que les modifications voulues ont été faites sur vos fichiers, il suffit d’effectuer un Git commit pour enregistrer localement les modifications faites dans une nouvelle version de votre code. Vous pouvez régulièrement faire des Git commit en indiquant en commentaire les modifications que vous avez apportées. Cela vous aidera à visualiser votre cheminement dans la rédaction de votre documentation. Pour mettre à jour votre site web distant, il faudra effectuer un Git push. Gardez bien en tete que sans Git push rien n’est envoyé sur votre site web distant ! Depuis Intellij Idea, vous pouvez très facilement effectuer les commandes Git nécessaires via l’onglet “Git” situé en haut de la fenêtre.

Gestion des images et de l’espace de stockage#

Afin d’ajouter des images à votre site web (comme des captures d’écran ou des photos de vos exploits pendant la réalisation des modules) vous devrez placer ces images dans un dossier à l’intérieur de votre projet. Personnellement j’ai créé des sous-dossiers dans le dossier “images” situé sous docs/fabzero-modules/images. J’ai créé un dossier pour les images de chacun des modules.

Utiliser des images permet de mieux comprendre les choses que seulement à travers du texte donc n’hésitez pas à en utiliser pour illustrer vos propos. Cependant, les images prennent en général beaucoup de place par rapport aux fichiers textes et votre espace de stockage est limité. Gardez aussi en tete qu’au plus vos fichiers sont volumineux au plus il faudra de temps pour les transmettre à votre site web distant. Pour palier à ce problème, vous pouvez toujours compresser vos images avant de les rajouter à votre site. Pour compresser mes images, j’utilise l’outil ImageMagick que vous pouvez télécharger ici

Personnellement, je vous conseille de mettre toutes les images dont vous voulez réduire la taille dans un meme dossier (typiquement les images de plus de 1Mo), d’ouvrir Git bash dans ce dossier après avoir téléchargé ImageMagick et d’entrer les commandes suivantes : mogrify -format jpg *.png puis mogrify -quality 60% *.jpg.

La première commande aura comme effet de convertir toutes les images “.png” du dossier en format “jpg”. La deuxième commande permettra de compresser toutes les images jpg du dossier à 60% de leur qualité initiale. Évidemment vos images pourraient ne pas etre initialement au format png ou vous pourriez avoir envie de compresser d’autres formats que le jpg, pour ce faire, changez simplement les mentions “jpg” ou “png” des commandes par le format souhaité. Je vous renvoie vers la page mise à disposition pour ce module, elle contient plus d’exemples d’utilisation d’ImageMagick.

Importation des issues#

Pour chacun des modules que vous documenterez, il y a une issue associée. Le système d’issue vous sera utile pour vérifier si vous avez bien documenté tous les aspects essentiels en lien avec le module sur lequel vous avez travaillé. Vous aurez à chaque fois une checklist pour vous aider à déterminer les éléments que vous avez inclus dans votre documentation. Les issues présentent également une section où vous pouvez indiquer ce que vous avez appris durant le module en question. Pour utiliser ces issues, vous devrez les importer sur Gitlab. Pour ce faire, rien de plus simple. Rendez-vous sur la page de votre projet et sélectionner dans la barre latérale gauche “Programmation” puis “Tickets”. Vous vous retrouverez alors sur la page consacrée aux tickets de votre projet.

Si vous n’avez pas encore importé d’issues, vous verrez un bouton “Importer des tickets” au centre de la page. Cliquez dessus puis cliquez sur “Importer un fichier CSV”. Sélectionnez ensuite “choisir un fichier” et indiquez l’emplacement du fichier CSV correspondant au module voulu (que vous aurez au préalable téléchargé sur votre ordinateur). Une fois le fichier sélectionné, cliquez sur “Importer des tickets” pour importer votre ticket. Vous y aurez ensuite accès depuis l’onglet “Tickets” sur la barre latérale gauche de Gitlab quand vous naviguerez dans le repository de votre projet.

Si vous avez déjà importé des issues, vous devrez alors vous rendre sur la meme page que précédemment, mais celle-ci présentera alors les issues déjà ouvertes. Il faudra cette fois-ci cliquer en haut à droite sur les trois points pour retrouver l’option d’importer un fichier CSV. Cliquez sur cette option et à partir de là, suivez la meme démarche que celle utilisée pour importer vos premières issues comme expliqué ci-dessus.

Principes de gestion de projet#

Plusieurs principes de gestion de projet ont été passés en revue durant le cours. Parmi eux, ceux que je compte mettre en place dans la réalisation de ces modules sont les suivants :

• Supply-side Time Management : Pour la documentation des modules, je déterminerai d’abord les moments que je peux consacrer à la documentation et je diviserai le travail que j’ai à effectuer en plus petites parties plus ou moins longues que j’assignerai à des créneaux plus ou moins longs dans mes disponibilités. La gestion du temps est cruciale dans la réalisation de vos projets et je vous conseille vivement de ne pas sous-estimer le temps dont vous aurez besoin pour documenter vos modules. Je vous déconseille fortement de laisser le travail s’accumuler et de procrastiner et de travailler continuellement sur la documentation.
• Spiral Development : Compléter rapidement une tache dans son entièreté une première fois malgré le manque de qualité vaut toujours mieux que de s’attarder à sa complétion pour que tout soit parfait. Avoir une version complète, mais imparfaite rapidement laisse le temps de repasser dessus pour l’améliorer et permet de rapidement voir ce qui doit etre amélioré et d’avoir quelque chose à rendre au cas où.
• Parallel Development : Essayer de travailler sur un maximum de sous-taches en meme temps permet d’avoir une qualité uniforme sur l’ensemble de vos taches alors que travailler de façon séquentielle vous poussera souvent à avoir une bonne qualité sur les taches commencées en premier et à vous précipiter sur les taches effectuées à la fin.
• Triage : On ne peut pas tout faire ou tout documenter donc il faut se fixer des priorités. Avoir avec soi sa check-list et les objectifs d’un module pendant la réalisation de la documentation aide à savoir si on a couvert les éléments les plus importants dans notre documentation.