SVN

Subversion (SVN) is a free version control system (VCS). It allows users to keep track of changes made to any type of electronic data, typically source code, web pages or design documents. Subversion is currently a popular alternative to CVS (another widely used VCS), particularly among many open source projects.

In the context of the PhpGedView project, a central SVN repository stores and maintains all the PhpGedView source code. PhpGedView developers who have write access to the repository can make changes to the code and commit them to the repository for everyone else to see and benefit from.

SVN has at least one big advantage over CVS, in that it is capable of versioning directories. If you have ever used CVS you will know about its inability to rename or delete directories once they have been created. If you are not familiar with CVS, then you don't really need to know about the difference.

Repository Layout

PhpGedView uses a standard repository layout:

phpgedview/
  |
  |___branches
  |
  |___tags
  |
  |___trunk
  |
  |___vendor_branches
  |
  |___vendor_tags

Trunk

The trunk directory contains the latest stable version of PhpGedView plus any bug fixes that have been addressed since the latest official release (4.2.4). It also includes new development code that is ready to be tested (Beta code). Longer term development work takes place away from the trunk in a branch. This means that the source code in the trunk remains reasonably stable and is most likely the directory from which you would checkout code. However, the code in the trunk directory IS still BETA,. It changes constantly, and will occasionally have potentially serious bugs. It is not recommended for production sites. It provides a valuable tool for more experienced users to test the development team's work, and provide prompt feedback before the code is publicly released.

The trunk can be checked out into a phpgedview directory using:

svn checkout https://phpgedview.svn.sourceforge.net/svnroot/phpgedview/trunk/phpGedView phpgedview

Tags

The tags directory contains copies of the source code from specific times. Whenever a release is made, the code is "tagged" by copying the source from the trunk to a suitably named subdirectory of tags. For example, there exists a stable-4.1 tag which is the source code as it was at the time of the 4.1 release.

Data in the tags directory should NEVER be modified!

The PhpGedView v4.1 code can be checked out into a phpgedview directory using:

svn checkout https://phpgedview.svn.sourceforge.net/svnroot/phpgedview/tags/stable-4.1 phpgedview

Branches

A branch may exist for the next major release of PhpGedView and is where any major re-development takes place. This is done to preserve the stability of the trunk so that more users can obtain working code from SVN. The code in branches is unstable, may not work and contain partially implemented features. Unless you are a developer you probably do not want to get code from a branch.

The current development branch is the phpGedView-4.3.0 branch and can be checked out into a phpgedview directory using:

svn checkout https://phpgedview.svn.sourceforge.net/svnroot/phpgedview/branches/phpGedView-4.3.0 phpgedview

Third Party (Vendor) Code

Good software design/programming makes use of existing code where possible rather than "reinventing the wheel". PhpGedView makes use of code from several third parties (vendors) and it may be modified in order to incorporate the design/layout of PhpGedView and we may even fix bugs. We also want to keep our vendor code reasonably up-to-date as the vendor make new releases containing new features and bug fixes etc. In order to allow us to do this with as little fuss as possible, we maintain a copy (unmodified by us) of the vendor's source code using vendor branches and vendor tags. Code is NEVER modified on either the vendor branches or vendor tags by the PhpGedView team. Instead, code is copied from the the vendor branch or vendor tag to the required location in the PhpGedView trunk or development branch for the first import of a vendor release. On subsequent vendor releases a diff is taken between two vendor tags and applied to the relevant location on the PhpGedView trunk or development branch.

Vendor Branches

A vendor branch contains a copy of the unmodified source code from a third party (a vendor) and is generated by importing a new releases made by the vendor. A vendor branch is essentially a trimmed down version of the development for the vendor source code.

Vendor Tags

Each vendor tag is generated during the import of a new vendor release into the vendor branch, and maintains an easy to refer to snapshot for a particular vendor release.

Revisions

The SVN repository maintains its own internal revision number. This is different, and often confusing for people more familiar with CVS since CVS maintains independent version numbers for each file in its repository.

Each time a developer commits code successfully, the repository's internal revision number is incremented. Having a repository-wide revision number means that each revision number is effectively a "tag" representing the state of the repository after each commit. In fact the revision numbers can be used to checkout the repository (or part of it) at different times using the same revision number and the exact same source code with be retrieved.

Repository Access

In order to access an SVN repository, you will need to install a Subversion client - these are available for many operating systems. The PhpGedView SVN repository is hosted at SourceForge.

Only developers that have been granted write access to the repository are able to commit changes; everyone else is able to read/checkout source code from the repository.

Common SVN Errors

A common error seen during checkout is:

svn: Can't convert string from 'UTF-8' to native encoding:

This is because PhpGedView supports some languages that use characters that are not recognised by your computer's locale (see the Languages and Character Sets FAQ for some more info). Therefore, you should set your computer's locale to be UTF-8 compliant. On UNIX/Linux based Operating Systems, you should be able to check your current locale by typing the following on a command line:

locale

You might get something like this returned if your locale doesn't support UTF-8:

LANG=en_GB
LC_CTYPE="en_GB"
LC_NUMERIC="en_GB"
LC_TIME="en_GB"
LC_COLLATE="en_GB"
LC_MONETARY="en_GB"
LC_MESSAGES="en_GB"
LC_PAPER="en_GB"
LC_NAME="en_GB"
LC_ADDRESS="en_GB"
LC_TELEPHONE="en_GB"
LC_MEASUREMENT="en_GB"
LC_IDENTIFICATION="en_GB"
LC_ALL=

By issuing a command similar to the following (this changes the locale to Great British English with UTF-8 support), you can add UTF-8 support:

export LANG=en_GB.UTF-8

Internal Links

• Using SVN for PhpGedView

External Links

SVN Official Website

http://subversion.tigris.org/

SVN on Wikipedia

Subversion_(software)

Free Online SVN Book

http://svnbook.red-bean.com/

SourceForge SVN Documentation

Version control for non-programmers with Subversion

Command-line SVN client

TortoiseSVN

SVN

Graphical SVN Clients

TortoiseSVN - Official website

Subclipse - Official website for the Eclipse plugin