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.

Gestion du contenu

Edition de contenu déjà existant

Il suffit de modifier le document au format markdown que l’on souhaite éditer. Pour cela, on peut le faire via la forge git ou bien via le dépôt git.

Production de nouveau 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.

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 créer un nouveau contenu avec la commande: hugo new docs/mon_nouveau_document.mddocs/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.

Avec la forge git

Sur votre propre branche, ou bien sur la branche partagée “preview”, créer un nouveau fichier au format .md, et y copier le contenu du fichier archetypale adapté présent dans le repertoire archetypes/ du dépôt git.

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.

Sur la branche “preview”

Après un commit sur la branche partagée “preview”, 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.

Installation de Hugo

Pour installer Hugo on peut suivre ce guide.

Procéssus de contribution

  1. Si vous avez de petites modifications, vous pouvez les réaliser directement sur la branche partagée “preview”.
  2. Si vous avez de plus grosses modifications à réaliser, qui pourrait impacter d’autres contributeurs sur la branche “preview”, ou si vous souhaitez ne pas être importuné par d’autres contributeurs, nous vous encourageons à créer votre propre branche temporaire.
  3. Lorsque vos modifications sont matures, vous pouvez éventuellement fusionner votre branche dans la branche “preview”.
  4. Lorsque vos modifications sur la branche “preview” vous donne satisfaction, vous pouvez proposer aux administrateurs de l’AMIPO d’intégrer vos modifications via une “merge request”. Vos modifications seront alors consultées et inspectées et éventuellement fusionner dans la branche “master”.

Branche personnelle

Chaque contributeur peut créer une ou plusieurs nouvelles branches pour proposer des modifications. Une fois que le contributeur juge ses modifications matures, il peut proposer de fusionner (merge request) sa branche dans une autre branche, typiquement “preview” ou “master”.

Branche “preview”

La branche “preview” est protégée, vous ne pouvez pas écraser cette branche. C’est une branche de travail partagée. Chaque commit sur cette branche déclenche la génération du site web avec les nouveaux fichiers sources, puis déploit ce site web sur l’environnement “preview”.

Branche “master”

La branche “master” est également protégée. Cette branche est maintenue par les co-administrateurs de l’AMIPO. Cette branche contient les fichiers sources qui serivent à générer le site web de l’environnement de Production. Chaque commit sur cette branche déclenche la génération du site web avec les nouveaux fichiers sources. Ce site web est alors disponible en télechargement au format zip.

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.

Test

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.

Preview

Si vous réalisez un commit sur cette branche partagée, alors le pipeline tentera de construire le site web et de le déployer sur un environnement “preview” accessible ici.

Master

Lorsqu’un commit est réalisé 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.