From Mageia wiki
Revision as of 06:52, 2 December 2013 by Filip (talk | contribs) (Checkout the resource: svn 2 git fix)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to: navigation, search


About SVN

SVN is a shortened name for Subversion. Subversion is an online repository system for keeping track of changes made to files, a versioning system. The repository itself is called an SVN repository. That means that it is a place to store files and track any changes made to them. It does this automatically, so you don't have to keep track of changes yourself.


To work with the svn repository you need to use some simple commands. You also need to make sure to have access to those commands by installing the subversion package if it isn't already installed on your system.


You can install it either through the package manager or using the command line using the commands below. The first is to change to the root user and the second will install subversion. Your prompt will change from a $ to a # when you change to the root user, as is shown.

$ su -
<enter your root password>

# urpmi subversion

When it has finished, log out of root with..

# exit

SVN works by downloading the files or directories you want to work on to your local machine. You then make the changes you want to make and upload them again to the repository. It is a very powerful tool and there is alot which need not concern you but if you wish you can learn more about it in the svn manuals (see also a visual guide) or by typing man svn.


There is some terminology which might seem strange at first too. When you download something from SVN you tell it to checkout those files and when you have finished editing you commit the changed files back. Not everybody has permission to commit to repository.


If you want to work on translations directly in the soft svn, you will need the following commands:


Commands for everyone

Checkout the resource

 $ svn co svn://svn.mageia.org/svn/soft/PATH TARGET_DIR

In this command line you have to replace PATH with the path of the resource you would like to download, TARGET_DIR can be set to whatever you want, it is just a directory name on your local disk.


A list of resources can be found here.


This will perform an anonymous checkout, anybody can do that, you don't need any account whatsoever. You can't commit changes you have made in your working directory back to the repository though, so you have to get your changed files to someone who has write access to the SVN by whatever means you have (preferably to your own language translation team (see the list of translation teams here, or if there is no team for your language, contact the common translation mailing list).


If you do have write access to Mageia's soft svn, please use the following command line instead:

 $ svn co svn+ssh://your_username@svn.mageia.org/svn/web/PATH TARGET_DIR



Update of an existing resource

If you have already checked out a resource, you can update your local copy by changing into your working directory and using the following command line

 $ svn up



Check a resource for changes

If you want to check an existing resource for changes, you can use the following commands. All of these should be used from inside your working directory.


Check for changed files in your working directory:

 $ svn st

Any changed files will show with an "M" at the beginning of the line.


Check for the changes you have made in your working directory:

 $ svn diff


Check for changes on the server:

 $ svn st -u

Files changed in your working directory will be marked with an "M", files changed on the server will be marked with a "*".
Files that incorporate local changes as well as changes on the server show both. Be careful with those ones.
If you see a line beginning with a "C", it shows a conflict svn can't resolve on it's own, you will have to do it manually.


Note:
Even if svn can merge changes on its own (files marked with a "*" and an "M"), it doesn't mean the result will be good because svn itself doesn't know the syntax and logic of the files it's been used on.
It is better work on those manually as well.


Check for who did what:

 $ svn log

The output of this can be very long, so you might want to pipe it into less:

 $ svn log | less



Editing po files

First of all, never edit a pot file, they are automatically generated from the source code and used as a reference only. If you do find an error in a string, please report it on the i18n mailing list.


For editing po files, you can use any text editor but it is better to use a specialist tool like Lokalize, Virtaal, GTranslator, OmegaT or poedit, because then you can be sure you won't create syntax errors.

Thorough description of the translation file formats and the translation tools can be found in FOSS localisation manual.





Commands for people with write access

Commit changes to the server

Again, you have to change into your working directory then check for changes and conflicts (see above). If everything is fine, check the changed files for syntax errors with the command below:

 $ msgfmt -c file.po


Then you can commit your changes using:

 $ svn ci -m "COMMIT_MESSAGE"

The commit message should make sense to others, e.g. "Updated German translation" will do nicely.


You can also try graphical tools, like Kdesvn or RapidSVN.

Add new languages to a resource

If you want to add a po file for a new language, just copy the pot file to xx.po (or xx_YY.po, if it is a language with several flavours), then add it to the svn using

 $ svn add xx.po

Please also let others know by sending an email to the i18n mailing list to say that you added the file.


Note:
The file will only be uploaded if you commit it to the server, just adding it to your local working directory is not enough.



Setting up ssh for using svn with write access

If you want to use our svn with write access by use of ssh public key (being able to commit files easier), there are some things you need to do:

  • Ask on i18n mailing list for commit rights.
  • Add your ssh public key to your identity account see here
  • Edit ~/.ssh/config (or create it, if it does not yet exist)



Getting svn commit rights

As a rule, each language should have two people who are able to commit changes, but there are exceptions:

  • language teams with only one person obviously don't have two people who can commit changes
  • Some i18n team members are also doing something else towards Mageia development and may have svn access already
  • Some really big teams might need additional people with write access

If you are just joining Mageia i18n team and your language does not have anybody who can commit at that time, it may will still take some time for you to get write access to the svn. After all, we don't know who you are and it is a trusted position.


If you are new to the Mageia community, you can still begin working by checking out the files anonymously and sending them to the i18n mailing list for someone else to commit them.


This does not mean we mistrust you personally, it's just a precaution.

Adding your public key

If you are wanting write access to the svn, you may want to add your public key to your Mageia identity account. There is an input field there to do so.


You can create a key pair by using

 $ ssh-keygen

This will create a key pair in your ~/.ssh/ directory. One private key and one public. Please make sure nobody but you knows your private key.


Then open the public key (the one ending in .pub) and copy & paste it into the field in your Mageia identity account.

Edit your ssh configuration

It makes life a bit easier if you add some information about your ssh access to the Mageia svn into ~/.ssh/config. That way you don't have to add your username to "svn co" commands and so on.


Here is the content you basically need:

 Host svn.mageia.org
       HostName svn.mageia.org
       User YOUR_MAGEIA_IDENTITY_USERNAME
       IdentityFile ~/.ssh/id_rsa


Note:
id_rsa is the default name of your ssh key, if you chose another name for your key you must of course change that here as well.