From 3daad4d70fa129fd3da8b2904cd655a91876e69c Mon Sep 17 00:00:00 2001
From: Julien Palard <julien@palard.fr>
Date: Thu, 25 Jun 2020 10:09:58 +0200
Subject: [PATCH] Documenting back porting and forward porting. (#1339)

---
 CONTRIBUTING.rst | 55 ++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 55 insertions(+)

diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst
index a95dfcf6..e4c253d3 100644
--- a/CONTRIBUTING.rst
+++ b/CONTRIBUTING.rst
@@ -719,6 +719,61 @@ Fusion des fichiers *pot* de CPython
   make merge
 
 
+Copier des traductions d'une branche à l'autre
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Dans certains cas on a besoin de bouger des traductions d'une branche
+à l'autre :
+
+- d'une ancienne branche vers une nouvelle branche : lors du passage
+  d'une version à l'autre de cpython, quelqu'un a une PR sur une
+  ancienne release (*forward porting*) ;
+- d'une nouvelle branche vers des anciennes branches : pour propager
+  de temps en temps le travail sur d'anciennes releases (*back porting*).
+
+On utilise ``pomerge``\  : on le fait lire sur une branche, puis écrire
+sur une autre, par exemple pour copier de la 3.7 à la 3.8 ::
+
+    git fetch
+    git checkout 3.7
+    git reset --hard upstream/3.7
+    pomerge --from-files *.po */*.po
+    git checkout -b forward-porting upstream/3.8
+    pomerge  --no-overwrite --to-files *.po */*.po
+    powrap -m
+    git add --patch
+    git commit --message="Forward porting from 3.7"
+    git push --set-upstream origin HEAD
+
+Notes :
+
+- j'utilise ``git fetch`` au début pour avoir upstream/3.7 et
+  upstream/3.8 à jour localement, ainsi je peux travailler sans
+  toucher au réseau jusqu'au ``git push``, mais chacun fait comme il
+  veut ;
+- j'utilise ``*.po */*.po`` et pas ``**/*.po``, car si vous avez un
+  venv dans l'arborescence il va vous trouver des traductions de Sphinx et peut-être
+  d'autres paquets dans ``.venv/lib/python*/`` (et mettre beaucoup
+  plus longtemps) ;
+- j'utilise ``pomerge --no-overwrite``, ça indique à ``pomerge`` de
+  n'écrire que si le ``msgstr`` est vide, donc de ne pas modifier
+  l'existant, ainsi il est impossible de casser quelque chose, c'est
+  important lors du *forward-porting* pour ne pas défaire une
+  correction. Mais on pourrait le tenter sans ``--no-overwrite`` sur
+  du rétroportage, attention, ça fait des bêtises, ça nécessite une
+  relecture attentive : certaines traductions, comme *example:* sont en
+  francais parfois traduite avec une majuscule, et parfois non, en
+  fonction du contexte, ``pomerge`` uniformiserait ça, ce n'est pas bien ;
+- attention, si vous testez sans ``--no-overwrite``, il est peut être
+  bon de vider la mémoire de ``pomerge`` avant la lecture, pour éviter
+  de lui faire écrire des choses lues lors des sessions précédentes,
+  via un ``rm -f ~/.pomerge.json``\  ;
+- j'utilise ``git add --patch`` (ou ``-p``) car j'aime bien relire quand même,
+  typiquement je n'ajoute pas les différences d'ordre dans les entêtes,
+  mais un ``git add --update`` irait très bien ;
+- attention au fichier *dict* à qui il peut manquer des lignes.
+
+
 Synchronisation de la traduction avec Transifex
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~