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.

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.

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.

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.