Principe⌗

Le site web de l’AMIPO est construit à partir d’une arborescence de fichier texte formatés en “markdown”. Tous ces fichiers textes sont consultables et modifiables dans le repertoire content/ du projet disponible sur le dépôt git. Le logiciel Hugo permet de générer un site “statique” à partir du contenu présent dans ce répertoire.

Procédure d’ajout ou modification de contenu⌗

Les contenus sont par défaut produit en mode brouillon draft: true dans le chapeau du fichier. Les contenus en mode brouillon ne sont pas publiés sur le site. Il faut désactiver le mode brouillon en précisant draft: false.

En ligne de commande (CLI) sur votre machine personelle⌗

Verifier que le paramétrage de votre client git est correcte:

$ git config --global user.name "John Doe"
$ git config --global user.email johndoe@example.com

Ces informations sont utilisés pour suivre qui réalise les modifications des documents du site.

Créez une nouvelle branche⌗

Choisissez un nom de branche adapté à votre modification. Ci après, on symbolise le nom de cette branche avec le texte MA_NOUVELLE_BRANCHE.

Dans votre dépot du site :

git checkout master
git pull origin master
git checkout -b MA_NOUVELLE_BRANCHE

Pour ajouter un nouveau document⌗

Avec le logiciel Hugo⌗

Avec le logiciel hugo installié sur sa machine (cf Installation de Hugo), depuis la racine du dépôt git, créez un nouveau contenu avec la commande: hugo new docs/mon_nouveau_document.md où docs/mon_nouveau_document.md est le nom du fichier qui contiendra ce nouveau contenu. Dans notre exemple, ce contenu sera de la documentation car présent dans le repertoire docs.

  • Ajoutez une nouvelle documentation : hugo new docs/mon_nouveau_document.md
  • Ajoutez un nouvel article sur le blog : hugo new posts/mon_nouvel_article.md
Sans le logiciel Hugo⌗

Copiez un fichier archetypale adapté présent dans le repertoire archetypes/ dans le bon sous repertoire content/ du dépôt git.

  • Ajoutez une nouvelle documentation : cp archetyps/docs.md content/docs/mon_nouveau_document.md
  • Ajoutez un nouvel article sur le blog : cp archetyps/posts.md content/posts/mon_nouvel_article.md

Pour modifier un document⌗

Tous les documents sont présents dans le repertoire content/, classés hierarchiquement dans différents repertoires :

  • content/docs : La documentation de l’AMIPO
  • content/posts : Les articles de blog de l’AMIPO Editez le fichier au format markdown (.md)

Commitez et pousser vos modifications⌗

Pour commiter (proposer) vos modifications voici la liste des commandes :

git add .
git commit -m "MON_MESSAGE_EXPLIQUANT_MON_TRAVAIL"
git push origin MA_NOUVELLE_BRANCHE

Avec la forge git⌗

La forge git est ici. Tous les documents au format markdown (.md) sont présents dans le repertoire content/

Créez une nouvelle branche⌗

Choisissez un nom de branche adapté à votre modification. Ci après, on symbolise le nom de cette branche avec le texte MA_NOUVELLE_BRANCHE.

Naviguez dans la liste des branches sur la forge : Dépôt > Branches et créez une nouvelle branche à l’aide du bouton. Entrez le nom de votre branche est spécifiez la branche master comme branche d’origine.

Pour ajouter un nouveau document⌗

Verifiez que vous êtes bien sur votre branche, le nom de votre branche doit apparaitre dans l’URL de votre navigateur web. Copiez le contenu d’un des fichiers archetypales présents dans le dossier archetypes/. Pour info :

  • archetypes/docs.md : Archetype de documentation de l’AMIPO
  • content/posts.md : Archetype d’un article de blog de l’AMIPO

Dans le bon sous-repertoire du repertoire content/ de votre branche, créez un nouveau fichier nommé mon_nouveau_document.md dans lequel vous collerez le contenu de l’archetype précedement copié.

Pour modifier un document⌗

Tous les documents sont présents dans le repertoire content/, classés hierarchiquement dans différents repertoires :

  • content/docs : La documentation de l’AMIPO
  • content/posts : Les articles de blog de l’AMIPO Ouvrez le fichier à modifier (un fichier .md) dans votre branche grace à l’interface web de la forge git, vour pouvez cliquer sur le bouton pour ouvrir l’éditeur, soit :
  • Edit
  • Web IDE

Commitez vos modifications⌗

Une fois vos modifications dans le fichier terminé, utilisez l’interface web pour entrer un message décrivant vos modifications (le Commit message) et cliquez sur le bouton de validation de vos modifications : Commit changes.

Proposez la fusion de vos modifications⌗

Lorsque toutes les modifications que vous souhaitiez effectuer sont terminées et commitées, vous pouvez créer une Merge request depuis l’interface web de la forge. Pour cela, cliquez sur le menu “Merge Requests” à gauche de l’interface.

  1. Dans ce menu, si votre branche est toujours sélectionnée, vous pouvez cliquer sur le bouton “Create merge request”.
  2. Si votre branche n’est pas sélectionnée, cliquez sur le bouton “New merge request” et utilisez l’interface pour sélectionner votre branche comme source et la branche master comme cible et enfin cliquez sur le bouton “Compare branches and continue”.

Enfin, choisissez soigneusement un titre et une description résumant toutes les modifications présentes sur votre branche, puis cliquez sur le bouton “Submit merge request”.

Vos modifications sont désormais proposez, un mainteneur du projet pourra entamer des discussions avec vous pour vous guider, améliorer ou rejeter votre proposition.

Visualisation⌗

Avec le logiciel Hugo⌗

Avec le logiciel hugo installié sur sa machine (cf Installation de Hugo), depuis la racine du dépôt git, on peut lancer la génération du site web avec la commande: hugo server.

En “preview” sur les pages gitlab⌗

Après un commit sur votre branche, le site web est généré par le pipeline de la forge git. Le travail du pipeline est indiqué par un badge “pipeline” clicable situé sur la page d'accueil du projet. Une fois le pipeline déroulé, la prévisualisation du site web est disponible ici.

En “test” après la fusion de votre branche sur la branche master⌗

Une fois vos propostion accépté et votre branche fusioné sur la branche master, le pipeline construi le site web de “production” et le déploie sur l’environnement de test https://test.amipo.fr/

Installation de Hugo⌗

Pour installer Hugo on peut suivre ce guide.

Pipeline d’intégration & de déploiement⌗

Les pipeline de d’intégration et de déploiement sont configurés dans le fichier .gitlab-ci.yml à la racine du dépôt git.

Proposition⌗

Lorsque la forge git reçoit un commit sur une branche (quelque soit la branche hormis master et preview), un pipeline de test lancé et permet de valider la syntaxe des fichiers sur le projet. Si le pipeline échoue, cela veut dire que le logiciel Hugo à rencontré des problèmes pour construire de le site web avec les sources que vous avez modifiés. Vous devriez recevoir un email pour vous signifier ce fait. Une fois le pipeline terminé, le site web construit sera déployé sur un environnement “preview” accessible ici.

Master⌗

Lorsqu’une proposition est fusionnée sur cette branche, le pipeline tente de construire le site web à déstination de la production. Si le pipeline termine avec succès, alors le site web static généré est disponible au format zip en téléchargement. Le site web de production sera alors automatiquement déployé sur l’environnement de test https://test.amipo.fr/ dans la minute qui suit.

Pour le dépolyer en production, il faut se logguer sur le serveur puis

sudo su
cd /var/amipo-admin-code/
./promote_en_prod.sh /var/www/test/html