File Control System
1.0
Functional Specification
Author: Ken Rodham
Date:
Revision: 1
The directory/file structure containing the team’s files is called the repository. It is assumed that the repository is accessible to all team members via a shared file system. The repository may contain subdirectories to any level of nesting, and each subdirectory may contain any number of files. The top-level repository directory is called the repository root directory.
Each team member has a local (i.e., unshared) copy of the repository on his or her local computer. This local copy of the repository is called a workspace. A user’s workspace is a mirror-image copy of the real repository, containing the same directories and files. A user initially creates their workspace by asking FCS to copy the repository to a specified location on their local computer. This location is called the workspace root directory. The user can make changes to files locally in their local workspace, and then, when the changes are complete, ask FCS to copy the changes back to the repository and make them available to the rest of the team.
FCS keeps track of all revisions made to repository files. For each file, revisions are numbered sequentially starting at 1. The initial copy of a file that is added to the repository becomes revision 1, the next update to the file becomes revision 2, and so on. While FCS keeps track of file revisions, it does not keep track of directory revisions.
In order to use FCS, a user must provide the following configuration information:
Given this information, FCS can copy files and directories between the user’s workspace and the repository.
NOTE: All remaining use cases assume that the user has previously performed the Configure FCS use case.
Before the repository can be used, the FCS administrator must:
Once repository initialization has been complete, the repository is ready to be accessed by team members. Initialization is an administrative function that is performed only once before a repository is used for the first time.
This use case allows a user to initialize the repository.
Variations:
After repository initialization, the repository contains one directory (the root) and no files. Additional files/directories to be added to the repository are first created in the user’s local workspace. When the user is ready to share the new files/directories, they perform an FCS add operation to add them to the repository. Adding a file/directory to the repository creates a copy of it in the repository, but does not remove it from the user’s workspace.
Files/directories are added to the repository one at a time. There is no batch mode for adding multiple files/directories at once. When adding a file, the user must provide a textual description of the file’s contents.
FCS can handle text files and binary files. When adding a file to the repository, the user must specify whether the file is a text file or a binary file.
This use case allows users to add workspace files to the repository.
Variations:
This use case allows users to add workspace directories to the repository.
Variations:
When a user wants to retrieve the latest revision of a file from the repository, they must perform an FCS checkout operation. A checkout operation copies the latest revision of the specified file from the repository into the user’s workspace. If the user wants to checkout an earlier revision of the file rather than the latest one, they may specify the desired revision number when checking out the file.
If a user wants to checkout a repository file with the intent of changing it, they must checkout the file in locked mode. FCS only allows one user to lock a particular repository file at a time, thus preventing multiple users from simultaneously modifying the file. When checking out a file in locked mode, it is possible that the file has already been locked by another user, in which case FCS will notify the user that the file is already locked. Only the latest (or current) revision of a file may be checked out in locked mode. Earlier revisions may not be modified.
This use case allows a user to copy a specified revision of a repository file into their workspace.
Variations:
In addition to checking out files, a user may also checkout an entire repository directory. Checking out a repository directory recursively copies all of the files/directories in the specified repository directory to the user’s workspace. This makes it convenient for users to retrieve the latest revisions of all files/directories in the repository or some part thereof. An example of this is a new team member who needs to copy all of the repository files/directories to their newly created workspace. After creating their workspace root directory on their local file system, the user would perform an FCS checkout operation on the repository root directory, thereby copying all files/directories from the repository to the workspace.
This use case allows a user to recursively checkout all of the files and subdirectories in a specified repository directory. By default, every subdirectory and the current revision of every file within the specified repository directory are copied to the workspace. Alternatively, the user may specify a label indicating which version of the repository directory should be checked out. If a label is specified, only those files and subdirectories that have the label are copied to the workspace. It is an error to specify a label that is not associated with the specified repository directory. However, it is expected that some files and subdirectories within the repository directory will not have the specified label. This is not an error, but files and subdirectories that do not have the label are not copied to the workspace. This allows the user to checkout only those files and directories that are part of the specified version of the repository.
A directory may not be checked out in locked mode.
i. If the file has the specified label, copy the labeled revision of the file to the workspace
ii. If the file does not have the specified label, do not copy the file to the workspace at all
i. If the subdirectory has the specified label, recursively copy the subdirectory to the workspace
ii. If the subdirectory does not have the specified label, do not copy the subdirectory to the workspace
Variations:
After checking out a file in locked mode, the user is free to make changes to the file. When the changes are complete, the new revision of the file may be copied to the repository by executing an FCS checkin operation. If the latest revision of the file is N, the new revision becomes revision N+1. When checking in a file, the user must provide a textual log message describing the changes that were made to the file in the new revision. Checking in a file copies the new revision to the repository, but does not remove it from the user’s workspace.
This use case allows a user to checkin a file that they currently have locked.
Variations:
If a user locks a file for editing and then decides not to change the file after all, they should execute an FCS unlock operation to release their lock on the file. Doing so will allow other users to modify the file. Unlocking a file does not remove it from the user’s workspace.
This use case allows a user to unlock a file that they currently have locked.
Variations:
Repository files and empty repository directories that are no longer needed may be removed from the repository by performing an FCS remove operation. Files/directories are removed from the repository one at a time. There is no batch mode for removing multiple files/directories at once. Removing a file/directory from the repository does not remove the corresponding file/directory from the user’s workspace. If the user wants to remove the workspace copy, they may do so using regular file system commands.
This use case allows users to remove files from the repository.
Variations:
This use case allows users to remove directories from the repository.
Variations:
FCS supports repository labeling for keeping track of which files and directories make up a particular version of the repository. When the repository is labeled, the user specifies a label string that describes the current version of the repository (e.g., “BETA_1”, “VERSION_1”, “VERSION_1.1”, etc.). Every directory and the most recent revision of every file in the repository is marked with the specified label. Thereafter, if there is ever a need to reconstitute that particular version of the repository, it can be done by specifying the correct label during an FCS checkout operation (e.g., “checkout VERSION_1.1”). Doing so would cause all of the files and directories that make up the specified repository version to be copied into the user’s workspace.
Every repository directory and file revision is marked with zero or more labels. If a directory or file revision has a particular label, then it is part of that version of the repository.
Any file or directory that has been marked with one or more labels may not be removed from the repository using an FCS remove operation because doing so would make it impossible to reconstitute previous versions of the repository.
Any non-empty string may be used as a label.
This use case allows a user to label all of the files and directories in the repository with a descriptive label.
Variations:
Users may ask FCS to display information about the repository itself or about a particular file/directory within the repository.
Repository information includes:
· The name of the user who initialized the repository
· The date/time at which repository initialization occurred
· A list of all labels that have been applied to the repository. For each label, the following information is displayed:
1. label string
2. name of the user who created the label
3. date/time at which the label was created
Directory information includes:
· The full path of the directory within the repository
· The name of the user who added the directory to the repository
· The date/time at which the directory was added to the repository
· A list of all labels that have been applied to the directory
File information includes:
· The full path of the file within the repository
· A description of the file’s contents (provided by the user when the file was added to the repository)
· The name of the user who added the file to the repository
· The date/time at which the file was added to the repository
· The current revision number of the file
· The name of the user who currently has the file locked (if any)
· The date/time at which the user locked the file (if any)
· A list of all labels that have been applied to the file. For each label, the following information is displayed:
1. label string
2. file revision number that is associated with the label
This use case allows users to view information about a repository file.
i. label string
ii. file revision number that is associated with the label
Variations:
1. If the specified repository file does not exist, an error message is displayed and the operation aborted
2. If the file information cannot be displayed for any reason, an error message is displayed and the operation is aborted
This use case allows users to view information about a repository directory.
Variations:
This use case allows users to view information about the repository.
i. label string
ii. name of the user who created the label
iii. date/time at which the label was created
Variations:
Users may ask FCS to display the revision history of a repository file. For each revision of the file, FCS will display the following information:
· The revision number
· The name of the user who made the revision
· The date/time at which the revision was made
· The log message provided by the user when the revision was checked in
This use case allows the user to view the revision history of a repository file.
Variations:
1. If the specified repository file does not exist, an error message is displayed and the operation aborted
2. If the file revision history cannot be displayed for any reason, an error message is displayed and the operation is aborted
Users may ask FCS to display the differences between two revisions of a text file. FCS compares the two file revisions and, at each point where the revisions differ, displays the lines that were inserted, deleted, or modified between the two revisions (similar to the Unix diff command).
This use case allows the user to view the differences between two revisions of a text file.
Variations:
1. If the specified repository file does not exist, an error message is displayed and the operation aborted
2. If the specified repository file is a binary file, an error message is displayed and the operation aborted
3. If one or both of the specified file revisions does not exist, an error message is displayed and the operation aborted
FCS performs automatic keyword substitution on text files whenever they are added or checked-in to the repository. This allows revision control-related information to be embedded within the body of a text file. The following keywords are supported:
@Path@ - the path of the file relative to the repository root
@Revision@ - the revision number of the file
@Author@ - the name of the user who checked in this revision of the file
@Time@ - the date/time at which this revision of the file was checked in
For example, the initial creator of a text file could include the following header in the file:
/*
@Path@
@Revision@
@Author@
@Time@
*/
When the file is added to the repository, FCS would substitute each of the keywords as follows:
/*
@Path: project/src/SomeFile.java @
@Revision: 1 @
@Author: fred @
@Time: Fri Jun 13
*/
Keyword substitution is performed on both the workspace and repository copies of the file. When revision 2 of the file is checked in, FCS would make the following substitution in both the workspace and repository:
/*
@Path: project/src/SomeFile.java @
@Revision: 2 @
@Author: barney @
@Time: Mon Jun 16
*/
Keyword substitution is only performed on text files, not on binary files. Keywords need not appear in comments; they may appear anywhere in a text file. In fact, any text file may contain keywords, not just source code files.