Codeline Organization
| Caveat: this post is not about branches but the content of the trunk and, as consequence, of the branches; look at Visual Studio TFS Branching Guide 2010 for more information about branching. |
So, what I will write about? On the organization of the various files in a version control system.
Some thinks that every project is different, with special requirements, but, as librarians know, not every classification system / taxonomy, scales equally. A clear structure helps the team to know where to put the artifacts since the beginning, avoiding painful restructuring later. It is important that organizations use a uniform structure as much as possible to ease: training, personnel reassignment and so on. Uniformity is more a convention than a prescription.
My proposal for organizing a codeline is described in the following table. Each row is a folder placed at the same level under the codeline root (be it a branch or the trunk).
Folder |
Content |
Build Dependencies |
This folder contains everything that is needed for a successful build, typically in form of MSI or DLLs. When the file is too big (say a 2GB ISO), put a text file with a description and, possibly, a reference to a URL or share. As some items have meaningful names, like setup.exe, I suggest to always create a folder with the full name of the package including the version and the source site, e.g. «Visual Studio 2008 Database Edition GDR R2 (MS)». This stuff must be installed on developers’ and build machines. |
Build Scripts |
Desktop & Team build scripts, together with other files they may need (tasks, includes). For TFS, each build definition with a unique TFSBUILD.PROJ must be in a different sub-folder. |
Build Tools |
Source code or binaries for tools used by any build script, be it Desktop or Team. For source, the projects should be included in the special build that outputs the normal build’s prerequisites. |
Deploy Scripts |
Deploy scripts and configuration data: use sub-folders to organize. |
Deploy Tools |
Tools for deploying, in binary or source form. For source, the projects are included in the special build. |
Developer Tools |
Source code or binaries for tools used only on developer’s workstation like designers or code generators. For source code, the projects are included in the special build. |
Documentation Sources |
Source files used to produce product documentation. Could be HTML pages, doc(x) files, style-sheets, images, and so on, that an ad-hoc build uses to generate CHM, web site, doc(x), PDF etc. |
Libraries |
Libraries that are simply linked or referenced in projects (i.e. no need to install). For example, this is the place for third-parties C/C++ include and lib files. |
Recycle Bin |
Staging area for file and folder that will be deleted. While many version control system, like TFS, do not remove deleted files immediately, such staging area is useful for having everybody agree on what to delete. |
Sources |
Source code for artifacts that will be deployed to production; unit testing are included. Use sub-folder to organize the various kind of project and deliverables: do not nest too much. There should be a Common sub-folder for files used across projects, like SNK or XSDs. |
Test Dependencies |
Stuff that must be installed along a test agent to make test successful, typically in form of MSI or DLLs. |
Test Sources |
Source code and data specific for integration test; unit test should go under Sources. |
Test Tools |
Source code or binaries for tools used in test; these are not deployed in production. |
Valuable Stuff |
Stuff that is not really used per se but may be useful somehow (technology samples, sample code, prototypes) and that shouldn’t be considered a deliverable on any way. |
A minor point: I avoid leaving blanks inside folder names and prefer the dash (-) sign as separator, because I think it’s more readable: see the following picture.
Also you don’t need to quote all those paths.
Hope this may spawn some comments.