$Revision: 11035 $
| Revision History | ||
|---|---|---|
| Revision 1.6 | 2009-03-29 | hosny |
| Updated the document for SVN | ||
| Revision 1.5 | 2004-04-12 | elzubeir |
| Removed references to akka (obseleted project) | ||
| Revision 1.4 | 2004-04-14 | elzubeir |
| Added info on how to generate encrypted password. | ||
| Revision 1.3 | 2004-04-13 | elzubeir |
| Restructured document outline. | ||
| Revision 1.2 | 2004-02-17 | elzubeir |
| Updated information on account requests. | ||
| Revision 1.1 | 2004-02-17 | elzubeir |
| XML'ized SGML version of document. | ||
Abstract
This document is meant to show you how to access and use the Arabeyes SVN repository.
Table of Contents
Subversion (SVN) is an open source version control system. Using SVN, you can record the history of your source files and/or documents. It does not check your work for you, but it is a good safeguard against disasters, should they happen.
This HOWTO is not going to teach you everything about SVN, but it is designed to be a quick guide to using the SVN Repository. For more information on using SVN you can check:
Version Control with Subversion - http://svnbook.red-bean.com/
There are many free svn clients you can download. If you are a Linux/Unix user, then you probably have it as part of your standard install. If you are a Windows user, you have two options:
Cygwin bash shell - http://sources.redhat.com/cygwin/
Cygwin is a UNIX environment for Windows, which comes with a command-line svn client.
TortoiseSVN - http://tortoisesvn.net/
TortoiseSVN is a graphical svn client for MS-Windows
It is strongly recommended that you use the linux/unix svn client. However, if you must use Windows, Cygwin bash shell is what we recommend. This HOWTO assumes that you either know the equivalent of commands on the graphical front-end, or use the command-line interface.
There are two types of SVN access: Anonymous (read-only access; open to all), and developers (read/write access; restricted).
Anonymous access is the same as the account based access, except that you would not be able to commit files to the SVN repository. You don't need a username or password.
$ svn checkout https://svn.arabeyes.org/svn/module
In the above example, be sure to replace the module with the approrpriate module name from the SVN repository.
In order to commit to the SVN server, you will need to have an account (username and password).
SVN write access is not lightly given. You may want SVN access if you are:
Starting a new project
Contributing to an existing project
If you are requesting an account to start a new project, then your account will be approved once the Core Management Team has apporoved your project. However, if you are requesting an account to contribute to an existing project, then the coordinator of that particular project will have to approve your account creation first.
In order to request SVN write access on Arabeyes' SVN repository, you must file a bug-report via bugs.arabeyes.org. It is also expected that you have read this document and know exactly why you are needing SVN access.
If at any point you wish to change your SVN password, you will need to email the SVN administrator with an encrypted version of your password. This can be done by taking the output of one of the following methods:
$ perl -e 'print crypt("PASSWORD", XY),"\n"'
Or
$ python -c 'import crypt; print crypt.crypt("PASSWORD", "XY")'
Where PASSWORD is your password and XY are two random alphanumeric characters of your choice.
After getting your account, you can start checking the files from the SVN reposetory as follows:
$ svn --username=ccount --password=pass checkout https://svn.arabeyes.org/svn/module
In the above example, be sure to replace the account and pass with your username and password respectively, and module with the approrpriate module name from the SVN repository.
The word 'checkout'[1] in SVN refers to downloading the files to your local machine. It is analogous to you checking out a book from the library, however you are not only expected to bring it back, but update it too!
$ svn checkout https://svn.arabeyes.org/svn/projects
The above command will create a directory structure on your computer, which will have everything that is under projects on the SVN repository. So, let us say we don't want everything under projects. Let us assume that you want the bicon project source and everything for it.
$ svn checkout https://svn.arabeyes.org/projects/bicon
When you 'commit' a file, you are essentially uploading it to the repository. So, now that you have downloaded the files and have made some changes, you would like to put it back on the repository.
For the sake of this example, we will say you are modifying the file 'myfile.cc'. Here is how to commit it:
$ svn commit myfile.cc
If the file does not already exist, and you are creating a new one then you need to 'add' it first. Here is how:
$ svn add myfile.cc $ svn commit myfile.cc
The first command creates an entry for the file in the repository, and the second one actually makes the commit to the repository (making it available). If the file already exists and you are making changes to it, you can ignore the 'svn add' command. For more help do 'svn help' from your linux/unix prompt.
Once you execute the commit command, a text editor will be launched so you can enter a brief log of what you have done. This is especially useful for others who are working on the same project - as it gives them an insight of what you have changed without having to look through the file(s). The editor is usually vi, on most Linux/Unix systems.However, that is not necessarily the case. It is whatever you have the environment $EDITOR set to. To find out what it is set to in your environment, do:
$ env | grep EDITOR
In order to get into insert mode under VI, press i. Then you may continue to type in your brief log. Once you are done, press ESC (which will get you out of the insert mode), and enter :wq then hit return. This will write (to save) and quit. Your commit will then be executed.
When you have made changes that span across multiple files it is best to commit them in one batch, as opposed to doing so one at a time. That is for 2 main reasons:
Minimizes on the amount of svn notification mail that goes out to everyone on the 'svn' list, whenever a commit is made.
Most of the time the multiple files changed involve the same issue. For
example, if the two files test.cc and
test.h were changed, it is unnecessary to commit them
individually.
There are two ways of committing multiple files.
$ svn commit file1 file2 file3
Or you can simply let it recursively do it:
$ svn commit
The first gives you more flexibility in what the files are exactly, whereas the latter simply commits any file that has changed in the current directory and all subdirectories.
New directories are either created as part of an existing project or to create a new module for a newly imported project. Before creating any new directory, please always consult the SVN administrator. This is particularily important to avoid redundancy and maintain an ordered organization.
This does not apply to those who are module owners. For instance, if the
author of X decided to add
X/yz/ to his X/ directory, it does
not require any approval from the SVN administrator.
Directories are added, just like files, using svn add, it works recursively on directory content as well, so you can added directories containing other files or directories.
It goes without saying that it is very important to enter a useful and meaningful comment on commits.
Translation (PO's):
When committing .po file(s) always make sure the
comment includes the output of:
$ msgfmt --statistics file.po [2]
This is to avoid commit logs such as "translated a little", which mean very little if anything at all.
Development Source Code:
Comments on source code commits may be a little easier (as the types of changes will vary). Always make sure you keep track of the changes you make AS you make them, so you remember what they are before committing.
An example of a bad log is: "I made a few fixes". What fixes? If you can't remember what you did anymore, then do a diff of the changes, go through it and note the changes you made.
Documents:
Generally documentation comments are inevitably going to be vague. If the document is small, that's not a problem. If it is not, point to the location you made the changes to. For example: "Chapter 3, Section 4 - Re-wrote the second paragraph for clarity" is a good comment.
There is a very simple rule to follow on this one. Any file that is generated by a program from another file that resides on SVN should not be put on SVN. That is unnecessary redundancy.
Compressed files (gzip/bzip2/Z/etc) should not be put on SVN in their compressed/tarred forms.
Generally the only binary type of files acceptable on SVN are graphics images and audio files. Every other file type is expected to be text.
Since there are others who are likely to have made changes during the course of the project, your local working copy of the svn contents may not always be up to date. In order for you to keep your copy up-to-date you can:
$ svn update
Note that this can only be done while you are inside the directory you are intending to update.