These are some thoughts I put together on how to structure an SVN repository for a new project. I wrote them while setting up the repository for the DepthPerception repository, because I thought my previous 2 repositories (HDRAmbLightPaper and Mesopic) were set up suboptimally. In particular:

• Having the paper in the root directory in HDRAmbLightPaper made it complicated to make tags of different versions of that paper, because each copy (tag) wanted to include the tags directory itself, creating undesired extraneous copies one additional level down. On hindsight, I should have made the repository for the project, not the paper, and made the paper itself a directory within the project.
• When setting up the Mesopic project, I wanted a directory in which you could put files related to the project that weren't important enough to include as checked-in elements of the project. So I created a .../psm/Mesopic directory for those files, and a .../psm/Mesopic/Mesopic directory for the files in the SVN repository. But the Mesopic/Mesopic structure is clunky, and I figured it would be good enough to simply have made the .../psm/Mesopic directory the root point for the Mesopic SVN repository, and files that weren't important enough to check in could simply not be checked in, but still reside in that directory.

How to structure an SVN repository for a project

A project (e.g. "DepthPerception" in the example below) should have an SVN repository of the same name.

• svnadmin create /ubc/cs/research/imager/project/psm/SVNRepository/DepthPerception
• cd $_ # Go to the above directory
• ../README.newProject # This is actually a shell script! It sets the necessary permissions etc.

A project should also have a directory in /ubc/cs/research/imager/project/psm which is a local (checked-out) copy of that SVN respository.

• cd /ubc/cs/research/imager/project/psm
• svn co file:///ubc/cs/research/imager/project/psm/SVNRepository/DepthPerception

Once that is done, you can begin adding files and directories to that project, checking in as appropriate...

A paper that is produced as part of a project should have its own subdirectory, called something like paper_sg2009 (for a SIGGRAPH 2009 submission for instance). A talk that is produced should also have its own subdirectory (like talk_sg2009) that is a child (like paper_sg2009) of the project directory. If a paper is later submitted to a different conference, the new paper should have its own directory (like paper_sg2010) who's initial state may be a copy of some version of paper_sg2009 (whose history would then apply to paper_sg2010 as well) for instance.

When a paper is submitted to a conference, the reviews that come back should be downloaded and saved in the paper directory. If applicable, the reviews may be saved (as different files) in multiple formats (like text and pdf), in multiple orderings (like by reviewer or by question), or in any other way that makes sense. The point is that all relevant information in the reviews (content, formatting, ordering, or whatever) should be retained. The same applies to rebuttals. If the reviews change or additional reviews happen, the reviews should be downloaded and saved (and submitted) again so that the difference between the old and new reviews is preserved. If there is discussion about a paper on a BBS (or similar medium), that discussion should be downloaded and saved.

A project should have a "tags" directory which contains copies of certain milestone versions of papers, talks, software, or other collections of files that evolve over time. Versions should have names that signify their value or purpose. At the least, every version of a paper that is actually submitted, a talk that is actually given, or a software collection that is used significantly, should have its own tag. That way a particular state is preserved for future reference.

• One big upside of having a paper in a subdirectory instead of the main directory of a SVN repository is that making a tag becomes much less messy, since you can then make a tag without having to include the tags directory itself in the tag you're trying to make.

In most cases, there should be more SVN commits than there are tags. Every commit should reflect some significant additional work that can (and should, in the commit process) be easily described, and every commit should be believed at the time of that commit to be no buggier than the previous commit. That is, there should be a monotonic decrease in believed bugginess. If a particular commit follows some major structural reorganization, it shouldn't be committed in a partial state that renders it effectively broken; the reorg should be functional (though not necessarily complete) before it is committed. Every version that is gone over with Wolfgang or other colleagues should be committed. That way any slide, page, paragraph, or line numbers that are referred to will be preserved.

Any time a structural change is begun, the paper/talk/software/whatever should be committed before embarking on that structural change. If the structural change is significant enough, it may warrant a tag. If the structural change is so significant that the result might be considered to be a different product, it may be appropriate to copy the old product into a new directory and do subsequent development there.

A project directory can be used as a place to store files that are related to that project but don't necessarily fit obviously into any well-developed subdirectory (of the project directory) structure. These files can be simply left un-checked-in until such time as it makes sense to check them in as part of a more well-developed structure.

In most cases, certain types of files should not be checked in. These include compiled files or other files that are derived from source files, such as .o, .so, .dep, .exe (?), .obj, .dll (?), .asv, .aux, .bbl, .log, .blg, .dvi, etc. This is to avoid the saving of extraneous files, especially if they're large, and also to avoid continuously resaving subsequent extraneous versions, which can happen because every subsequent build will contain a (different) version of that derived file which will flag the whole directory as changed even if it really isn't. If it is really desired to keep a particular executable or derived file because its importance is high, then a tag should be made of the source code version that produced that file, and then that file can be SVN added and committed. Some derived files (like .pdf) may be worth checking in because they can be important files that have been submitted for some kind of review, and any such file should be kept.

A project directory should have a "Papers" directory in which are stored electronic copies of papers relevant to that project. Note that this may change if the use of papers-organizing software such as Mendeley becomes prominent within PSM.

-- AllanRempel - 09 Sep 2009