CSC 0 Standard Operating Procedures,
Volume 1: Artifact Repository Structure



Project Directory Structure

A software project directory is organized into the following subdirectories:

Subdirectory Contents
requirements Requirements analysis, principally in .html files

specification Formal specification, principally in .rsl files

prototype Prototype, in a variety of prototyping file formats

design Design, in .html files generated by javadoc, and other design file formats

implementation Implementation, in .java, .C/.h, and/or other programming language files

deployment Deployed artifacts, including one or more executable programs and necessary installation/support files
administration Scheduling and other administrative information, principally in .html files

testing Test plans, scripts, and results, in .html, .csh, .java, .out, and .diff files

documentation Assembled documentation, principally in .html and .ps files

library Optional directory of standard library files, in project-specific file formats

subprojects Optional subprojects directories, with the same structure as this directory, i.e., requirements through subprojects.


In a project librarian directory, there are four project superdirectories that organize the projects by degree of stability. The directories are:

Superdirectory Contents
production Projects that are stable enough for production use. Project developers may safely use and link to files in production directories.

beta Moderately stable versions of projects. The difference between beta and production versions is that beta projects contain experimental functionality that may not be fully tested. Project developers may reasonably safely use and link to files in beta directories, though they may not be as stable as production projects in all cases.

alpha UNstable versions of projects. Files in alpha projects are subject to frequent change and may not be fully tested. Project developers should use or link to alpha files only with direct coordination with the project owner.

work Work-in-progress versions of projects. Files in work projects are highly unstable and may not even compile. Project developers should never use or link to files in work directories. The files, if readable, may be used for browsing purposes.

Within each of the four release-level directories are the project directories themselves. Figure 1 is a diagrammatic view of the full project directory structure.


Figure 1: Diagram of project directory structure.



In general, a single project may have one to four separate versions, depending on the stability and degree of active work for the project. For example, an established ongoing project may have versions in all four of the production, beta, alpha, and work directories. A stable project for which no work is currently active may have a version only in the production directory. A brand new project may have a version only in the work directory.

In CSC 0 this quarter, we will use only two levels of projects -- work and alpha. The alpha directory will only be updated once, at the end of the quarter. The contents of the requirements, specification, testing, and administration directories will be copied from the 308 projects of last quarter. Minor updates may be made to the requirements and specification directories, in response to SCOs. The major directories used in 0 this quarter will be design, implementation, and testing. The administration directory will also be used for team administrative files, as it was used in 308. The prototype and documentation directories will not be used.

The directories listed above contain all pertinent project files. Under some circumstances, there may need to be platform-specific files or directories within a project. When such exist, they should be defined as symbolic links (i.e., shortcuts, aliases) to appropriate files or directories in the standard project hierarchy.

Specific Update Procedures

Each 0 project member, including the librarian, maintains his/her own work directory. The project librarian also maintains a master projects directory for the entire team, in addition to his/her individual work directory. Figure 2 shows the top-level project directory structure for team members and the librarian.


Figure 2: Top-level directory structure for team members and the librarian.



All changes of any kind originate in an individual work directory. On a regular basis, the files from the individual work directories are checked in to the project SVN repository using the `svn add' and `svn commit' commands. Team members keep their own working directories up to date by checking out the work of their partners, using the `svn update' command.

The "regular basis" on which work is checked in is at least once per week, on or before Friday at 5 PM. The required weekly check-ins commence on Friday of the second week of class, once everyone's project directories have been set up. Individual team members will typically check-in and check-out work more frequently than once per week, so that their work can be accessed from the repository by all team members.

After individual team members have checked in their work for the week, the librarian updates the public work directory for the entire project. This step is the official weekly release of the project. The work in the release directory is that which will be evaluated for the milestones.

The handout on SVN Basics covers details of using SVN commands. Steps 1 through 3 cover initial project set up. Steps 4 through 6 cover how individual team members perform check-in and check-out. Step 7 is how the librarian releases work to the public project directory.

Starting around the fifth week of the quarter we will begin formal testing of the design and implementation. At that point, we will discuss further conventions for check-in of tested work.

File Ownership

Exactly one team member is responsible for each project file. In version control terms, that member is the file owner. Under normal conditions, only the owner of a file may check it in. All other members may check it out. File ownership is recorded in the administration/work- breakdown.html. We will discuss the format of this file in a subsequent SOP. In some cases, it may be necessary for file ownership to change or be shared. If this is not coordinated among all team members, SVN conflicts can arise.