How to structure an SVN repository for a project

A project should have a directory in /ubc/cs/research/imager/project/psm .

A project should have an SVN repository of exactly the same name, whose local (checked-out) copy is the above project directory.

• svnadmin create file:///ubc/cs/research/imager/project/psm/SVNRepository/

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, .ps, .pdf, 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.

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