Travail pratique

ID : A07-TP05.2

But du TP

Prendre en main l'IDE IntelliJ IDEA
Se familiariser avec l'utilisation du système de gestion de versions Git et la plateforme de gestion de projets GitLab
Réaliser collaborativement un site web avec MkDocs et Git
Déployer un site web supplémentaire sur nginx (Linux) en production

Travail à réaliser

Prettier

Installez et configurez Prettier dans IntelliJ IDEA.
- Configurez Prettier dans IntelliJ IDEA, pour formater les fichiers Markdown (.md).

Organisation

Formez 3 groupes de 3 personnes, puis choisissez un des thèmes suivants (un thème par groupe) :
- Topic A : header, main et footer
- Topic B : article, section et aside
- Topic C : nav, div et span
Dans chaque groupe, chaque membre prend en charge une balise du thème et reçoit le numéro de cette balise (1, 2 ou 3) :

Membre Topic A Topic B Topic C

1 header article nav

2 main section div

3 footer aside span

Chaque ligne du tableau réunit trois personnes de groupes différents : elles contribueront aux balises les unes des autres (voir Etape 3).

Les membres 1, qui n'ont pas de rôle dans le workflow Git de leur thème, se chargent en plus de trois tâches communes à toute la classe :

ID	Tâche commune	Détail
A1	Activer les extensions Markdown (`feature/markdown-extensions`)	Préparation du projet
B1	Publier la première release (liste de l'équipe et extensions Markdown)	Préparation du projet
C1	Créer la branche `feature/examples`, la fusionner dans `develop` et publier sa release	Etape 5

Inscrivez votre nom dans le fichier TEAMS.md, à la racine du projet GitLab du TP, directement dans la branche develop. Ce fichier reprend le tableau ci-dessus, avec une ligne par balise.
1. Mettez à jour votre branche develop locale :
```
git checkout develop
git fetch
git rebase origin/develop
```
2. Sur la ligne de votre balise, remplacez _à compléter_ par votre prénom et votre nom. Ne modifiez aucune autre ligne.
3. Contrôlez votre modification avec git diff, faites un commit (ex. Add <Prénom Nom> to the team list), puis push la branche develop sur origin.
A la fin, les 9 lignes de TEAMS.md sont complétées sur origin/develop, et git shortlog -sn origin/develop -- TEAMS.md (après un git fetch) affiche un commit de chacune des 9 personnes.

9 personnes, un seul fichier, une seule branche

Tout le monde modifie le même fichier dans la même branche : seul le premier push passe directement. Les suivants sont refusés par origin (message rejected … fetch first), car votre branche locale ne contient pas les commits poussés entre-temps par les autres.

Coordonnez-vous

Passez un par un, dans l'ordre du fichier (A1, A2, A3, B1… C3).
Annoncez à la classe quand vous commencez, puis quand votre push est passé : c'est le signal pour la personne suivante.
Faites le fetch et le rebase juste avant de modifier le fichier, pas dix minutes avant.

Si votre push est refusé malgré tout

Récupérez les commits des autres : git fetch
Rejouez votre commit par-dessus : git rebase origin/develop
En cas de conflit, ouvrez TEAMS.md (ou la fenêtre de résolution des conflits d'IntelliJ IDEA), gardez les noms déjà inscrits et le vôtre, puis terminez le rebase : git add TEAMS.md et git rebase --continue
Recommencez le push.

🚨 N'utilisez jamais git push --force : vous effaceriez de origin les noms inscrits par les autres.

Commandes Git de ce TP

Le travail se fait avec IntelliJ IDEA ou en ligne de commande, au choix. Les commandes ci-dessous sont nouvelles : chacune a son équivalent dans IntelliJ IDEA (menu Git et fenêtre Git, onglet Log).

Commande	Description
`git checkout <branche>`	Bascule sur une branche (crée la branche locale si elle n'existe que sur `origin`)
`git diff`	Affiche les modifications pas encore ajoutées à l'index
`git diff --staged`	Affiche les modifications ajoutées à l'index, qui feront partie du prochain commit
`git diff <branche1>...<branche2>`	Affiche ce que `<branche2>` a modifié depuis qu'elle s'est séparée de `<branche1>`
`git log --oneline --graph --all`	Affiche l'historique de toutes les branches sous forme de graphe
`git shortlog -sn <plage>`	Compte les commits par auteur
`git show <commit>`	Affiche le message et les modifications d'un commit
`git blame <fichier>`	Indique, pour chaque ligne d'un fichier, le commit et l'auteur qui l'a modifiée en dernier
`git stash` / `git stash pop`	Met de côté des modifications non commitées, puis les réapplique

Sources :

Préparation du projet

Avant de commencer les thèmes, les extensions Markdown utilisées aux étapes suivantes sont activées dans une branche feature, puis une première release publie cette fonctionnalité et la liste de l'équipe complétée.

Extensions Markdown (A1)

Pendant les inscriptions dans TEAMS.md, créez la branche feature/markdown-extensions depuis la branche develop à jour.
Dans mkdocs.yml, activez les extensions Highlight, InlineHilite, Snippets et SuperFences, comme indiqué dans la section Configuration de la documentation de Material for MkDocs.
- Highlight colore le code des blocs de code (étapes 2 et 3).
- Snippets insère le contenu d'un fichier dans une page (étape 5).
Vérifiez avec mkdocs serve qu'un bloc de code ```html s'affiche avec la coloration syntaxique (sans commiter ce test), puis faites un commit de mkdocs.yml.
Attendez que les 9 noms soient inscrits dans TEAMS.md (annonce de C3).
- Attendre la fin des inscriptions évite que votre push soit refusé parce que d'autres poussent la branche develop en même temps.
Mettez à jour votre branche develop locale, qui ne contient pas encore les inscriptions des autres :
```
git checkout develop
git fetch
git rebase origin/develop
```
- Contrôlez que les 9 noms sont présents dans TEAMS.md.
- Inutile de mettre à jour la branche feature/markdown-extensions : elle ne modifie que mkdocs.yml, et le merge réunit les deux historiques.
Faites un « merge commit » de la branche feature/markdown-extensions dans la branche develop, push la branche develop et supprimez la branche feature.
Annoncez à la classe que les extensions sont dans develop : c'est le signal pour B1.

Première release (B1)

Une fois les extensions fusionnées dans develop, mettez à jour votre branche develop locale (mêmes commandes qu'au point 5 ci-dessus), créez la branche release avec le bon numéro de version et mettez à jour CHANGELOG.md avec toutes les modifications depuis la version 0.3.0.
Fusionnez la branche release dans main puis dans develop, comme pour les thèmes (voir Workflow Git).
Annoncez à la classe que la release est terminée : c'est le signal pour créer les branches des thèmes (étape 1).

Etape 1 : branche et squelette

Dans le projet GitLab du TP, avec IntelliJ IDEA :

Le membre 1 du groupe crée une branche feature/topic-x (remplacez x par la lettre de votre thème) depuis la branche develop à jour, une fois la première release publiée : la branche contient ainsi les extensions Markdown.

Il crée le fichier docs/topic-x.md avec le squelette ci-dessous (exemple pour le Topic A), sans autre contenu :

# Topic A : header, main et footer

## `header`

### Description

### Utilisation

### Exemples

### Compatibilité

## `main`

### Description

### Utilisation

### Exemples

### Compatibilité

## `footer`

### Description

### Utilisation

### Exemples

### Compatibilité

Il effectue un commit du squelette avec un message de commit clair, puis push la branche feature/topic-x sur origin.
Les deux autres membres font un fetch puis un checkout de la branche :
```
git fetch
git checkout feature/topic-x
```

🚨 Les squelettes des trois thèmes doivent être sur origin avant la fin de la séance du lundi 26 octobre : les autres groupes en ont besoin pour l'étape 3.

Etape 2 : rédaction de sa balise

Le but de l'exercice est que chaque personne rédige son contenu individuellement de son côté et le mette à disposition des autres avec des push de la branche feature/topic-x sur origin.

Dans la section de votre balise, rédigez les sous-chapitres Description, Utilisation et Compatibilité.
- Vous pouvez utiliser les documentations en ligne pour vous aider, telles que MDN Web Docs - HTML.
- Pour la compatibilité, affichez sous forme d'image le tableau de compatibilité de MDN Web Docs, enregistrée dans docs/img/ avec un nom qui contient votre balise (ex. docs/img/header-compatibility.png), et indiquez la source sous l'image.
Dans le sous-chapitre Exemples de votre balise, ajoutez un premier exemple d'utilisation, sous un titre de niveau 4 (####) qui le décrit en quelques mots.
- Indiquez le langage de chaque bloc de code (ex. ```html) : l'extension Highlight, activée lors de la préparation, se charge de la coloration syntaxique.
Il doit y avoir au moins un commit par sous-chapitre.
Avant chaque commit, contrôlez ce que vous allez enregistrer :
- git diff : modifications pas encore ajoutées à l'index ;
- git diff --staged : modifications qui feront partie du commit.
Le commit ne doit contenir que des modifications de votre propre section (et votre image).
Les trois membres modifient le même fichier : si votre push est refusé, faites un fetch puis un rebase sur origin/feature/topic-x, résolvez les éventuels conflits et recommencez le push.

Etape 3 : tour des thèmes

Chaque personne ajoute un exemple dans chacun des deux autres thèmes, pour la balise qui se trouve sur la même ligne qu'elle dans le tableau de l'organisation.

Exemple : la personne responsable de header (Topic A, membre 1) ajoute un exemple pour article (Topic B) et un exemple pour nav (Topic C).

Pour chacun des deux autres thèmes :

Mettez de côté votre travail en cours : faites un commit, ou utilisez git stash si votre travail n'est pas prêt à être commité.
- Git refuse le checkout si des modifications non commitées entrent en conflit avec l'autre branche.
Récupérez la branche de l'autre groupe et basculez dessus :
```
git fetch
git checkout feature/topic-y
```
- Si la branche existe déjà dans votre dépôt local (deuxième passage), le checkout ne la met pas à jour : faites ensuite un git rebase origin/feature/topic-y.
Ajoutez votre exemple à la fin du sous-chapitre Exemples de la balise concernée, sous un titre de niveau 4 (####).
- Ne modifiez pas le contenu rédigé par les autres : si vous y voyez une erreur, signalez-la à son auteur.
Contrôlez vos modifications (git diff, git diff --staged), faites un commit, puis push la branche sur origin.
- Deux personnes ajoutent un exemple à la même balise : un conflit est possible. Faites un fetch, un rebase, résolvez le conflit en conservant les deux exemples, puis recommencez le push.
Revenez sur votre branche (git checkout feature/topic-x) et, si besoin, récupérez votre travail mis de côté (git stash pop).

A la fin de l'étape, chaque balise a trois exemples : un de son auteur et un de chacun des deux autres groupes.

Etape 4 : explorer l'historique et comparer

Chaque membre du groupe réalise ces contrôles sur la branche de son thème, après un fetch, une fois que les contributions des autres groupes sont arrivées.

Visualisez l'historique de toutes les branches : git log --oneline --graph --all (ou l'onglet Log de la fenêtre Git d'IntelliJ IDEA).
Vérifiez que les 9 personnes de la classe ont contribué à votre thème :
```
git shortlog -sn origin/develop..origin/feature/topic-x
```
Affichez tout ce que votre thème ajoute par rapport à develop :
```
git diff origin/develop...origin/feature/topic-x
```
Seuls docs/topic-x.md et les images du thème doivent apparaître. Toute autre modification (ex. mkdocs.yml) doit être identifiée et corrigée par un nouveau commit de son auteur.
Identifiez l'auteur de chaque exemple de votre balise : git blame docs/topic-x.md (ou clic droit dans la marge de l'éditeur, puis Annotate with Git Blame).
- Affichez le commit correspondant avec git show <commit>.
Relisez les exemples ajoutés à votre balise. Si un exemple doit être corrigé, demandez-le à son auteur : c'est lui qui fait le commit de correction, sur votre branche.

Etape 5 : page HTML et merge request

Chaque personne réalise une petite page HTML qui utilise les 9 balises des trois thèmes, l'intègre au site MkDocs et la soumet à la validation d'une autre personne avec une merge request (MR) GitLab. La personne qui valide votre MR est indiquée dans la colonne « Valide la MR de » du fichier TEAMS.md.

Une merge request est une demande de fusion d'une branche dans une autre, faite sur GitLab : elle permet à une autre personne de relire et de commenter les modifications avant qu'elles soient fusionnées.

Source : GitLab Docs - Merge requests

Les MR ne sont pas fusionnées dans develop, mais dans une branche d'intégration feature/examples. Les 9 pages forment une seule fonctionnalité : elle est fusionnée dans develop et publiée dans une seule release, une fois toutes les MR fusionnées. Les releases des thèmes, faites depuis develop pendant ce temps, ne contiennent ainsi aucune page d'exemple inachevée.

Branche d'intégration (C1)

Depuis la branche develop à jour, après la première release, créez la branche feature/examples.
Créez le fichier docs/examples.md avec un titre, puis une section par identifiant de TEAMS.md, de A1 à C3, qui contient uniquement _à compléter_ :
```
# Exemples HTML

## A1

_à compléter_

## A2

_à compléter_

…

## C3

_à compléter_
```
Faites un commit, push la branche feature/examples sur origin et annoncez-le à la classe.

Auteur de la page

Récupérez la branche d'intégration (git fetch, puis git checkout feature/examples) et créez depuis celle-ci une branche feature/example-<id>, où <id> est votre identifiant dans TEAMS.md en minuscules (ex. feature/example-a1).
Créez le fichier docs/examples/<id>.html (ex. docs/examples/a1.html) : une page HTML complète sur l'un de vos hobbys ou l'une de vos passions.
- Les 9 balises header, main, footer, article, section, aside, nav, div et span sont utilisées selon leur sens (voir les pages des thèmes).
- La page respecte la structure d'une page HTML, la hiérarchie des titres (document outline) et les règles du Code style.
- Le Nu Html Checker n'affiche aucune erreur.
Dans le fichier docs/examples.md, remplacez _à compléter_ sous le titre de votre identifiant par un lien vers votre page et son code source, inclus avec l'extension Snippets :
```
[Afficher la page](examples/a1.html)

```html
--8<-- "docs/examples/a1.html"
```
```
- Ne modifiez aucune autre section de docs/examples.md.
- Vérifiez le rendu avec mkdocs serve : le lien ouvre votre page et le code source s'affiche avec la coloration syntaxique.
Faites au moins deux commits (la page HTML, puis son intégration dans docs/examples.md), puis push la branche sur origin.
Sur GitLab, créez une merge request de feature/example-<id> vers feature/examples (champ Target branch, et non develop) et indiquez la personne qui la valide dans le champ Reviewer.
Si la personne, qui valide, demande des corrections, faites-les dans de nouveaux commits sur la même branche, puis push : la merge request se met à jour automatiquement.

Personne qui valide

Récupérez la branche de la MR et basculez dessus (git fetch, puis git checkout feature/example-<id>), et vérifiez le rendu avec mkdocs serve.
Contrôlez les points suivants :
- Les 9 balises sont présentes et utilisées selon leur sens
- La structure de la page, la hiérarchie des titres et le code style sont respectés
- Le Nu Html Checker n'affiche aucune erreur (vérifiez-le vous-même)
- Seuls docs/examples/<id>.html et la section de l'auteur dans docs/examples.md sont modifiés (onglet Changes de la MR)
- Les messages de commit respectent les règles vues en cours
Laissez au moins un commentaire dans la MR (correction demandée, question ou remarque), en précisant la ligne concernée.
Une fois les corrections faites, approuvez la MR (Approve), puis fusionnez-la (Merge) avec la méthode « merge commit », en cochant la suppression de la branche source et sans regrouper les commits (squash).
Revenez sur votre branche de travail (git checkout).

Intégration et release (C1)

Une fois les 9 MR fusionnées :

Mettez à jour votre branche feature/examples locale (git fetch, puis git rebase origin/feature/examples) et vérifiez avec mkdocs serve que les 9 pages et leur code source s'affichent.
Mettez à jour votre branche develop locale (git checkout develop, git fetch, git rebase origin/develop), puis faites un « merge commit » de la branche feature/examples dans la branche develop.
Ajoutez sur la page principale index.md, sous la liste des thèmes, un lien vers la page des exemples, et faites un commit de cette modification dans la branche develop.
push la branche develop, puis supprimez la branche feature/examples sur origin.
Publiez une release, avec la même procédure que pour les thèmes (voir Workflow Git).

Workflow Git

Utilisez le workflow Git Gitflow Workflow pour gérer les versions de votre code source et le partager entre vous.

Respectez l'ensemble des règles, vues en cours, relatives aux messages de commit, aux conventions de nommage des branches et à la numérotation des versions.

Pour le workflow, une fois les étapes 1 à 4 terminées pour votre thème :

Le membre 2 fait un « merge commit » (merge no-fast-forward) de la branche feature/topic-x dans la branche develop.
- Avant le merge, il met à jour ses branches locales feature/topic-x et develop (git fetch, puis git rebase origin/<branche> sur chacune d'elles) : sinon, il fusionnerait une version de la branche sans les dernières contributions des autres.
Le membre 2 ajoute votre thème dans la table des matières de la page principale du site MkDocs index.md (dans l'ordre alphabétique A-C).
- L'entrée dans la table des matières est cliquable et permet d'accéder à la page de votre thème.
- Il fait un commit de cette modification dans la branche develop après le merge de la branche feature, puis push la branche develop et supprime la branche feature/topic-x sur origin.
Le membre 3 crée une branche release avec le bon numéro de version, depuis la branche develop à jour, qui contient le travail du membre 2.
- Chaque ajout d'une nouvelle feature (thème) incrémente la version mineure du projet : 0.X.0 (ex. release-0.5.0).
- Les trois groupes publient chacun une version, de même que B1 (préparation) et C1 (pages d'exemple) : si le numéro prévu a déjà été utilisé, prenez le suivant.
- Une seule release à la fois dans la classe : annoncez quand vous commencez, puis quand vos push sont passés. Deux releases en parallèle modifieraient le même endroit de CHANGELOG.md et pourraient prendre le même numéro de version.
Dans la branche release, le membre 3 met à jour le fichier CHANGELOG.md.
Pour terminer, le membre 3 fait un « merge commit » (merge no-fast-forward) de la branche release dans les branches main puis develop (dans cet ordre), puis push les branches main et develop et supprime la branche release.
- Mettez d'abord à jour la branche main locale (git checkout main, git fetch, git rebase origin/main) : les releases des autres l'ont modifiée.
A la fin du travail pratique, seules les branches main et develop doivent exister sur origin (plus de branches feature ou release).

🚨 Pas de merge dans ou depuis les branches origin, uniquement dans les branches locales ! Seule exception : la fusion, sur GitLab, d'une merge request validée (étape 5).

Si votre push ne passe pas sur origin, faites un fetch et résolvez les conflits (éventuellement faites un rebase, voir l'avertissement ci-dessous si vos commits locaux contiennent un merge commit).
Evitez de faire un pull afin de ne pas générer de merge inutile.
Utilisez « interactive rebase » pour repositionner, modifier ou arranger uniquement vos commits locaux, pas encore poussés : les branches feature sont partagées par toute la classe, réécrire des commits déjà sur origin casserait le travail des autres.
Utilisez les branches hotfix pour corriger les erreurs ou les oublis dans le code fusionné dans la branche main.

Push refusé après un merge commit

Plusieurs personnes fusionnent des branches dans develop pendant le TP (extensions, thèmes, releases, pages d'exemple) : votre push de develop peut être refusé juste après votre « merge commit », parce que quelqu'un d'autre a poussé entre-temps.

Dans ce cas, un simple git rebase origin/develop ne convient pas : par défaut, rebase supprime les merge commits et recopie les commits de la branche fusionnée à la suite les uns des autres, directement dans develop. Le merge no-fast-forward disparaît de l'historique, et le workflow Git n'est plus respecté.

Récupérez les commits des autres : git fetch
Rejouez vos commits en conservant le merge commit : git rebase --rebase-merges origin/develop (dans IntelliJ IDEA : fenêtre Rebase, Modify options, puis --rebase-merges)
Si un conflit apparaît dans le merge commit, résolvez-le à nouveau : Git ne réutilise pas la résolution faite lors du merge.
Contrôlez avec git log --oneline --graph que votre merge commit est toujours présent, puis recommencez le push.

Pour limiter ces refus, annoncez à la classe quand vous commencez à fusionner dans develop, puis quand votre push est passé, comme pour l'inscription dans TEAMS.md.

Sources :

Mise en production

Résolvez les problèmes ou erreurs résiduelles du TP04 (votre VPS doit être configuré correctement).
Déployez la dernière version du site MkDocs (le site web produit avec la commande build) sur votre serveur de production (VPS) avec l'URL https://tp05.apiXX.isc.heia-fr.ch (remplacez XX par le numéro de votre serveur personnel).
- La page d'accueil de nginx doit bien évidemment rester accessible avec l'URL https://apiXX.isc.heia-fr.ch.
- Par « dernière version du site MkDocs », on entend la version finale du code avec les thèmes de tous les groupes et les pages HTML individuelles d'exemple.

Rendu du TP

Aucun rapport, manuel ou documentation n'est demandé pour ce travail pratique.

Le dernier commit sur Git doit être fait au plus tard le jeudi 29 octobre à 23h59.

La dernière version du site MkDocs doit avoir été mise en ligne sur votre VPS au plus tard le vendredi 30 octobre à 23h59.

Le TP sera évalué, entre autres, sur les critères suivants :

Respect de toutes les consignes de ce document
Contributions de chaque personne dans les trois branches feature (étapes 2 et 3)
Page HTML d'exemple conforme, merge request relue, commentée, approuvée et fusionnée correctement (étape 5)
Tâches communes réalisées correctement (extensions Markdown, première release, branche d'intégration des pages d'exemple)
Utilisation correcte du workflow Git
Commits respectant les règles vues ensemble (un ensemble logique de changements par commit)
Mises à jour correctes et pertinentes du changelog
Numérotation correcte des versions
Disponibilité de la dernière version du site sur votre VPS
Uniformité dans la rédaction des thèmes entre les groupes
VPS correctement configuré (correction des points selon votre grille d'évaluation du TP04)

Membre	Topic A	Topic B	Topic C
1	`header`	`article`	`nav`
2	`main`	`section`	`div`
3	`footer`	`aside`	`span`