CONTRIBUTING-CORE.rst (#1482)

awecx · Seluj78 · web-flow · commit cf4858b5a6d1 · 2020-12-02T21:11:48.000+01:00
* Section maintenance dans un guide séparé + suppression infos sur Transifex.

* Modifs mineures.

* Ajout titre à CONTRIBUTIN-CORE.

Co-authored-by: Jules Lasne &lt;jules.lasne@gmail.com&gt;
diff --git a/CONTRIBUTING-CORE.rst b/CONTRIBUTING-CORE.rst
@@ -0,0 +1,87 @@
+Maintenance
+-----------
+
+Les commandes suivantes doivent être exécutées à partir de la racine d'un clone
+de ``python-docs-fr`` et certaines s'attendent à trouver un clone de CPython
+à jour à proximité :
+
+.. code-block:: bash
+  
+  ~/
+  ├── python-docs-fr/
+  └── cpython/
+  
+  
+Pour cloner CPython, vous pouvez utiliser :
+  
+.. code-block:: bash
+  
+  git clone --depth 1 --no-single-branch https://github.com/python/cpython.git
+  
+  
+Ceci évite de télécharger tout l'historique (inutile pour générer la
+documentation) mais récupère néanmoins toutes les branches.
+
+.. code-block:: bash
+  
+  make merge
+
+Dans certains cas on a besoin de propager 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, lorsque quelqu'un a une PR sur une
+  ancienne version (*forward porting*) ;
+- d'une nouvelle branche vers des anciennes branches : pour propager
+  de temps en temps le travail sur d'anciennes versions (rétroportage
+  ou *backporting*).
+  
+Pour forward-porter un ou plusieurs commits, il vaut mieux utiliser ``git
+cherry-pick -x LE_SHA``, ça garde l'auteur, le sha1 d'origine, et
+toutes les modifications.
+
+Pour rétroporter « en gros » on utilise ``pomerge``\  : on le fait lire
+sur une branche, puis écrire sur une autre, par exemple pour copier de
+la 3.8 à la 3.7 :
+  
+.. code-block:: bash
+  
+    git fetch
+    git checkout 3.8
+    git reset --hard upstream/3.8
+    pomerge --from-files *.po */*.po
+    git checkout --branch back-porting upstream/3.7
+    pomerge  --no-overwrite --to-files *.po */*.po
+    powrap --modified
+    git add --patch
+    git commit --message="Backporting from 3.8"
+    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 de temps) ;
+- 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.
+  On peut le tenter sans ``--no-overwrite``, attention, ça fait
+  des bêtises, ça nécessite une relecture attentive :
+  certaines traductions, comme *example:* sont en parfois traduites en
+  français 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,
+  en général, 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* auquel il peut manquer des lignes.
+
diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst
@@ -30,7 +30,7 @@ où vous avez le droit de faire des modifications.
     # Clonez votre fork Github avec `git` en utilisant ssh
     git clone git@github.com:VOTRE_NOM_DE_COMPTE_GITHUB/python-docs-fr.git
 
-    # ou bien via HTTPS
+    # ou bien avec HTTPS
     git clone https://github.com/VOTRE_NOM_DE_COMPTE_GITHUB/python-docs-fr.git
 
     # Allez dans le répertoire cloné
@@ -187,10 +187,10 @@ branche est liée à votre *fork* Github (et donc que vos futurs ``git pull`` et
 
 
 
-La commande précédente vous affiche un lien pour ouvrir une pull request sur
+La commande précédente vous affiche un lien pour ouvrir une *pull request* sur
 Github. Si vous l'avez manqué, allez simplement sur https://github.com/python/python-docs-fr/pulls
 et un joli bouton « Compare & pull request » devrait apparaître au bout de
-quelques secondes vous indiquant que vous pouvez demander une pull request.
+quelques secondes vous indiquant que vous pouvez demander une *pull request*.
 
 Mettez dans le commentaire de la *pull request* le texte suivant :
 « Closes #XXXX » où XXXX est le numéro du ticket GitHub créé pour réserver le fichier traduit.
@@ -367,7 +367,7 @@ Ne traduisez pas le contenu des balises comme ``:ref:...`` ou ``:class:...``.
 Vous devez cependant traduire les balises ``:term:...``, qui font référence à
 un concept ou une primitive défini dans le `glossaire Python <https://docs.python.org/fr/3/glossary.html>`_.
 La syntaxe est ``:term:nom_français<nom_anglais>``. Par exemple, traduisez
-``:term:`dictionary``` en  ``:term:`dictionnaire <dictionary>```.
+``:term:`dictionary``` en ``:term:`dictionnaire <dictionary>```.
 
 Comme le glossaire est déjà traduit, il y a forcément une correspondance à chaque
 terme que vous pouvez rencontrer.
@@ -379,7 +379,7 @@ Glossaire
 Afin d'assurer la cohérence de la traduction, voici quelques
 termes fréquents déjà traduits. Une liste blanche de noms propres, comme « Guido »,
 « C99 » ou de certains anglicismes comme « sérialisable » ou « implémentation»,
-est stockée dans le fichier « dict » à la racine du projet. Vous pouvez
+est stockée dans le fichier *dict* à la racine du projet. Vous pouvez
 y ajouter une entrée si cela est nécessaire.
 Si vous devez *absolument* utiliser un mot anglais, mettez-le en italique
 (entouré par des astérisques).
@@ -476,7 +476,7 @@ Ressources de traduction
 - les listes de diffusion relatives à la documentation (courriel) :
 
   - `de l'AFPy <http://lists.afpy.org/mailman/listinfo/traductions>`_,
-  - `de cpython <https://mail.python.org/mailman/listinfo/doc-sig>`_ ;
+  - `de CPython <https://mail.python.org/mailman/listinfo/doc-sig>`_ ;
 - des glossaires et dictionnaires :
 
   - le `glossaire de la documentation Python <https://docs.python.org/fr/3/glossary.html>`_, car il est déjà traduit,
@@ -489,8 +489,8 @@ Ressources de traduction
   résumé succinct de typographie, utile pour apprendre le bon usage des
   majuscules, des espaces, etc.
 
-L'utilisation de traducteurs automatiques comme `DeepL https://www.deepl.com/` ou semi-automatiques comme
-`reverso https://context.reverso.net/traduction/anglais-francais/` est proscrite.
+L'utilisation de traducteurs automatiques comme `DeepL <https://www.deepl.com/>`_ ou semi-automatiques comme
+`reverso <https://context.reverso.net/traduction/anglais-francais/>`_ est proscrite.
 Les traductions générées sont très souvent à retravailler, ils ignorent les règles énoncées sur cette
 page et génèrent une documentation au style très « lourd ».
 
@@ -528,13 +528,13 @@ Comment définir la touche de composition ?
 
 Cela dépend de votre système d'exploitation et de votre clavier.
 
-=> Sous Linux, Unix et \*BSD (tel OpenBSD), vous pouvez la configurer à l'aide de
-l'outil graphique de configuration de votre clavier ou via
+⇒ Sous Linux, Unix et \*BSD (tel OpenBSD), vous pouvez la configurer à l'aide de
+l'outil graphique de configuration de votre clavier ou avec
 ``dpkg-reconfigure keyboard-configuration``
 (pour `Ubuntu <https://help.ubuntu.com/community/ComposeKey>`_ ou Debian
 et distributions assimilées).
 
-À minima, vous pouvez configurer votre fichier '~/.Xmodmap' pour
+À tout le moins, vous pouvez configurer votre fichier *~/.Xmodmap* pour
 ajouter l'équivalent de :
 
 .. code-block:: shell
@@ -546,19 +546,19 @@ ajouter l'équivalent de :
 Utilisez ``xev`` pour connaitre la bonne correspondance de la touche que vous
 voulez assigner !
 
-Ensuite, dans votre fichier '~/.xsession', ajoutez :
+Ensuite, dans votre fichier *~/.xsession*, ajoutez :
 
 .. code-block:: shell
 
     # Gestion des touches clavier
     xmodmap $HOME/.Xmodmap
 
 
-Sous X, avec un bureau graphique, tel que Gnome, ou Xfce, il faut aller
+⇒ Sous X, avec un bureau graphique, tel que Gnome, ou Xfce, il faut aller
 modifier dans les « Paramètres » → « Clavier » → « Disposition » →
 « Touche composée ». Pour finir, redémarrez votre session.
 
-=> Sous Windows, vous
+⇒ Sous Windows, vous
 pouvez utiliser `wincompose <https://github.com/SamHocevar/wincompose>`_.
 
 Le cas de « --- », « -- »,  « ... »
@@ -573,7 +573,7 @@ Les *smartquotes* sont normalement responsables de la transformation de
 ``--`` en *en-dash* (``—``), de ``---`` en *em-dash* (``—``), et de
 ``...`` en *ellipses* ``…``.
 
-=> Si vous voyez :
+⇒ Si vous voyez :
 | « -- » ou « --- » : faites :kbd:`Compose - - -`
 | « ... » : faites :kbd:`Compose . . .`
 
@@ -585,7 +585,7 @@ guillemets anglais ``"``. Cependant, Python utilise les guillemets
 anglais comme délimiteurs de chaîne de caractères. Il convient donc de
 traduire les guillemets mais pas les délimiteurs de chaîne.
 
-=> Si vous voyez :
+⇒ Si vous voyez :
 | « "…" » : faites :kbd:`Compose < <` ou :kbd:`Compose > >`
 
 Le cas de « :: »
@@ -599,7 +599,7 @@ Le cas de « :: »
 En français, nous mettons une espace insécable devant nos deux-points, comme :
 « Et voilà : ».
 
-=> Traduisez ``mot deux-points deux-points`` par
+⇒ Traduisez ``mot deux-points deux-points`` par
 ``mot espace-insécable deux-points deux-points``.
 
 Pour saisir une espace insécable faites :kbd:`Compose SPACE SPACE`
@@ -710,128 +710,3 @@ ce qui suit après vous être assuré que ``~/.local/bin/`` se trouve dans votre
 Pas d'inquiétude, cela ne change la façon dont Git affiche les changements que sur
 les fichiers de la traduction, sans incidence sur les autres.
 
-
-Maintenance
------------
-
-Toutes ces commandes doivent être exécutées à partir de la racine d'un clone
-de ``python-docs-fr`` et certaines s'attendent à trouver un clone de CPython
-à jour à proximité, comme :
-
-.. code-block:: bash
-
-  ~/
-  ├── python-docs-fr/
-  └── cpython/
-
-
-Pour cloner CPython, vous pouvez utiliser :
-
-.. code-block:: bash
-
-  git clone --depth 1 --no-single-branch https://github.com/python/cpython.git
-
-
-Ceci évite de télécharger tout l'historique (inutile pour générer la
-documentation) mais récupère néanmoins toutes les branches.
-
-
-Fusion des fichiers *pot* de CPython
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-.. code-block:: bash
-
-  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*).
-
-Pour forward-porter un ou plusieurs commits, il vaut mieux utiliser ``git
-cherry-pick -x LE_SHA``, ça garde l'auteur, le sha1 d'origine, et
-toutes les modifications.
-
-Pour backporter « en gros » on utilise ``pomerge``\  : on le fait lire
-sur une branche, puis écrire sur une autre, par exemple pour copier de
-la 3.8 à la 3.7 :
-
-.. code-block:: bash
-
-    git fetch
-    git checkout 3.8
-    git reset --hard upstream/3.8
-    pomerge --from-files *.po */*.po
-    git checkout --branch back-porting upstream/3.7
-    pomerge  --no-overwrite --to-files *.po */*.po
-    powrap --modified
-    git add --patch
-    git commit --message="Backporting from 3.8"
-    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.
-  On peut le tenter sans ``--no-overwrite``, attention, ça fait
-  des bêtises, ça nécessite une relecture attentive :
-  certaines traductions, comme *example:* sont en
-  français 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
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Vous aurez besoin de ``transifex-client`` et ``powrap``,
-depuis PyPI.
-
-Vous devrez configurer ``tx`` via ``tx init`` si ce n'est déjà fait.
-
-Propagez d'abord les traductions connues localement :
-
-.. code-block:: bash
-
-    pomerge --no-overwrite --from-files **/*.po --to-files **/*.po
-    powrap --modified
-    git commit --message "Propagating known translations."
-
-
-Ensuite récupérez les changements depuis Transifex :
-
-.. code-block:: bash
-
-    tx pull -f --parallel
-    pomerge --from-files **/*.po
-    git checkout -- .
-    pomerge --no-overwrite --mark-as-fuzzy --to-files **/*.po
-    powrap --modified
-    git add -p
-    git commit -m "tx pull"
-    tx push -t -f --no-interactive --parallel
