Metrics Database Users’ Guide

Prepared as part of CSC Task 012 for the NASA Langley Research Center 
Kevin Marlowe, Computer Sciences Corporation 
March 12, 1997 

Introduction

The Metrics Database is a standalone database application that stores and tracks information about the status of a software development project. It allows members of a team developing software to maintain a shared repository of information about the project, and permits detailed analysis of the data stored. It can support projects ranging from the most to the least complex by permitting local customization without losing compatibility with data stored on other projects or at other locations. 

The Web Interface

The Metrics Database is normally accessible only to users who have access to the local Microsoft network. Since the database uses Microsoft’s NetBEUI network protocol to communication between machines, only users located on the same side of a network router can attach remote drives, and thus attach to the database. Remote users, therefore, cannot directly modify the database using the standard interface provided. 

Additionally, the interface provided for the database is written in Microsoft Access, which is only available for PCs based on the Intel architecture. This means that users on other types of computers, including Apple and various Unix computers, cannot use the standard interface. 

To address these issues, an interface has been developed that works over the World Wide Web through a web browser (such as Netscape Navigator). Users on non-PC platforms, or PC users who are not connected to the local network, can access certain features of the Metrics Database from anywhere in the world using the Web interface. Since the Web interface and the Access interface work with the same data files, there is no problem with data synchronization or replication, and access is limited only by the speed of the remote user’s network (assuming the server is located on a high-speed Internet connection). 

To use the Web interface, you need a connection to the World Wide Web and a Web browser that supports the JavaScript language. Netscape 3.0 or later works well, as will most current Web browsers. Some browsers give the user the option of disabling Java and JavaScript code; these features must be enabled for the Web interface to the Metrics Database to work correctly. 

Connecting to the Web Server

You need to know the Uniform Resource Location (URL) for the server that’s running the database. This will typically be the same machine as the one serving the database to users of the Access interface on their PCs. Your system administrator should be able to tell you the URL to use. For example, the URL might be "http://sw-eng.larc.nasa.gov/metrics/html/login.htm".  

Start your Web browser and enter the URL in the area provided for connecting to remote Web servers (usually "File / Open Page…"). The Metrics Database login page should appear. 

Enter your username and password in the blanks provided, and press the "Login" button to connect to the database. 

Next, you’ll be asked to select a project and release to work on. You can return to this page and select another project when you want to switch projects, but the project and release you select here are maintained for the rest of your session with the Database. 

Projects and releases appear as one selection throughout the Metrics Database as "project – release". 

Finally, the Metrics Database Remote Control will appear. You use the Remote Control to navigate through the forms of the database. 

Select a form by clicking on the appropriate button of the Remote Control. The form will open in your browser window. 

Several of the buttons on the Remote Control have special functions. These are: 

Back. Moves the browser to the previous page. 

Forward. Moves the browser to the next page. 

Home. Returns to the Metrics database Home Page. 

Off. Removes the Remote Control from your screen. You can turn it back on by returning to the Metrics Database Home Page and selecting the button marked "Open Remote". 

Project. Returns to the Project Selection page to allow selection of a different project or release. 

Help. Opens this page. 

The Remote can be minimized or closed without affecting the operation of the Database. 

Using the Metrics Database Forms

When you select a button on the Remote Control, the form you selected will open in the browser window. Your name, and the project and release you chose earlier, will be carried forward for you. You cannot change them except by logging on again and/or selecting another project / release combination. 

Most Database forms request that you enter some header information, such as a CSCI or id number, at the top of the form. You will usually have two choices or operations for each type of form: edit an existing form, or start a new one. Select the appropriate button for the action you require.  

Once you complete or amend a form, you will need to submit it back to the central Database server. This is done by clicking on the button marked "Submit" on the form. Once you select "Submit", you data will be saved in the Database. 
  
Warning: Once you submit information to the database, your browser screens may show old data. If you are editing a form and submit your changes, select the form from the Remote Control to update the online form with the changes you made. Using the "Back" button in your browser (or the Remote Control) will show out-of-date data. 

Quitting the Metrics Database

There is no way (in fact, there is no need) to "exit" the Metrics Database on the Web. When you exit your browser, all name, password, and project information you have entered will be deleted from your local computer. 

Forms

For security reasons, only certain forms are available through the Web interface. They are: 

• Software Change Request (SCR)  
• Software Trouble Report (STR)  
• Software Promotion Notification Form (SPNF)  
• Weekly Development Effort Form (WDEF) 

Reports are not available through the Web interface. There is no technical reason why more forms could not be implemented; different sites may author and install different sets of forms. 

The instructions that follow are for the PC versions of the forms. Some functionality may be missing in the Web version for security reasons and some features may work slightly differently.

 Software Change Request (SCR)

The SCR documents all requests for changes to the software products.  All information about the change should be fully and accurately documented on the SCR.

CSCI:  The computer software configuration item (CSCI) to which the change applies.

SCR Number:  Unique SCR identifier.

CCR Number:  If the SCR results in a Configuration Change Request (CCR), the CCR identifier number is recorded here.  Otherwise, leave the field blank.

STR Number:  If the SCR is the result of a Software Trouble Report (STR), the STR identifier number is recorded here.  Otherwise, leave the field blank.

The following fields can't be changed via the Web form, but will display data entered via the PC interface:

Requester:  Individual requesting the change
Action Taken:  The decision to defer, implement, or not implement the change
Authorized By:  The project software manager signs (places name or initials) the form.
Date:  Date of authorization.
Individual Responsible for Implementing Change:  Individual assigned to implement the change
Expected Comp. Date:  Date the SCR is expected to be completed.
Completed By:  Individual implementing change places name or initials in field when change is completed.
Completion Date:  Actual date SCR action was completed.
Verified By:  Project software manager places name or initials in field after verifying and approving change


SCB Comments:  Any SCB member may explain the decision (or register opposition to the decision) and any special concerns surrounding the change.

Section A:  Identification of Change(s) 

Software Product(s) Affected:  The software product(s) (document and/or code) that may be affected by the change.

Nature of Proposed Change and Reason:  Additions, deletions, or changes to the software product(s).  List all advantages and possible disadvantages for this change, including risks/implications if change is not made.  If applicable, list all options for the change and the advantage/disadvantage of each.  If this change is a result of a STR, indicate how the STR will be resolved.

Category:  Click and hold on the down arrow key to access the options showing the possible reason(s) for the change.  Although the reason(s) was documented above, categorizing the change allows for tracking project statistics.

Section B:  Resource Impact Analysis

Analyzed by:  Individual responsible for doing the analysis. Click on the arrow to the right of the field to access other names or additional space.

Req. Comp. Date:  Required completion date for the analysis.

Criticality (1-5):  A criticality level (i.e., "1" through "5") is assigned as determined by the classifications in the following chart.

EXPLANATION OF CRITICALITY CLASSIFICATION CRITICALITY LEVEL

1. Software system will fail without this change. Example: Incorrect hardware (h/w) interface requirements
2. Important capability will fail without this change. Example: Requirements for some off-nominal situations are incomplete or incorrect. 
3. Non-critical capability will fail without this change Example:  Code produces incorrect error message in off-nominal node
4. Capability will work, but this authorization will improve or add features to the capability, or a document will be significantly improved. Example: Instructions in Users Guide are incomplete
5. Capability will work better with this change  (e.g. more efficient, faster) or a document will be clarified. Example: Use of more efficient algorithm in code.

Risk (1-4):  A risk of implementation is assigned (i.e., "1" very high through "4" low), as determined by the classifications in the following chart. 

RISK EXAMPLES ASSIGNED NUMBER
1. VERY HIGH
Change involves more than five Ada compilation units with complex code, complex timing or numerous interfaces or change is to baselined interface requirements and designs.
2. HIGH 
Change involves two to five Ada compilation units with complex code, complex timing and many interfaces or change involves modifying baselined designs.
3. MODERATE 
Change involves more than two Ada compilation units with a moderate complexity level or 1 unit with high complexity or change involves modifying architectural design during detailed design.
4. LOW 
Change involves one or two Ada compilation units with a low
complexity level or change involves modifying User's Guide, Software Version Description, etc.


Resources:  Approximate the time and costs required in the following categories.  The figures represent the approximate total time and cost to implement the SCR.

 Implementation (modifying data files, etc.):
 Testing (including unit, integration testing):
 Changes to Documentation:

Section C:  Analysis of Impact to Existing Products

Number of each type of components to be changed:  List the number (quantity) of the following components that will be affected by the change.

 Ada package specifications
 Ada package bodies
 Ada separate procedures
 Ext. data files
 Menu files
 Documents
 Other

Explain:  Fully explain the impact of the change on any of the above components.  Be as detailed as possible so the impact can be fully understood.

List software products to be modified and changes - Software Changes:  List the software that will be affected by the SCR, and briefly describe the change(s).  To add new software to the list, select the "New" button and enter the software and changes in the dialog box that appears. To edit software already in the list, select the "Edit" button and make changes in the dialog box that appears.


Section D:  Analysis of Impact to Reusable Software

If this change also needs to made to reusable software, list ongoing projects (or library information) here:  Explain any changes that must be made to software being reused from reuse repositories or other projects.

 Software Trouble Report (STR)

The STR documents all potential software errors.  All available information about the software problem should be fully and accurately documented or referenced on the STR.

STR Number:  Unique identifier for the STR.
Submitter:  Individual submitting the STR.

Section A:  (Identification of Problem)
CSCI:  Enter the name of the computer software configuration item (CSCI) in which the error occurred.
Document/Platform where problem occurred:  Name of the document in which the error occurred.  If the problem is an execution error, document the platform on which the code was running.
Date discovered:  Date the problem was discovered.  This could be important in resolving the problem.
Describe the problem:  Fully describe the problem or the observed symptom(s), including any possible work-arounds.  Include how the user is affected and the problem's severity.  Include any supporting information that may help in analyzing the problem.
Describe the system configuration and software version in which the problem occurred:  Provide all information required to accurately describe the software system and environment in which the problem occurred.  This includes all information about the software, hardware, simulator(s), etc. 
What were you doing (or attempting to do) when the problem occurred:  Describe the test(s) or sequence of events (e.g., keystrokes) being performed when the problem occurred.
If the error occurred during the execution of a test procedure, identify and describe the procedure:  If the error was found in qualification testing, identify and describe the test case; otherwise, leave the field blank. 
Error discovered by:  Name the individual reporting the error.
The problem occurred:  If the error is in the code execution, indicate the frequency of the problem.  If not, leave the field blank.
Where did you see this problem (site location):  Indicate the physical site and platform where the error was encountered.

Section B ( Analysis):
Analyzed by:  Individual who performed the analysis.
Req. Comp. Date:  Required completion date for the analysis.
Comp. Date:  Individual analyzing the request enters the date the analysis was complete.
Source of error (code units(s) and/or documentation):  Identify the error(s) location(s).  If no error was found, write "None."  If the error was corrected, enter "the error was corrected in Version X."
S/W (software) Product(s) affected (code units and/or documentation):  List all code units and/or documentation to be changed if the error is corrected.
Additional problems found during analysis:  Document any other potential errors or problems discovered while performing this analysis.

Section C (Resolution)
Action Taken:  Determine and document the appropriate action to be taken.  If a change in a software product is required, the project software configuration management (SCM) manager provides a SCR number.  If a system-level change is required, the SCM manager provides a CCR number.
Explanation:  Add any other information to fully define and/or explain the resolution.
Reviewed By:  Enter the project software manager's name after the review.
Date:  Date review was completed.

 Software Promotion Notification Form (SPNF)

This form is used to document a request that a software product(s) be placed under configuration management (CM).

SECTION A:  (automatically assigned):
PNF Number:  Unique number assigned to the request.

SECTION B:  (completed by Requester)
System/CSCI Name:  Select the System/CSCI to which the product belongs.
Product to be Promoted:  Fill in the following fields as appropriate to indicate specific location, name, and version of product.
File name(s):
Directory name:
Product name:
Version number:
SCR Number:  If the product modifies a baselined product, an approved Software Change Request (SCR) must be referenced.  If not, leave blank.
Promotion Level:  Promotion level for this product.
Requested by:  Enter name.
Date:  Date of promotion request.

SECTION C:  (completed by Software Engineering Manager or Project Software Manager)
Approved By:  Name of individual authorizing the promotion.  Promotion to the baseline level requires the project software manager's approval.
Date:  Date of approval.

SECTION D:  (completed by Librarian)
Completed:  List new directory, file name, etc. for product that was successfully promoted.  Otherwise, leave blank.
Unsuccessful:  Explain why product was not promoted.  Leave blank if product was successfully promoted.
Promoted by:  Enter name of person who promoted product.
Date:  Date of promotion.

 Weekly Development Effort Form (WDEF)

All project members and managers, with the exception of testers, should submit a completed WDEF to show work done on a project.  Submit one WDEF for each project worked on during the week.  

CSCI:  Select the name of the CSCI you worked on during the past week.
Activity:  Select the name of the activity(ies) for the CSCI listed above.
Hours:  Enter the total number hours you work on the listed activity.