diff --git a/README.rst b/README.rst index cf673cac..135d0720 100644 --- a/README.rst +++ b/README.rst @@ -54,10 +54,10 @@ Prerequisites: if you don't already have one). -Let's start: +Getting Started: You'll need to fork the `python-docs-fr -`_ clicking its ``Fork`` +`_ source repository by 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. @@ -65,49 +65,59 @@ Step by step: .. code-block:: bash - # Git clone your github fork using ssh (replace JulienPalard): - git clone git@github.com:JulienPalard/python-docs-fr.git + # Clone your github fork with `git` using ssh or https: + git clone git@github.com:YOUR_GITHUB_USERNAME/python-docs-fr.git + git clone https://github.com:YOUR_GITHUB_USERNAME/python-docs-fr.git - # Go to the cloned directory: + # Go into the cloned directory: cd python-docs-fr/ # Add the upstream (the public repository) using HTTPS (won't ask for password): + # This is so git knows what/where the upstream is. git remote add upstream https://github.com/python/python-docs-fr.git -All the translations must be made on the latest release. -We never translate on an oldest version, by example, the latest python release -is python 3.7, we don't want to translate directly on the python 3.5 release. -If needed translations would be backported on the oldest versions by the -`documentation team `. +Next, you need to find a file to work on. +You can use `potodo `, a tool made to find ``po`` to do. +Install it using pip (``pip install potodo``) in a ``python3.7`` environement. +Then run the command ``potodo`` in your cloned fork. +From the list returned by the command, you can choose any file that is not reserved. -First, you need to find a file to work on. You can use `potodo `. -Install it (``pip install potodo`` in a venv) and then run the command -`potodo` in your cloned fork. -From the list it spits out, you can choose any file that is not -reserved. We recommend not starting with a file from ``c-api`` as it is very technical. +**We recommend not starting with a file from ``c-api`` as it is very technical.** -Once you've choosen a file, please open an issue telling you're -working on it, to block someone from working on it. +Once you've choosen a file to work one, please open an `issue on github ` in the format of `I'm working on FOLDER/FILE.po`. This is done to update ``potodo`` as it checks the github API for reserved ``.po`` files in issues and pull requests. -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 file, 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": + # upstream/3.7 branch. We will name our branch "library-sys" but you shall name yours + # whatever you want. Usually you'll name a branch based on the file you're working on. + # For example, If you're working on "library/venv.po" you can name your branch "library-venv" + + # Update your local version to the latest git fetch upstream - git checkout -b glossary upstream/3.7 + # Create a new branch named "library-sys" based on "upstream/3.7" + git checkout -b library-sys upstream/3.7 # You can now work on the file, typically using poedit, - poedit directory/file.po + # Of course, replace "library/sys.po" by the file you've chose earlier + poedit library/sys.po - # When everything is clear (syntax errors from Sphinx, html rendering, - # semantics, typography), + # When you are done translating, you can run pospell (pip install pospell). + # This tool was made to check if you don't have any french mistakes. + # You can run the following command: pospell -p dict -l fr_FR **/*.po to check all files + # or replace **/*.po by your specific file (recommended). + + # You can then run powrap (pip install powrap) which will rewrap + # You modified file to the correct line length of `80`. + # Run this command: `powrap **/*.po` or replace `**/*.po` with your modified file. + + # When everything powrap and pospell passes without errors, # you can commit your work with a nice explicit message: - git commit -a -m "Working on glossary." + git commit -a -m "Working on library/sys.po." - # Then push your modifications to your github clone, + # Then push your modifications to your github fork, # 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", @@ -145,6 +155,13 @@ Before commiting, you should use `grammalecte `_ to check for your translations. +All the translations must be made on the latest release. +We never translate on an oldest version. For example, if the latest python release +is Python 3.7, we don't want to translate directly on the python 3.5 release. +If needed translations would be backported on the oldest versions by the +`documentation team `. + + What to translate ~~~~~~~~~~~~~~~~~