Nouvelle version majeure

Une nouvelle version majeure nécessite un gros travail qui se fait en quatre étapes. Les étapes 2 à 5 peuvent être réalisées plusieurs fois, au maximum une fois par versions Beta et Release Candidate.

Étape 1, la création des fichiers automatiques

Certains fichiers de la documentation sont créés par des programmes. Voici comment les créer :

cd doc/src/sgml
make errcodes-table.sgml
make features-supported.sgml
make features-unsupported.sgml
make keywords-table.sgml
make targets-meson.sgml
make wait_event_types.sgml

Étape 2, le merge

Le but est de regarder toutes les différences entre l'ancienne version originale et la nouvelle. Ces différences se récupèrent avec la commande suivante (entre les versions 12 et 13 pour l'exemple) :

git diff REL_12_STABLE..REL_13_BETA1 doc/src/sgml > ~/en13.patch

Le résultat (le fichier ~/en13.patch) contient toutes les modifications qu'il va falloir reporter dans les fichiers de la traduction.

Certains fichiers sont nouveaux. Il faut les ajouter avec un git add. De même, certains disparaissent. Il faut les supprimer avec un git rm.

Quant aux fichiers modifiés, les petites modifications sont immédiatement traduites, les grosses sont laissés pour plus tard. Les modifications des fichiers Makefile et XSLT sont à prendre en compte immédiatement. Les fichiers SVG sont à copier simplement.

Une fois le merge terminé, il convient de faire un git commit -a. Le message de commit est traditionnellement Merge v13 beta X.

Étape 3, la création/mise à jour de la page de traduction

Une page du wiki est créée pour savoir qui a réclamé tel ou tel fichier.

Voici un script permettant de créer le tableau :

git diff | diffstat -tf4 | awk -F "," '/b\// { print "| " $4 " | " $1 " | |"}' | sort -k2

Le tableau sera ensuite à améliorer, et la page à construire, mais l'essentiel et le plus compliqué est là.

Étape 4, la traduction

Chaque personne intéressée place son nom sur un fichier du tableau et traduit les paragraphes/phrases ajoutés. Il renvoie le fichier par mail ou en faisant une PR pour qu'il puisse être relu, puis intégré.

Étape 5, la mise à disposition

Il est intéressant de générer la documentation de temps à autre pendant la traduction. Ça permet à d'autres personnes de relire la traduction et de remonter les erreurs.

Étape 6, la réindentation

En fin de traduction de la version complète, il est important de penser à réindenter la documentation. Il existe un programme pour cela dans le répertoire tools. Un simple make suffit à le compiler. Le script suivant permet de réindenter tous les fichiers se trouvant dans le répertoire courant et ses sous-répertoires :

#!/bin/sh

find . -name "*.xml" | while read file
do
  mv ${file} ${file}.old
  cat ${file}.old | ~/bin/pg_doc_indent > ${file}
  echo -n "."
done
echo " done!"

Le message de commit est généralement un simple Réindentation.