====== Version control in Pootle ======

Pootle has the ability to integrate with version control systems (also called revision control systems) such as CVS or Subversion (SVN) (See [[wp>Revision_control]] for a general overview of what a version control system is.

All features described below are already implemented.

===== Extra reading =====

Some more ideas about version control integration are mentioned here: [[wordforge:version_control]]

Below there are references to assigning rights to users in Pootle. More information is here: [[permissions]]






===== Supported systems =====

^ System             ^ Status  ^
| [[wp>Concurrent_Versions_System|CVS]]  | Supported   |
| [[wp>Subversion (software)|Subversion]] (SVN)   | Supported  |
| [[wp>darcs]]              | Supported  |
| [[wp>git (software)|git]]                | Supported (since version 1.1)       |
| [[wp>Bazaar (software)|Bazaar]] (bzr)               | Supported (since version 1.1)       |
| [[wp>Mercurial (software)|Mercurial]]          | Development (in trunk)        |

It should be possible to add other systems fairly easily.  Interested programmers can look at the [[http://translate.svn.sourceforge.net/viewvc/translate/src/trunk/translate/storage/versioncontrol/|versioncontrol]] module.


===== Preparation =====
To have any sort of integration with version control from within Pootle, it is necessary to check out the translation files into their correct places in their Pootle projects. The CVS or SVN meta files (CVS/ or .svn/) need to be there. This has to be done outside of Pootle.


==== Example ====
<code>
cd pootle_podirectory
svn co https://translate.svn.sourceforge.net/svnroot/translate/src/trunk/Pootle/po/pootle
</code>

Now you have the directory 'pootle' contains a translation project. If that directory is now one of your projects registered on the server, the version control functions should appear for all users with the necessary priviledges. Look for the functions in "Show Editing Functions".

====== How to treat special directory layouts =====
Is the directory structure for the language files of your project different from the default structure found in the source project?

If yes, then you might consider using symlinking every single language file to the expected location. The version control support of Pootle will follow these links. Thus the meta directories of your version control system (e.g.: ''.svn/'' or ''CVS/'') do not necessarily have to be below your ''podirectory'' (see ''pootle.prefs'').

Hint for users of Pootle v1.0.x: the symlink feature does not work without this [[http://translate.svn.sourceforge.net/viewvc/translate/src/trunk/Pootle/indexpage.py?r1=6641&r2=6640&view=patch&pathrev=6641|patch]].


===== Updating =====
If you want to update the Pootle copy of the translations with the version that is currently in version control, a contributor with the 'update' right can click on the "Update" link for a file which will then perform the update process.  The project administrator needs to assign the "update" right.

When updating from version control there is the possibility that a third party could have changed the file (another translator accessing the version control directly could have made a change).  Traditionally in version control this would create a file with conflicts.  Those familiar with version control conflicts will understand that we can't afford to have that as we won't be able to resolve them.  Therefore Pootle will be conservative and will consider the version control system to be the authority and any conflicts in the local file get be converted to suggestions.  These suggestions then need to be reviewed by a translator with 'review' rights.

===== Committing =====
You can commit translation files from within Pootle.  In the case where authentication is required to submit the translation to version control (probably almost all relevant systems), there needs to be a non-blocking authentication method.  Pootle will not be able to commit if a password is necessary to complete the action. This unfortunately means that it will probably not be realistic for Pootle to commit with the project admin's credentials, as this will require his/her private key(s) to be on the Pootle server.

This usage scenario is more useful for people hosting their own Pootle server where they are able to setup one commit account on the version control server, or perhaps one account for each team.  A typical commit message when committing from Pootle will look something like this:

  Commit from GNOME Pootle by user Sipho.  80 of 100 messages translated (7 fuzzy).

So it is still possible to see who submitted what and when, and actually provides some useful statistics in the commit message.  A user must be assigned 'commit' privileges by the project administrator.  If the user has the correct privileges, they will see a "submit" link next to each file.

Possible ways of configuring non-interactive authentication are described in [[configure version control authentication]].

Feature suggestions:
  * provide user interface for personal authentication (e.g. password or keyfile upload) for one-time use or permanent storage (attached to this specific Pootle user)