Box Backup Source Code Repository

All source code is held on Github with public read (but not write) access. You can download the source as a ZIP file without installing anything, or install a Git client if you wish to contribute changes back to the project.

Continuous Integration

Our Github settings require that each pull request passes all of our test suite on all of our supported platforms before being merged. This means that you should be able to clone the master branch at any time and know that you are getting the latest and best stable version of Box Backup, to use either as a backup solution, or as a base for new development. See BuildAutomation for details.

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. The easiest way to do this is:

• Download the source as a ZIP file and extract it.
• Change into the directory boxbackup-master
• Follow the instructions under To Build From the Git 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 local editable copy of the source code, install a Git command-line client and use this command:

git clone https://github.com/boxbackup/boxbackup.git

Once you have done that:

To get a list of committed changes (which may be terse), run:

git log

To update your copy to the latest version, run:

git pull

Git is widely used but not especially friendly, so there is a lot of good documentation available. If you are not familiar with Git, you are advised to read it. If you have problems or questions, please ask for help on the mailing list, and we will be happy to help.

To Build From the Git Repository

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

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

If you are compiling on Windows, run the bootstrap command and then follow the Windows compilation instructions.

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: master

Web interface: https://github.com/boxbackup/boxbackup/tree/master

This is the main branch within Git 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. See the Workflow section below.

Release Branches

When an official release is made we will create a Release on GitHub with a new (higher) version number.

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?

Development Branches

All developers should work on unique branches, either in the main repository (if they have write access) or on their own forks. They should submit pull requests to merge their branches. Pull requests are likely to be merged automatically if tests pass.

Workflow

If you have a new feature or bug fix to submit, please fork the repository to your own GitHub account, check out your copy, create a branch, commit your changes to it, and submit a pull request.

Formal Release Procedure

What follows is the old formal release policy. I intend to move to user-driven rolling releases, so releases in future are likely to be less well tested than this.

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.]