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.

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.3.x ==

+

== Stable version {{stable_branch}} ==

* To download the source to a /home/~user/gramps33 directory, you can use two methods to access the SVN repository:

* To download the source to a /home/~user/gramps33 directory, you can use two methods to access the SVN repository:

# An http frontend to gramps SVN

# An http frontend to gramps SVN

Revision as of 10:26, 20 April 2012

The development source code of GRAMPS is stored in the SVN repository at sourceforge [1]. This helps synchronizing changes from various developers, tracking changes, managing releases, etc. If you are reading this, you probably
want to do one of two things
with SVN: either download the latest source or the development version,
or else upload your changes (if you have write access to the repository)
or make a patchfile (if you don't have write access).

maintenance - 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. Maintenance branches can be found here: https://gramps.svn.sourceforge.net/svnroot/gramps/branches/maintenance

geps - These are meant for development of Gramps Enhancement Proposals. Most of the time GEPS are developed in the trunk. Occassionally a GEP will require extensive reworking or long periods when the code base is ususable. In these cases a branch in geps can be used as a temporary development area. Once the hard work is done the change should be merged into the trunk and the geps branch should be removed. greps branches should follow the naming convention gep-<###>-<descriptive text> e.g. gep-013-server. Please read the #Working with development branches section for help with managing these branches.

sandbox - These are meant for experimentation purposes. If you want to explore some ideas or try out some changes that would break the trunk or prototype something that has not made it to a GEP you can create a sandbox branch. These should be short lived. As soon as you have finished please remove the branch. We reserve the right to remove any sandbox branch that has not been touched for 12 months. sandbox branches should use the following naming convention <username>-<descriptive text> e.g. hippy-prototype-rss-idea. Please read the #Working with development branches section for help with managing these branches.

Release tags are created in the tags directory. 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 4.1

==

To download the source to a /home/~user/gramps33 directory, you can use two methods to access the SVN repository:

An http frontend to gramps SVN

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:

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 gramps33 source tree:

Packages

Obtain it

There are several versions of the gramps code in SVN.
The development branch for small changes and bug fixes is gramps33 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.

Prepare it

Now go into the trunk 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 trunk dir for pointers. An important library is also libglib2.0-dev. Check whether your system has this package installed.
A list of package requirements can be found on the Installation page.
This will execute the make command too. If not, type after the above

make

Warning

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

Windows

Run the development version

As you should not install the development version, how can you try it out? The current Python version required to run Gramps trunk is officially python2.6 as of July 2010. Easy, just type the following in the trunk directory

python src/gramps.py

or

python2.6 src/gramps.py

warning

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

Where for bugs?

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

Making a patchfile

If you do not have write access to the repository, you can make a patchfile with your changes. This is a text file which can then be sent by email to somebody, or posted/uploaded to the bug tracker (against a bug you are fixing or a feature request which you are solving for instance), etc.

These instructions tell how to make a patchfile against trunk, so that your changes are added to the next major release of Gramps. (To make a patchfile against a branch the process is similar, with some slight changes.)

To then use SVN to make a patchfile, first go to the top of your changed tree

cd /path-to-your-gramps/trunk

and then tell SVN to record/document/itemize the changes to your edited file(s)

svn diff > ~/some-descriptive-name.patch

with the resulting file being the patchfile you just made.

If you want to add a new text file, such as a new python module,
you can include that in your patchfile by first doing, e.g.,

svn add dir1/dir2/newfile.py

before you do the "svn diff" as described above. (This method
does not work for non-text files such as image files; be warned.)

Note also that if you add a file in this manner, depending
on what was added and where it was added, you may also have
to modify the corresponding Makefile.am file.

I do not know how to make a patchfile which documents
a deleted file which "patch" will then correctly delete.
(If you know how, please add it here.) When SVN version 1.7
is released (scheduled for 1Q2011 as I write this), then there
will be a "svn patch" command which should do that.

Working with development branches

If you are using a geps or sandbox branch you need to take care when merging changes from the trunk and back to the trunk. Please take a few minutes to read the Basic Merging section of the Subversion book.

IMPORTANT: please use an svn client that is version 1.5 or newer. The merge tracking functionality only became available in 1.5. If you use an earlier client you will have to deal with all the revision tracking of merges by hand - not fun.

IMPORTANT: if you see a message that talks about from foreign repository it is probably because your working copy was checked out from an http:// url but you are merging from a https:// url or visa versa. Just be consistent about why you use. Don't merge from foreign repository because svn will not be able to manage the revisions correctly.

NOTE you will see some modification to files that you are not expecting. If you look at these you will find that they are modifications to svn properties. These are used by the merging tool to keep track of what changes have already been applied.

The developers reserve the right to remove branches that have been
dormant for more than 1 year.

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:

Ignore files

You should on creation of new directories set the svn:ignore property:

svn propedit svn:ignore src/new_dir/

and there set at least:

*.pyc
*.pyo
Makefile
Makefile.in

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.