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.
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
- Follow the instructions under To Build From the Git Repository below.
- Temporarily stop any existing
- Run the command
release/bin/bbstored/bbstored, depending if you are working on the client or the server.
- Optionally add the options
-kVTto the command line to help with debugging (run in foreground with extra logging).
- Optionally add
strace -s 128or
gdbto the start of the command to trace or debug the process.
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:
To update your copy to the latest version, run:
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
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:
To install or update the executables in /usr/local/sbin, use this command, as root:
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.
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?
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.
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:
- Large file backup and restore
- Backup of changed files and restore of
- 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.]