howto • svn

How To Deal With Subversion

Subversion is the software that manages the Gambas source code repository on http://sourceforge.net.

A repository is exactly like a file system, but a file system that keeps all modifications.

Gambas repository organization

The Gambas repository is divided into three main directories:

/trunk This directory contains the sources of the development version. Its aim is becoming the next major version of Gambas.
/branches This directory contains the sources of the stable version. There is one sub-directory for each stable version. Their aim is becoming the next minor version of the stable version.

One can find there some other development related to Gambas that are designed outside of /trunk, and that will be merged with it in the future.

/tags This directory contains the sources of each released version of Gambas. There is one sub-directory for each version. They are just archives, and can be used for recreating a package of a past version.

You can read the repository contents from the web at this address: http://sourceforge.net/p/gambas/code

Compiling the Subversion repository.

First, you have to download the sources.

Everybody can make a copy of the repository on his hard disk by using the following command:

$ svn checkout svn://svn.code.sf.net/p/gambas/code/gambas/trunk

Or:

$ svn checkout svn://svn.code.sf.net/p/gambas/code/gambas/branches/3.5

for a stable version.

Once done, you do the compilation exactly the same way as when you compile a source archive downloaded from the website. See Compilation and Installation.

Getting a write access to the Gambas repository

If you want to do actual development or translations for Gambas, then you need a write access to this repository.

To get a write access to the Gambas subversion repository, just create a user account on sourceforge.net, and ask me to grant a write access to the user you just have created.

Then create a working directory (name it as you like):

$ mkdir ~/gambas

And checkout the repository this way:

$ cd ~/gambas
$ svn checkout --username=<user> svn+ssh://<user>@svn.code.sf.net/p/gambas/code/gambas/trunk

If you don't use the svn+ssh protocol, your won't be able to commit.

How does it work?

Each time anything is changed in the repository, the revision number is incremented, and a revision log is attached to it. The revision log is edited by the person doing the modification.

All is done with the svn command.

Someone may have modify some things between the time you checked out and the time you committed. So before doing a svn commit, you should do a svn update.

Writing revision log

When you commit, you must specify the editor used for editing the revision log in the $EDITOR environment variable. For example:

$ EDITOR=gedit svn commit

Note that you cannot modify a revision log after the commit. It seems that sourceforge has disabled this feature. So, be careful!

Revision log format

THIS IS IMPORTANT!

I want to have a standard way to write commit messages, so that ChangeLog can be almost automatically generated.

The format is the following:

'BUG' is for a fix, 'NEW' for a new feature, translation, or updated ones, and 'OPT' is for an optimization.

Slots are the name of the component in uppercase, or one of the following:

All lines had to be lower or equal than 76 characters.

This it not needed anymore! Lines now can be as long as you want.

If a changelog modification is more than one line, you must use a two space indent.

Void lines are ignored.

All other lines won't go into the changelog.

Examples

I did this thing, And this won 't go into the changelog.

[GB.QT]
* BUG: I fixed this bug.
* New : I made this very long modification....
  And it takes more than one Line To Write it.

This won 't go into the changelog too.

[GB.SDL]
* BUG: What an awful bug!

[GB.GTK]
* New : I Finally finished the component: - )

Please follow this scheme. It would be really cool...

Commit mailing-list

There is a mailing-list that gets a mail each time somebody commits a new revision. So this way you always know if you have the latest revision on your hardisk or not.

To subscribe to this mailing-list, go to the mailing-list page on the web site. The name of the mailing-list is gambas-devel-svn.

State of your repository copy

To get the state of your repository copy, run the svn status command.

Each state is described with one or more letter:

See above for more information about conflicts.

Caveats

No automatic project structure tracking

You must tell subversion if you add, delete, rename or move a file. You do that with the commands:

Forgetting to use svn add is a common mistake. I know what I'm talking about :-)

Conflicts

Somebody can modify a file in the repository, while you have modified the same file on your hardisk. This is a conflict, and svn will tell you when running svn update, or the svn status command.

Each time there is conflict, svn tries to solve it automatically, by merging your own changes with the changes made by other people.

If the merge succeeds, your will get a file with a 'G' state character.

If the merge didn't succeed, your will get a file with a 'C' state character. Then you will have to solve the conflict by hand:

Once done, you will tell svn that the conflict is solved by running the svn resolved command on the file in conflict.

Is there any risk?

Normally there is no risk, as everything is archived, and so you can always go back in time.

Moreover, if you work on a Gambas project inside the repository, the development environment can deal with all svn command for you. Go to the versioning tab in the project property dialog, and you will find buttons that allow you to update the project, commit it, and cancel your modifications.

If you have made something weird, you can use the svn revert command. It will revert your local copy to the state of the last checkout or update.