From 939285b7e8baca3b323ed4d85ca5fab6ca733235 Mon Sep 17 00:00:00 2001 From: "Jules Lasne (jlasne)" Date: Sat, 2 May 2020 23:52:27 +0200 Subject: [PATCH] Readme contributing typos + code blocks changes (#1039) * Fixed typo in README.rst * Separated code blocks Closes #1032 * Apply suggestions from code review * Update CONTRIBUTING.rst * Apply suggestions from code review Co-authored-by: Christophe Nanteuil <35002064+christopheNan@users.noreply.github.com> Co-authored-by: Mathieu Dupuy Co-authored-by: Christophe Nanteuil <35002064+christopheNan@users.noreply.github.com> --- CONTRIBUTING.rst | 116 +++++++++++++++++++++++++++++++---------------- README.rst | 2 +- 2 files changed, 77 insertions(+), 41 deletions(-) diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst index cdc0601a..93837432 100644 --- a/CONTRIBUTING.rst +++ b/CONTRIBUTING.rst @@ -51,64 +51,99 @@ votre traduction (voir `Outils utiles pour la traduction`_) Vous êtes maintenant prêt. Chaque fois que vous commencerez un nouveau fichier, suivez cette procédure : + +Pour travailler, nous aurons besoin d'une branche, basée sur une version à jour +(fraîchement récupérée) de la branche upstream/3.8. On met donc à jour notre +version locale. + .. code-block:: bash - # Pour travailler, nous aurons besoin d'une branche, basée sur une version à jour - # (fraîchement récupérée) de la branche upstream/3.8. On met donc à jour notre - # version locale. git fetch upstream - # On créé ensuite une branche. Il est pratique de nommer la branche en fonction du - # fichier sur lequel on travaille. Par exemple, si vous travaillez sur - # « library/sys.po », vous pouvez nommer votre branche « library-sys ». - # Cette nouvelle branche nommée « library-sys » est basée sur « upstream/3.8 ». + +On créé ensuite une branche. Il est pratique de nommer la branche en fonction du +fichier sur lequel on travaille. Par exemple, si vous travaillez sur +« library/sys.po », vous pouvez nommer votre branche « library-sys ». +Cette nouvelle branche nommée « library-sys » est basée sur « upstream/3.8 ». + +.. code-block:: bash + git checkout -b library-sys upstream/3.8 - # Vous pouvez maintenant travailler sur le fichier (typiquement, en utilisant poedit). - # N'oubliez pas de configurer votre nom et votre email dans Poedit. - # (Édition -> Préférences -> Général) - # Vérifiez aussi qu'il est configuré pour passer à la ligne à 79 caractères. - # (Édition -> Préférences -> Avancé -> Passer à la ligne à : 79) - # - # Ici, remplacez « library/sys.po » par le fichier que vous avez choisi précédemment. - # poedit library/sys.po ou lancez simplement poedit puis « Fichier » → « Ouvrir » - # Si vous n'utilisez pas poedit, vous pouvez utiliser `powrap` (voir la section *outils*) - # qui va reformater correctement le fichier que avez vous avez modifié. - # Exécutez `powrap -m` (reformater tous les fichiers modifiés) - # ou `powrap library/sys.po` (un fichier en particulier) : +Vous pouvez maintenant travailler sur le fichier (typiquement, en utilisant poedit). +N'oubliez pas de configurer votre nom et votre email dans Poedit. +(Édition -> Préférences -> Général) +Vérifiez aussi qu'il est configuré pour passer à la ligne à 79 caractères. +(Édition -> Préférences -> Avancé -> Passer à la ligne à : 79) + +Ici, remplacez « library/sys.po » par le fichier que vous avez choisi précédemment. + +.. code-block:: bash + + poedit library/sys.po + +Ou lancez simplement poedit puis « Fichier » → « Ouvrir » + +Si vous n'utilisez pas poedit, vous pouvez utiliser `powrap `_. (voir la section *outils*) +qui reformate correctement le fichier que avez vous avez modifié. +Exécutez `powrap -m` (reformater tous les fichiers modifiés) +ou `powrap library/sys.po` (un fichier en particulier) : + +.. code-block:: bash + powrap -m - # Pour l'orthographe, une liste blanche de certains termes techniques ou - # de noms propres, comme « Guido », « C99 » ou « sérialisable », est - # stockée dans le fichier « dict » à la racine du projet. Vous pouvez - # bien sûr y ajouter une entrée si nécessaire. - # La commande suivante va lancer les vérifications nécessaires. +Pour l'orthographe, une liste blanche de certains termes techniques ou +de noms propres, comme « Guido », « C99 » ou « sérialisable », est +stockée dans le fichier « dict » à la racine du projet. Vous pouvez +bien sûr y ajouter une entrée si nécessaire. +La commande suivante lance les vérifications nécessaires. + +.. code-block:: bash + make verifs - # C'est le moment de git add et git commit. - # git add va permettre de déplacer nos modifications dans l'index de Git en - # attendant d'être déplacée dans le dépôt local. + +C'est le moment de git add et git commit +git add place nos modifications dans l'index de Git en +attendant d'être propagées dans le dépôt local. + +.. code-block:: bash + git add library/sys.po - # Puis on bascule les modifications dans le dépôt local avec un commit. + +Puis on propage les modifications dans le dépôt local avec un commit. + +.. code-block:: bash + git commit -m "Traduction de library/sys.po" # Ou un autre message plus inspiré :) - # Poussez ensuite vos modifications sur votre fork Github. - # Le -u n'est utile qu'une fois pour que votre client git se souvienne que cette - # branche est liée à votre fork Github (et donc que vos futurs `git pull` et - # `git push` sachent quoi tirer) + +Poussez ensuite vos modifications sur votre fork Github. +Le -u n'est utile qu'une fois pour que votre client git se souvienne que cette +branche est liée à votre fork Github (et donc que vos futurs `git pull` et +`git push` sachent quoi tirer) + +.. code-block:: bash + git push -u origin - # La commande précédente vous affichera 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. +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. + +Mettez dans le commentaire de la pull request le texte suivant : Fixes #9999 où 9999 est le numéro du ticket GitHub créé pour réserver le fichier traduit. + +À partir de là, quelqu'un passera en revue vos modifications, et vous fera des +suggestions/corrections. Pour les prendre en compte, retournez sur votre branche +contenant du fichier concerné (au cas où vous auriez commencé quelque chose d'autre +sur une autre branche) : + +.. code-block:: bash - # À partir de là, quelqu'un passera en revue vos modifications, et vous fera des - # suggestions-corrections. Pour les prendre en compte, retournez sur votre branche - # contenant du fichier concerné (au cas où vous auriez commencé quelque chose d'autre - # sur une autre branche) : git checkout library/sys git pull # pour rapatrier les modifications que vous auriez acceptées # sur l'interface web. @@ -117,6 +152,7 @@ suivez cette procédure : git commit -a -m "prise en compte des remarques" git push + Vous avez peut-être remarqué que cela ressemble à un triangle, avec un segment manquant : diff --git a/README.rst b/README.rst index 1b0d354d..ae339722 100644 --- a/README.rst +++ b/README.rst @@ -70,4 +70,4 @@ l'`AFPy `_. En 2017 ce projet est devenu la traduction officielle de la documentation Python en français grâce à la `PEP 545 `_. `Jules Lasne `_ à publié fin 2019 une `vidéo de -l'histoire du dépôt `_. +l'histoire du dépôt `_. \ No newline at end of file