Project documents and files

About documents and files

Files in a project serve many different purposes:

• Statements of the projects vision, direction, feature lists and requirements
• Project plans and schedules
• Technical files such as design specifications, coding conversions , developer FAQs and How-Tos, test plans, API references, and descriptions of theory of operations.
• User files such as user's guides, installation guides, and user FAQs and How-Tos
• "Downloads" and other deliverable files, such as compiled application or library code, that have been produced by this project for consumption by end users or other developers in other projects.

The process of adding files to the Documents & files page depends on the contributor's permissions. Observers and Content Developers can suggest new files which must be reviewed and approved by the Project owner before they are posted for viewing by all project members and guests. Developers can add files directly into the project.

Often, project files require team collaboration. One team member may post a draft for other members to review, edit and post updates. Once a file is obsolete it needs to be archived and, possibly, removed from view by the Project owner.

Contributing files

Contributing members of a project can create new files or folders by using the Add new folder or Add new file links. Non contributing members, such as Observers suggest new files or folders by using the Suggest a folder or Suggest a file links. Suggested items must be approved by a Project owner before they are visible to other users.

When creating a file you will need to define the following:

• Name: This is a required field. Your file name should be brief and descriptive. Ideally, users will be able to identify the main topic of your file by browsing the file names.
• Status: Select a value from the menu. Your options are Draft, Reviewed, Baselined, Stable, Archival and Obsolete.
• Description: This is an optional field. The file description can be used to provide a brief abstract of the salient arguments in the file, or list major ideas/topics discussed within the file. Once again, keep this brief.

At any time, you can use the Edit link to modify the file title, description, or other fields, or you use the Delete link to remove the file. If your suggested file is not approved, you will receive an email notification with the reason for this action.

A file can be textual content, a file from your local directory or a link to a URL. Each of these types has distinctive characteristics:

• Text: This field allows you to enter your content directly. You can choose to save the file in raw text format, as it has been entered into this field, or use the Text format selector to mark your content as HTML source.
• Attachment: If you would like to include a file you have on your local drive you must first upload the file to the project storage area. To do so, select Attachment as your document type and use the Browse button to navigate to your file. Once you have located your file click the Open button to add the file location and name to the field. Suggested files should not exceed 25 MB in size. Files larger than this cannot be uploaded.
• Link: This field allows you to enter a link to a URL containing the content you intend to share with other project members.

To add or suggest a new document:

1. Access any page within the project and click on the Documents & files link.
2. Select the folder in which you would like to save the file.
3. Click on the Add new file (or Suggest a file if you are a non-contributing member) link under the page title.
   NOTE: New files and folders are always placed inside the currently selected folder.
4. Enter a name in the Name filed.
5. Select a status from the Status menu.
6. Enter a description in the Description field.  This step is optional.
7. Select a content type from the Contents section.

   NOTE: If you are using HTML in a Text type you can select the HTML Source from the drop down to have the document properly rendered in the browser.

8. Enter the appropriate information for the type you selected.
9. Click the Submit button.

Collaborating on files

The collaboration process can be tracked using the file status. Marking the status of a file allows project participants to easily identify which files are available for collaboration (for instance, Draft files), have been reviewed or are no longer applicable. Project members with an item in process can flag the file as reserved for editing. When other project members view this file they will see that it has been reserved by you and the date you intend to release your reservation. Setting the reservation type to "strict lock" prevents others from editing the document during the reserved period. The Project owner will still be able to edit the document; however, all other members will have read-only access until the reservation is released. Setting the reservation type to "advisory warning" does not prevent others from accessing or altering the document. Before you update a document with your changes it is a good idea to make sure that no one else has made any changes since your reservation.

To reserve a file :

1. Access any page within the project and click on the Documents & files link.
2. Navigate to the folder containing the file you want to reserve.
3. Click the Reserve file link in-line with the file name.
4. Select an end date or Indefinite from the End date radio buttons.
5. Select a reservation type.
6. Enter a statement in the Reason field explaining why you are setting this reservation.
7. Click the Reserve file button.

The name of the reserving user appears in the Reservations field in-line with the file. The reservation will remain in effect until the Until date passes.

To remove a reservation:

1. Access any page within the project and click on the Documents & files link.
2. Navigate to the folder containing the file you want to reserve.
3. Click the Edit link in-line with the file name.
4. Click the Edit link in the Edition reservations section.
5. Click the Delete reservation link in the Other operations section.
6. Click the Confirm delete button.

Viewing files

To view project files, from any project page click the Documents & files link on the left navigation bar. The Documents & files page displays files organized by folders. You can use the + and - icons to expand or contract the folder display to access subfolders.

The tree view shows 2 counts next to each folder. The first count is the number of documents directly underneath the folder. The second count is the total number of documents directly underneath the folder plus any documents that live in any child folders. For example, "Folder 1 (1,5)" means that there is 1 document in Folder 1, and 5 total documents in Folder 1 and all its child folders. Empty folders show a file count of (0,0).

Note: The file count includes reserved files, suggested and pending files, and locked files.

The table to the right of the folders contains a list of files available within the currently active folder. To change the active folder, click on the folder name. Files are shown ten at a time with links at the bottom of the page for browsing through further pages of files. Clicking on the name of a file will show its contents.

Note: Only those files to which you have view access are included in the file count for each folder.

Alternatively, if you need to share a file with another user you can send a URL to the location of the file. To do so, navigate to the document and cut and paste the location into your communication.

Attributes for each file appear in-line with the filename. Information available for each file includes:

• Name: The file name serves as a link to the file contents.
• Status: The status describes the point in the life-cycle of the file.
• Modified by: The modified by field indicates the last user to have modified the file along with the time stamp of the last file update. The username of the file is a mailto link.
• Size: Indicates the size of the file.
• Reservations: If any user has reserved the file the username will appear in this field. If no reservations have been made, and you have the appropriate permissions, you will have a Reserve file link, from which you can make a reservation of the file.
• Description: Any description provided for the file will be listed in this field.
• Edit: If you have permission to edit files in the project you will see an Edit link.

NOTE: files in locked projects can not be edited, they are read-only.

Similar to files, folders have attributes. Folders can be nested with subfolders appearing below the parent folder. Once you have selected a folder to make it active, the active folder appears as an open file folder, the folder name is bolded and the description appears above the table listing files contained in the folder.

Copying files

You can copy files that are displayed by the Docs & Files tool.

To copy a file:

1. Click the Projects tab.
2. Click the link for the project that contains the document you want to copy.
3. Click Documents & Files in the left navigation pane.
4. Browse the folders and find the document you want to copy.
5. Click the Edit link for this document.
6. At the bottom of the Edit File page, click the Copy File link.
7. Input a name for the file, select a folder for the file to be copied to, and click Copy File.

Deleting files

You can delete files that are displayed by the Docs & Files tool.

To delete a file:

1. Click the Projects tab.
2. Click the link for the project that contains the document you want to delete.
3. Click Documents & Files in the left navigation pane.
4. Browse the folders and find the document you want to delete.
5. Click the Edit link for this document.
6. At the bottom of the Edit File page, click the Delete File link.
7. On the Delete File page, click the Confirm Delete button.

Reserving files

You can reserve a file under two modes: Advisory Warning or Strict Lock. Strict lock reservations prevent other users from editing the file. Advisory reservations inform other users that this file is reserved, but do not prevent you from editing the file. Project owners have permission to edit files, even if they are locked.

To reserve a file:

1. Click the Projects tab.
2. Click the link for the project that contains the document you want to reserve or lock.
3. Click Documents & Files in the left navigation pane.
4. Browse the folders and find the document you want to delete.
5. Click the Reserve File link under the column Reservations.
6. On the Reserve File page, select the appropriate options and click the Reserve File button.

Linking to files in the CVS or Subversion repository

You can use the Documents & Files tool to allow users to view files in the version control repository for the project, even if the users do not have access to the repository. When you link to files in the repository, users can view the most current version of the file in the Web browser by clicking the link to the file from Documents & Files. Users do not need to check out the source from the repository.

You can only link files in the following directory or subdirectories of this directory:

• CVS - You can link files in the www directory for the project, or any subdirectory of www.
• Subversion - You can link files in the trunk/www directory for the project, or any subdirectory of trunk/www

To create a link to a file in version control:

1. Using your version control tool, add the file to the CVS repository in either the www directory or one of its subdirectories.
   Or, if you use Subversion, add the file to the trunk/www directory or one of its subdirectories.
2. Commit the file to the repository.
3. In the CollabNet environment, click the Projects tab and click the link for the project where you added the document in version control.
4. Click Documents & files in the left navigation pane.
5. Click the Add new file link.
6. Enter a Name, Status and optional Description for the file.
7. In the Contents section, select the Link radio button and enter the URL for the file as a relative link in the www or trunk/www directory. For example, a link to index.html would be http://domain.com/index.html and a link to index.html in a docs directory under www or trunk/www would be http://domain.com/docs/index.html.

HTML coding conventions

HTML, without XSS scripting tags, can be passed to the browser from specific areas of the application. To prevent cross-site scripting security issues, each HTML submission is passed through a filter that detects scripting tags. Most CollabNet pages use this filter, so that all user-supplied HTML is escaped, except where it is explicitly allowed. Allowed HTML is limited to the following subset of HTML tags:

Allowed tags are: <!-- --> <A> <ABBR> <ACRONYM> <AREA> <B> <BASE> <BASEFONT> <BIG> <BDO> <BLINK> <BLOCKQUOTE> <BR> <CAPTION> <CENTER> <CITE> <CODE> <COL> <COLGROUP> <DD> <DEL> <DFN> <DIV> <DL> <DT> <EM> <FIELDSET> <FONT> <H1> <H2> <H3> <H4> <H5> <H6> <HR> <I> <IMG> <INS> <KBD> <LI> <LABEL> <LEGEND> <LINK> <MAP> <MENU> <MULTICOL> <NOBR> <NOFRAMES> <NOSCRIPT> <OL> <OPTGROUP> <P> <PARAM> <PRE> <Q> <S> <SAMP> <SMALL> <SPACER> <SPAN> <STRIKE> <STRONG> <STYLE> <SUB> <SUP> <TBODY> <TD> <TFOOT> <TH> <THEAD> <TR> <TT> <TABLE> <U> <UL> <VAR> <WBR>

To render HTML