From 52615fdff63bfc68a4504239ca87ca7171d4d5fe Mon Sep 17 00:00:00 2001 From: Julien Palard Date: Sat, 7 Jul 2018 12:05:21 +0200 Subject: [PATCH 1/3] Be more specific about our git flow. --- README.rst | 94 +++++++++++++++++++++++++++++++++++++++--------------- 1 file changed, 68 insertions(+), 26 deletions(-) diff --git a/README.rst b/README.rst index b5838899b..4eef52afb 100644 --- a/README.rst +++ b/README.rst @@ -42,39 +42,81 @@ You can contribute using: Contributing using Github ~~~~~~~~~~~~~~~~~~~~~~~~~ -You'll first need a `github account `_. +Prerequisites: -Then you'll need to fork the project by clicking the ``Fork`` button -on `python-docs-fr `_. This -creates a copy of the whole project on your github account: a place -where you have the rights to do modifications. +- A `github account `_. +- ``git`` `installed `_ (for windows, see + https://gitforwindows.org/). +- A ``.po`` file editor (Use `poedit `_ + if you don't already have one). -To modify po files you'll need to synchronize the project files to -your computer by using ``git``: https://help.github.com/articles/set-up-git/. -Once the project files are synchronized to your computer, you'll be -able to modify them, those are ``.po`` files and can be modified using -various tools: +Let's start: -- `poedit `_ (recommended) -- gted -- gtranslator -- lokalize -- betterpoeditor -- vim or emacs with an appropriate mode -- Vé on Android -- Probably many others +You'll need to fork the `python-docs-fr +`_ clicking its ``Fork`` +button. This creates a copy of the whole project on your github +account: a place where you have the rights to do modifications. -Before commiting, you should use `grammalecte -`_ to check for your translations. +Step by steps:: + + # Git clone your github fork using ssh (replace JulienPalard): + $ git clone git@github.com:JulienPalard/python-docs-fr.git + + # Go to the cloned directory: + $ cd python-docs-fr/ + + # Add the upstream (the public repository) using HTTPS (won't ask for password): + $ git remote add upstream https://github.com/python/python-docs-fr.git + + +Now you're ready to start a work session, each time you'll start a new task, start here:: + + # To work, we'll need a branch, based on an up-to-date (freshly fetched) + # upstream/3.7 branch, let's say we'll work on glossary so we name + # the branch "glossary": + $ git fetch upstream + $ git checkout -b glossary upstream/3.7 + + # You can now work on the file, typically using poedit, + # then commit your work with a nice explicit message: + $ git commit -a -m "Working on glossary." -After commiting (this is just "naming the modification"), synchronize -the file back to github using ``git push``. + # Then push your modifications to your github clone, + # as they are ephemeral branches, let's not configure git to track them all, + # "origin HEAD" is a "special" syntax to say "Push on origin, + # on a branch with the same name as the local one", + # it's nice as it's exactly what we want: + $ git push origin HEAD -And now, from your github project, a buttun should appear "Compare & -pull request", this is asking us, the main project, to pull your -modifications. This step may take some time as we'll review your -modifications before accepting them, and we may ask for modifications. + # Now you can open the pull request on github, just go to + # https://github.com/python/python-docs-fr/ and a nice "Compare & pull request" + # button should appear after a few seconds telling you can ask for a pull request. + + # Now someone is reviewing your modifications, and you'll want to fix their + # findings, get back to your branch + # (in case you started something else on another branch): + $ git checkout glossary + # Fix the issues, then commit again: + $ git commit -a -m "glossary: small fixes." + $ git push origin HEAD + + +You may have noted that this looks like a triangle, with a missing segment: + +- You're fetching from upstream (public common repo on github) +- You're pushing to origin (your clone on github) + +So yes it's the work of someone to add the last segment, from your +origin to the public upstream, to "close the loop", that's the role of +the people who merges pull requests after proofreading them. + +You may also have noted you never ever commit on a version branch +(``3.6``, ``3.7``, ...), only pull from them, consider them read-only +you'll avoid problems. + +Before commiting, you should use `grammalecte +`_ to check for your translations. What to translate From b4c4494d330fe0fe8d3f223f678a49a632c5b55d Mon Sep 17 00:00:00 2001 From: Julien Palard Date: Sat, 7 Jul 2018 12:33:00 +0200 Subject: [PATCH 2/3] README: FIX code block syntax highlighting. --- README.rst | 36 +++++++++++++++++++++++------------- 1 file changed, 23 insertions(+), 13 deletions(-) diff --git a/README.rst b/README.rst index 4eef52afb..223555915 100644 --- a/README.rst +++ b/README.rst @@ -58,36 +58,40 @@ You'll need to fork the `python-docs-fr button. This creates a copy of the whole project on your github account: a place where you have the rights to do modifications. -Step by steps:: +Step by steps: + +.. code-block:: bash # Git clone your github fork using ssh (replace JulienPalard): - $ git clone git@github.com:JulienPalard/python-docs-fr.git + git clone git@github.com:JulienPalard/python-docs-fr.git # Go to the cloned directory: - $ cd python-docs-fr/ + cd python-docs-fr/ # Add the upstream (the public repository) using HTTPS (won't ask for password): - $ git remote add upstream https://github.com/python/python-docs-fr.git + git remote add upstream https://github.com/python/python-docs-fr.git -Now you're ready to start a work session, each time you'll start a new task, start here:: +Now you're ready to start a work session, each time you'll start a new task, start here: + +.. code-block:: bash # To work, we'll need a branch, based on an up-to-date (freshly fetched) # upstream/3.7 branch, let's say we'll work on glossary so we name # the branch "glossary": - $ git fetch upstream - $ git checkout -b glossary upstream/3.7 + git fetch upstream + git checkout -b glossary upstream/3.7 # You can now work on the file, typically using poedit, # then commit your work with a nice explicit message: - $ git commit -a -m "Working on glossary." + git commit -a -m "Working on glossary." # Then push your modifications to your github clone, # as they are ephemeral branches, let's not configure git to track them all, # "origin HEAD" is a "special" syntax to say "Push on origin, # on a branch with the same name as the local one", # it's nice as it's exactly what we want: - $ git push origin HEAD + git push origin HEAD # Now you can open the pull request on github, just go to # https://github.com/python/python-docs-fr/ and a nice "Compare & pull request" @@ -96,10 +100,10 @@ Now you're ready to start a work session, each time you'll start a new task, sta # Now someone is reviewing your modifications, and you'll want to fix their # findings, get back to your branch # (in case you started something else on another branch): - $ git checkout glossary + git checkout glossary # Fix the issues, then commit again: - $ git commit -a -m "glossary: small fixes." - $ git push origin HEAD + git commit -a -m "glossary: small fixes." + git push origin HEAD You may have noted that this looks like a triangle, with a missing segment: @@ -227,12 +231,16 @@ Simplify git diffs Git diffs are often crowded with useless line number changes, like: +.. code-block:: diff + -#: ../Doc/library/signal.rst:406 +#: ../Doc/library/signal.rst:408 To tell git they are not usefull information, you can do the following after ensuring ``~/.local/bin/`` is in your ``PATH``. +.. code-block:: bash + cat < ~/.local/bin/podiff #!/bin/sh grep -v '^#:' "\$1" @@ -254,7 +262,9 @@ like:: ├── python-docs-fr/ └── cpython/ -To clone CPython you may use:: +To clone CPython you may use: + +.. code-block:: bash git clone --depth 1 --no-single-branch https://github.com/python/cpython.git From 382a2ed399707322a47f4eb3236d325271a73dd4 Mon Sep 17 00:00:00 2001 From: Julien Palard Date: Sat, 7 Jul 2018 12:48:48 +0200 Subject: [PATCH 3/3] FIX: Typo. --- README.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.rst b/README.rst index 223555915..0866de61c 100644 --- a/README.rst +++ b/README.rst @@ -58,7 +58,7 @@ You'll need to fork the `python-docs-fr button. This creates a copy of the whole project on your github account: a place where you have the rights to do modifications. -Step by steps: +Step by step: .. code-block:: bash