wiki:SourceCodeRepository

Version 20 (modified by Achim J Latz, 9 years ago) (diff)

Added special case for compiling with MingW (./infrastructure/mingw/configure.sh instead of ./configure)

Box Backup Source Code Repository

All source code is held in Subversion with public read (but not write) access. You must install the Subversion client in order to download one of the development versions listed on this page.

The repository location is https://www.boxbackup.org/svn/box

Testing the Latest Version

If you experience a problem, and a developer checks in a fix, or additional debugging code to help diagnose it, they may ask you to try building and running the latest trunk version. To do this, you will need to:

  • Install a subversion client for your distribution, or if you can't find one, get it from here.
  • Run this command to download the trunk version: svn co https://www.boxbackup.org/svn/box/trunk/
  • Change into the directory trunk
  • Follow the instructions under To Build From the Subversion Repository below.
  • Temporarily stop any existing bbackupd and bbstored processes.
  • Run the command release/bin/bbackupd/bbackupd or release/bin/bbstored/bbstored, depending if you are working on the client or the server.
  • Optionally add the options -kVT to the command line to help with debugging (run in foreground with extra logging).
  • Optionally add strace -s 128 or gdb to the start of the command to trace or debug the process.

Examples

To get a list of committed changes (which may be terse), use this command:

svn log https://www.boxbackup.org/svn/box/trunk/

To checkout the latest development version (trunk), cd to your working directory, and then use this command:

svn co https://www.boxbackup.org/svn/box/trunk/

If you are updating a previous working copy of Box Backup, cd to that same working directory, and then use this command:

svn update 

However, if you are switching your working copy from the old bbdev.fluffy.co.uk repo, then the command goes like so:

svn switch http://bbdev.fluffy.co.uk/svn/box/trunk https://www.boxbackup.org/svn/box/trunk

Branches or the repository root can be accessed by modifying the URL.

To Build From the Subversion Repository

Currently you need autoconf and automake installed. Build like so:

./bootstrap && ./configure && make && echo "Finished."

In case you are using MingW under Windows, you should use the following commands:

./bootstrap && ./infrastructure/mingw/configure.sh && make && echo "Finished."

If you have any error messages, or the last line of output doesn't say Finished, please contact us for help.

To Install the Newly Built Version

If you are updating a previous installation, you should kill any running services, like so, as root:

killall bbstored

and/or

killall bbackupd

To install or update the executables in /usr/local/sbin, use this command, as root:

make install-backup-server

and/or

make install-backup-client

Note that on OpenBSD, you also need to install the metaauto package, then set version environment variables before running bootstrap to tell it which version to use.

export AUTOMAKE_VERSION=1.4  
export AUTOCONF_VERSION=2.59

Structure of the Repository

In order to maintain structure for the Box Backup repository the following layout is used for holding all work.

Main Branch: trunk

Location: https://www.boxbackup.org/svn/box/trunk

This is the main branch within SVN which always works towards the next release. You should not develop directly on this branch but work on various other branches aimed at the work which is underway. Once agreed with the team then any changes are merged into this branch for any uncoming release.

It is acceptable to commit bug fixes and other small changes directly to trunk so long as there is consensus on the change. But please note: this branch should compile and work at all times.

Release Branches

Location: https://www.boxbackup.org/svn/box/RELEASE/<version>

When an official release is made it is tagged by copying it into this directory and renaming it to the version number. If for any reason the release is remade the copy will be updated. No commits should ever be made directly to the release copies.

DISCUSS: Release maintenance branches??

  • Mebourne: Do we really have the developer time to maintain them properly?
  • Ben: Could we take the lazy approach of asking users to use the latest version?

Snapshots

Location: https://www.boxbackup.org/svn/box/snapshots/<version>

Monthly snapshots of the development code in trunk are created here. Information on the snapshots is available on the Snapshots page.

Feature Branches

Location: https://www.boxbackup.org/svn/box/features/<feature-name>

This directory holds branches dedicated to the development of specific new features. There will be one branch here for each significant new feature being worked on. The branches here will be short lived, when a feature is complete and merged into trunk they will be removed.

Before committing onto one of these branches obtain agreement from the developers working on that feature. These branches may or may not compile and run at any given time, as the relevant developers wish.

The definition of feature here is quite loose - a new platform port would be considered a new feature and would belong here. Current feature branches are:

Personal Branches

Location: https://www.boxbackup.org/svn/box/personal/<username>

For any experimental work, complicated bug fixes, small new features, or anything else you want at all, you are welcome to have your own private branches. Changes in a personal branch can be merged into one of the other branches with the agreement of those concerned.

Developers' branches are personal, not private. You should feel free to compile, test, and run changes developers are working on, they are very likely to be happy for the feedback. But note that nothing is guaranteed and they may not compile at all, even on the developer's favourite platform.

A developer is free to have just one branch of their name, or make as many branches under their directory as they see fit, within reason.

Workflow

Bug Fix

Commit to trunk if obviously correct. Otherwise either send a patch to the -dev mailing list or use a personal branch for review.

New Feature

Create a feature branch. As soon as possible, get changes merged into trunk after review by other developers.

Changes should be incremental, but not trivial, and not break anything. If the changes are too small, then the reviews are too frequent and it becomes difficult to keep everything relevant in mind. If the changes are too large, then the review is too arduous to be completed in a timely manner by volunteer developers.

Tests

No test code may be deleted. Test code should only be modified if completely unavoidable.

Formal Release Procedure

When a release is formally made the following procedure should be followed to ensure quality releases are maintained.

All branches with all relevent changes for that release should be merged into trunk. Once this has been performed it should be checked out and tested on the main support platforms (BSD, Linux, Solaris, Win32, etc). Once the release manager is happy with the merge then the branch should be tagged as a formal release.

Once a formal release is created then makedistribution.pl should be used to create an official release tarball (to add license info etc).

As it is simple to break a release, the following tests should be carried out:

  1. Large file backup and restore
  2. Backup of changed files and restore of
  3. Confirmation of successful compilation and all unit tests pass on all support platforms. [Some unit tests failures may be allowed if they are well understood and harmless.]

Further Information

The Subversion home page is http://subversion.tigris.org/

The Subversion manual is http://svnbook.org/