Brief introduction to SVN

From Gramps
Revision as of 06:39, 3 May 2009 by Romjerome (talk | contribs) (Stable version 3.1.x)
Jump to: navigation, search

The development source code of GRAMPS is stored in the SVN repository. This helps synchronizing changes from various developers, tracking changes, managing releases, etc. If you are reading this, you probably want to do just two things with SVN: download latest source or the development version, or upload your changes.

Types of branches

There are two kinds of branches in the Subversion Repository: "trunk" and "maintenance branches".

The first type is a "trunk". There is only one trunk. All new feature development happens in the trunk. New releases never come from the trunk. The trunk for GRAMPS can be found here: https://gramps.svn.sourceforge.net/svnroot/gramps/trunk

The other type of branch is a "maintenance branch". There are many maintenance branches. A maintenance branch is created from the trunk when all the features for a release are complete. New features are not committed to maintenance branch. Releases only come from maintenance branches. The purpose of maintenance branches is to allow the line of code to stabilize while new features are added in trunk.

The first two digits of the GRAMPS version number are reserved to indicate the maintenance branch the code came from. The last digit indicates the revision from that maintenance branch. For example, 3.0.4 would indicate the 5th release from the 3.0 branch (3.0.0, 3.0.1, 3.0.2, 3.0.3, 3.0.4).

Here is a hypothetical example: Imagine that the current version of GRAMPS is 8.3.2. A new series of features has been added in trunk and are ready for release. A new maintenance branch is created from trunk named 8.4 (or possibly 9.0 depending on the nature of the new features). New features continue to be added in trunk that will not be included in the 8.4 series of releases, but will be included in the 8.5 series. Bug fixes continue to occur in the 8.4 branch until the code is deemed worthy of release. At that time, a release is tagged from the 8.4 maintenance branch and named 8.4.0. Some time after the release of 8.4.0, some bugs are found and fixed in the 8.4 maintenance branch. Those bug fixes are released as 8.4.1.

Stable version 3.1.x

  • To download the source to a /home/~user/gramps31 directory, you can use two methods to access the SVN repository:
  1. An http frontend to gramps SVN
  2. SVN access
  • To upload your changes, you have to have developer access.

The second method requires that svn be installed on your system (Debian/Ubuntu: apt-get install subversion; Fedora: yum install subversion). With the SVN method, type the following in the command line:

  svn co https://gramps.svn.sourceforge.net/svnroot/gramps/branches/gramps31 gramps31

You should see the downloading progress reported in your terminal. If you would like to update your source tree after some time, execute the following command in the top directory of the gramps31 source tree:

  svn update

To commit your changes, you can execute:

  svn commit -m "message describing the nature of the change"

Since uploading is a potentially dangerous operation, you have to explicitly obtain a write access to the SVN repository from Brian Matherly or Benny Malengier.

Unstable development: "trunk"

Also see: Running a development version of GRAMPS, and Getting Started with GRAMPS 3

Packages

Obtain it

As of January 2009, there are several versions of the gramps code in SVN. The development branch for small changes and bug fixes is 'gramps31' and 'trunk' has been created for the ongoing unstable version. If this talk of 'branch' and 'trunk' sounds confusing you might like to read the list message explaining branch and trunk.

To checkout a copy of the possibly unstable trunk to ./trunk:

  svn co https://gramps.svn.sourceforge.net/svnroot/gramps/trunk gramps32

To checkout a copy of the last branch GRAMPS 3.1 ./gramps31:

  svn co https://gramps.svn.sourceforge.net/svnroot/gramps/branches/gramps31 gramps31

To checkout a copy of the older stable GRAMPS 3.0 ./gramps30:

  svn co https://gramps.svn.sourceforge.net/svnroot/gramps/branches/gramps30 gramps30

To checkout a copy of the older stable GRAMPS 2.2 ./gramps22:

  svn co https://gramps.svn.sourceforge.net/svnroot/gramps/branches/gramps22 gramps22

Prepare it

Now go into the gramps30 directory and type

./autogen.sh

You will get warnings of missing packages that GRAMPS needs to build from source. The most common warnings are, that you miss the gnome-common package if you run under Linux and Gnome. If you run Ubuntu install via Synaptic the 'gnome-common' (version 2.20.0-0ubuntu1): common scripts and macros to develop with GNOME: gnome-common is an extension to autoconf, automake and libtool for the GNOME environment and GNOME using applications. Included are gnome-autogen.sh and several macros to help in both GNOME and GNOME 2.0 source trees. Install these and/or any other missing packages, read INSTALL and README file in the gramps30 dir for pointers. An important library is also libglib2.0-dev. Check whether your system has this package installed. This will execute the make command too. If not, type after the above

make
Gnome-important.png
Warning

Do not install the development version. That is, do not type sudo make install.

Building with Fedora 8 - 10

These are the packages you need:

yum install gnome-common intltool glib2-devel gnome-doc-utils gcc emacs gettext subversion make rcs

Now you can run the ./autogen.sh script and then make.

Windows

This step appears unnecessary on windows? See Installation#Installing_from_source_code_on_Windows

Run the development version

As you should not install the development version, how can you try it out? Easy, just type the following in the gramps30 directory

python src/gramps.py


Gnome-important.png
warning

Do not open your existing databases with gramps 3.0, it might destroy your data, and will make it impossible to use the data in the stable version 2.2.x. To try it out, export your database to a gramps xml file, eg test_version_3.0.gramps, create a new family tree in GRAMPS 3.0, and import this xml file.

Where for bugs?

The bug tracker has in the right top angle different projects. Choose project 3.x and submit an issue.

Useful things to know

Subversion commands

svn help add
svn help commit
svn help log

Adding files to repositories requires you to set some properties to the files and to have a sourceforge account. See svn help propset. You can use the propget on existing files to see how you should add it. A convenient way is to common files to your ~/.subversion/config file, eg in my config I have:

[miscellany]
enable-auto-props = yes

[auto-props]
*.py = svn:eol-style=native;svn:mime-type=text/plain;svn:keywords=Author Date Id Revision
*.po = svn:eol-style=native;svn:mime-type=text/plain;svn:keywords=Author Date Id Revision
*.sh = svn:eol-style=native;svn:executable
Makefile = svn:eol-style=native
*.png = svn:mime-type=application/octet-stream
*.svg = svn:eol-style=native;svn:mime-type=text/plain

svn2cl

The Gramps project does not keep a ChangeLog file under source control. All change history is captured by Subversion automatically when it is committed. A ChangeLog file is generated from the SVN commit logs before each release using svn2cl. Developers should take care to make useful commit log messages when committing changes to Subversion. Here are some guidelines:

  • Try to make a descriptive message about the change.
  • Use complete sentences when possible.
  • When committing a change that fixes a bug on the tracker, use the bug's number and summary as the message.
  • When committing a patch from a contributor, put the contributor's name and e-mail address in the commit message.
  • It is not necessary to put the names of the files you have modified in the commit message because Subversion stores that automatically.

Other usage tips

Browse svn

An alternative to the command line tools to view the svn repository is the online interface.