Placing your Grok project under version control

Might be outdated! This document hasn't been reviewed for Grok 1.0 and may be outdated. If you would like to review the document, please read this post.

Very often, programmers find themselves wanting to save their projects to a version control system like Subversion, Bazaar, Git, or CVS. But it can be confusing to know what to save out of all the files that grokproject creates under your project directory! And, if you version-control the wrong ones, you could find that your project can be difficult to get working again when you check it back out.

The key is to recognize that much of your Grok project is created automatically from its buildout.cfg, and therefore should not be version-controlled. There are three reasons for not saving these files. First, they are each already defined or described by your buildout.cfg, and it is therefore redundant to place them in persistent storage. Second, they are often files which need to be different on every computer on which you place them because they have file names or paths to executables (like the Python interpreter) that are likely to be different on the various machines to which people check the project out. And, third, having the files in version control means that your version-control system and buildout will be constantly fighting as they overwrite the files' contents with new and old data, which can make deployment quite difficult.

Therefore, the files that you want to version-control are generally these:

# Save these files

buildout.cfg
setup.py
src/yourproject/everything except *.pyc files

That is, you want to save the two files buildout.cfg and setup.py that define your project and describe how it should get built and run, and you want to save all of the source files and application content that you have generated under the src/ directory. But you should not save anything inside of the following directories, which are all auto-generated files that might have to look different on each system on which you check out and build your Grok project:

# Do NOT save these files

bin/
develop-eggs/
parts/
src/yourproject.egg-info/

By omitting these directories, you leave buildout free to create these files afresh as they need to be on each system where you place your project.

 

Option #1: Rebuilding your project with the buildout command

Because you will need these files re-created when you check out your project, you will need to get a working copy of buildout available. Some people, I have heard, including people of quite high reputation in the Grok community, actually use easy_install to make the buildout program permanently available on their system:

# How to install the buildout command permanently
$ easy_install zc.buildout

Having this command available on your system means that you will typically find yourself doing something like this when you are ready to start work on a project that has been sitting in version control:

# Getting to work again

$ svn co http://.../myproject
$ cd myproject
$ buildout
$ bin/zopectl fg

 

Option #2: Using a bootstrap file to avoid installing buildout

Another method for checking your project back out, and that avoids having to install the buildout command on your system at all, is to place a copy of the file bootstrap.py in your project:

# Grabbing bootstrap.py for your project

$ cd my-project
$ wget http://svn.zope.org/*checkout*/zc.buildout/trunk/bootstrap/bootstrap.py

You can then check this file in with the rest of your project, along with the other files you version-control, and it will be available whenever you check the project out. Then, re-activating your project just goes like this:

# Building out a freshly checked-out project

$ python ./bootstrap.py
$ ./bin/buildout
$ ./bin/zopectl fg

Using bootstrap.py means that anyone can work on your project without having to worry about installing Python commands on their system that they might never have heard of.

Backing up your live application data

Note that, as you run your project in production, you will want to be very careful to back up the following file:

# Back this file up, it contains your application data!

parts/data/Data.fs

But as one does not typically use version control to back up raw application data, you should not actually place this file under version control! Instead you will copy it safely to another machine, or make sure it gets copied and placed on a back-up tape, to assure that you can restore your site with its content should the machine on which it is running ever be destroyed.