Mettre à jour le site des tuteurs ou y ajouter du contenu

Les pages HTML du site web des tuteurs sont produites à partir de fichiers dans un format XML maison appelé TML. Tout le contenu du site est sous git, et l'arborescence HTML est mise à jour automatiquement à chaque push (de la branche qui va bien) dans ~tuteurs/www.git.

Cette page décrit les étapes pour effectuer un changement sur le site, et donne au passage, sans explications, le strict minimum de commandes git nécessaires. Il est cependant recommandé d'aller en apprendre un peu plus sur la page consacrée à git ou dans la doc de ce dernier.

Préliminaires

Le dépôt git

Le source TML du site web est géré par git, un système de contrôle de versions. Pour y apporter des changements, on modifie sa propre copie du source TML obtenue en clonant le dépôt git ~tuteurs/www.git, puis on envoie les changements au dépôt central. Le plus simple est de travailler sur son compte clipper, mais il est possible de le faire depuis une machine personnelle, voire avec quelques précautions depuis le compte tuteurs.

On ne modifie jamais directement les fichiers du répertoire ~tuteurs/www.

La meilleure façon est de commencer par mettre une clé ssh chez tuteurs (si on n'en a pas déjà) puis de faire (de chez soi ou d'une machine de l'école)

$ git clone tuteurs@sas.eleves:www.git 

On peut aussi (ce n'est guère utile qu'aux gens qui n'ont plus de compte clipper) cloner le dépôt git sur le compte tuteurs lui-même, par exemple dans tmp/moi.

Dans ce cas, il est important de veiller avant tout commit à régler les nom et adresse utilisés pour identifier l'auteur du commit :

$ export GIT_AUTHOR_NAME="Tartempion"
$ export GIT_AUTHOR_EMAIL="tartempion@phare"

Quand on travaille depuis son propre compte, les valeurs par défaut font généralement l'affaire, sinon, on peut les changer une fois pour toutes via

$ git config --global user.name "Tartempion"
$ git config --global user.email "tartempion@clipper"

Les outils TML

Plusieurs programmes utiles aux tuteurs — notamment, mais pas uniquement, pour travailler sur le site web — se trouvent dans ~tuteurs/bin. C'est donc une bonne idée de l'ajouter à son $PATH

Pour ce faire, éditez le fichier .profile à la racine de votre compte, trouvez le passage qui parle du PATH et modifiez la fin. Attention, ne pas oublier de mettre :\ (non suivi d'espace !) à la fin de l'avant-dernière ligne, et de tester (en vous logguant une deuxième fois) avant de se délogguer.

PATH=\
$HOME/bin/$SYSTEMNAME:\
$HOME/bin:\
$UTILPATH:\
$MAINPATH:\
$GAMESPATH:\
$MISCPATH:\
/users/staffs/tuteurs/bin

(Aucun de ces programmes n'est indispensable pour modifier le site web. Pour travailler depuis chez soi, on a le choix de s'en passer ou de les récupérer avec git clone tuteurs@sas.eleves:share/tml et y faire les adaptations nécessaires : il y a des chemins à adapter dans tml/lib/catalog.xml, ainsi que $BASE dans tmlcheck, build et rebuild.)

Créer ou modifier une page

Supposons que vous souhaitiez créer ou modifier la page unix/accents.html. Pour cela, il va falloir écrire un fichier unix/accents.tml.

Trucs plus avancés

Masquer une page dans l'arbre de navigation

Vous pouvez décider de ne pas faire apparaître une page dans l'arbre de navigation qui se trouve sur la gauche des pages.

Pour cela, le script de génération des pages regarde dans chaque répertoire si un fichier nolinks s'y trouve. Ce fichier doit contenir une liste séparée par des espaces ou des retours à la ligne de choses de la forme « fichier » ou encore « répertoire/ ». Cela désactivera les liens éventuels vers la page fichier.html ou vers l'index de répertoire.

Par exemple, pour ne pas faire apparaître cette page de documentation interne aux tuteurs (et quelques autres) dans l'index, la racine du CVS contient :

sas ~tuteurs/www $ cat nolinks
doc-interne
aide
404
actualite
plan_site

Pour supprimer un fichier nolinks, procédez en plusieurs étapes :

Ignorer un commit dans le calcul de la dernière modification

La date et l'auteur de la dernière modification de chaque page sont lus dans l'historique du dépôt git. Il est possible d'empêcher qu'un commit donné soit pris en compte pour ce calcul. (C'est utile, par exemple, si l'on a fait des modifications automatisées qui affectent plein de pages sans assurer que leur contenu soit à jour.) Il suffit pour cela de placer dans le message de commit la ligne magique Last-change: ignore this commit. On peut aussi ignorer un commit après coup en ajoutant son identifiant (SHA) au fichier .hidden_commits.

Ajuster le nom sous lequel on apparaît dans les dernières modifications

Voir le fichier .mailmap.

Quelqu'un a modifié les fichiers de www !

Lors de la mise à jour du site, il y a un mécanisme qui essaie de faire une copie de sauvegarde des modifications parasites avant de les écraser. Lancer git --git-dir=../www.git stash list depuis ~tuteurs/www et lire la doc de git stash

Doc technique

Quelques informations sur les scripts qui gèrent tout ça sont ou devraient apparaître peu à peu dans les divers fichiers README du compte tuteurs.

Auteurs : Joël Riou, Nicolas George, Éric Levieil, Marc Mezzarobba. Dernière modification : Sun Oct 20 00:04:58 2013 +0200 par Antoine Amarilli.