(Project Plan for\ <REFERENCE>(PROJECT_NAME) <line><line> DIGITAL CONFIDENTIAL) <REVISION_INFO>(X0.2) <AUTHOR>(G. C. Everhart) <DATE> <ABSTRACT>(Abstract) This is the Project Plan for the development of <REFERENCE>(PROJECT_NAME). This capability is current planned as the basis for upgrades to the SCSI code base beginning in the GRYPHON release. This project plan is in: STAR::DOCD$:[EVMS.PROJECT_DOCUMENTS]SCSIArchitecture.PS and .TXT <ENDABSTRACT> <comment> <HEAD2>(Review Team) <SIGNATURES> <byline>(Ken Munsell\Group Manager) <byline>(Richard Critz\Technical Leader) <byline>(Pat St. Laurent\Supervisor) <endcomment> <ENDTITLE_PAGE> <COPYRIGHT_PAGE> <COPYRIGHT_DATE>(1995) <ENDCOPYRIGHT_PAGE> <CONTENTS_FILE> <PREFACE>(-4) This Project Plan describes how to build, test, integrate, and deliver the Software Component <REFERENCE>(PROJECT_NAME) for OpenVMS AXP (and/or) OpenVMS VAX. <SUBHEAD1>(Associated Documents) <LIST>(NUMBERED) <LE>Investigation Report: STAR::DOCD$:[EVMS.PROJECT_DOCUMENTS]IR-SCSIArchitecture.PS <LE>Design Specification: STAR::DOCD$:[EVMS.PROJECT_DOCUMENTS]DS-SCSIArchitecture.PS <ENDLIST> <SUBHEAD1>(Change History) <TABLE> <TABLE_ATTRIBUTES>(\MULTIPAGE) <TABLE_SETUP>(3\10\7) <TABLE_HEADS>(Date\Issue #\Description/Summary of Changes) <comment>Use as many <TABLE_ROW> tags as required, using the SCSIArchitectures shown as a guide. If you have a long list, use the tags <TABLE_ROW_BREAK>(FIRST) and <TABLE_ROW_BREAK>(LAST) to allow the table to break across pages. <endcomment> <TABLE_ROW>(April 1\0.1\Review version) <COMMENT> ***** BE SURE TO UPDATE DATE_LAST_CHANGED ******<ENDCOMMENT> <DEFINE_SYMBOL>(DATE_LAST_CHANGED\April 1) <ENDTABLE> <ENDPREFACE> <ENDFRONT_MATTER> <RUNNING_TITLE>(Digital Equipment Corporation--Project Plan\Digital Confidential) <HEAD1>(Project Description) <comment> Describe the project, stating what it is, and why the work should be done. Identify any unusual or problematical areas. Specify whether the work is for both VAX and Alpha, or for only one platform. <endcomment> The SCSI architecture project is part of an effort to proactively maintain the SCSI code base by producing first an overall architecture (meta design) document (which is the subject of the architecture project) and subsequently reworking parts of the SCSI code base to conform to the documented design. The problem, as has been determined by responsible technical people and confirmed by the SCSI group's own retrospective, is that the SCSI code has become difficult to maintain and understand. This has been attributed to the lack of any residual design, the absence from the scene of all the original designers of the ancestral code, and to the tendency the code shows to having grown by accretion as patches have been piled on patches to deal with one-up problems. At any rate, no functional specification, design, or other reliable document save the source code itself describes the existing SCSI code base, and there is no population of "code gurus" available to fill the gap with oral lore. That this tends to exacerbate the situation is obvious. It has been feared that leaving this situation unaltered would lead to a large amount of bug fixing activity and make adding new features, new device support, and performance improvement impossible. Investigation has been conducted informally. Alternatives rejected early on included porting the DEC Unix CAM code base to VMS (believed to be too costly in terms of handling the different VMS synchronization requirements and technically risky) and continuing a maintenance mode (believed to lead to paralysis and high QAR/CLD costs as new devices appear in the field). It was also stated early on that resources did not and do not exist to rewrite the entire SCSI code base all at once. The alternative preferred was to develop a clean architecture from the start, writing down the rationale for decisions embedded there, and develop a plan for selective migration of parts of the system while continuing to use others with possibly some glue code to enable use of existing components with new ones. The approach of simply cleaning up the existing implementation without considering other possibilities, it should be added, was also rejected early, since this would foreclose any possibility of major improvements which might result from encouraging "blue sky" thinking as input to the ultimate top level design. Rather, it was decided to attempt to elicit as many "blue sky" ideas as possible from the resident VMS SCSI experts in order to acquire a fund of such ideas some of which might be used in an improved top level ordering of the design. This was NOT intended to mean that a result of the group investigation might not be largely or even wholly identical to the VMS 6.2 SCSI design, but rather that it was necessary that group members examine alternatives, in a fairly unconstrained way, and write down what their conclusions were about what the best SCSI implementation they could think of would look like. The difference is that other possibilities WERE to be considered, and that choices, and reasons for choices, were to be written down. The architecture project specifically has been directed to produce a clean SCSI architecture. A bias was stated to the responsible engineer that a clean migration path exist, though this was treated as a refutable presumption. A sufficiently promising new design might cause downstream plans for migration to be readdressed, though it was considered most likely that such a revolutionary design would not be forthcoming. (That the current code base on the whole has been functioning well argued that the result would be closer to a cleanup than a rebuild from scratch.) The plan for migration becomes important late in the architecture definition phase, since it influences many detail decisions which must be made. The major uncertainty about the project stems from its level of abstraction. It involves creating a design FOR designs, at the very top level of abstraction, and hence is rather far removed from the usual and concrete problems one encounters in making actual devices work. While some aspects of the layering chosen are informed by the collective experience of the workers in how the existing code base is laid out, and while the result must conform to what the rest of VMS needs from disk, tape, etc. drivers, describing a top level design in the absence of many particulars runs the risk of losing touch with what is possible to real code and real devices. This risk has been mitigated by the tendencies of the SCSI experts to consider concrete examples, but cannot be fully retired until architecture-compliant code is built and tested, and the architecture revised to conform to any lessons learned. Therefore the architecture document is viewed not as a graven-in-stone monument, but as a mutable document which must be made to conform to the VMS understanding of the SCSI world over time. <HEAD2>(Goals) <comment> Give a list of the specific goals of the project <endcomment> <HEAD2>(Non-Goals) <comment> List any specific non-goals for the project <endcomment> <HEAD2>(Staffing) <comment> Show all team members involved in this project, the percentage of time dedicated to the project, and how long they expect to be involved. <endcomment> <table>(Project Staffing) <table_setup>(4\15\15\10) <table_heads>(Contributor\Function\Percentage\Time) <table_row>(Person 1\Developer\100%\6 months) <table_row>(Person 2\Project Leader\50%\8 months) <table_row>(Person 3\Test Writer\40%\1 month) <ENDTABLE> <HEAD1>(Tasks and Estimates) <comment> Describe each task, person responsible, and the length of time to complete it. <endcomment> <reference>(TASKS) contains the project tasks and time estimations for implementing <reference>(PROJECT_NAME). <table>(Project Tasks and Time Estimates\TASKS) <table_setup>(3\35\10) <table_heads>(Task\Engineer(s)\Time Estimate) <table_row>(Finish project\Person 1\1 day) <ENDTABLE> <head1>(Integration Criteria) <comment> List the contents of each project baselevel to be integrated. (Include coding milestones and regression tests.) Describe what criteria is being used to determine readiness for integration. Be sure to include any special configurations or requirements that may be needed at the time your project integrates. <endcomment> This section lists the integration steps for checking in changes for the SCSIArchitecture project. <table>(Integration Steps\ISTEPS) <table_setup>(3\5\35) <table_heads>(Step #\Description\Date Planned) <table_row>(1\Finish project\Oct. 31, 1995) <endtable> The following criteria will be used at each integration step to determine readiness to integrate: <HEAD1>(Defect Containment) <comment> Describe the work being done in the project for defect containment. This would include reqression tests, code review and/or inspection, special testing within QTV or elsewhere, etc. Work planned with groups other thant the project team should indicate the person in the other group who is the contact, and give an overview of the plans. <endcomment> <HEAD2>(Pre-integration testing ) <comment> Describe how you will be testing prior to integrating your code. If the QTV group is involved, provide the contact name. <endcomment> <HEAD2>(Post-integration testing ) <comment> Describe how you will be testing after integrating your code. If the QTV group is involved, provide the contact name. <endcomment> <HEAD2>(Dependencies of this Project on other Projects/Events/Resources ) <comment> Describe any dependencies your project has on outside forces that could affect its success. When possible describe what is being done to track and minimize these depencencies. <endcomment> There are no dependencies of this project on other project/events. <HEAD2>(Dependencies of other Project/Events on this Project) <comment> Describe any other projects that are dependent on your project for their success. When possible describe what is being done to minimize the impact to other projects. <endcomment> There are no other projects dependent on this project. <HEAD2>(Risks) <comment> State any currently known risks and the steps that are being taken to address them. <endcomment> <HEAD2>(Contingencies) <comment> Describe and contingency plans you are considering. For example, if this is a hardware based project, what will happen if the hardware slips. <endcomment> If the hardware slips we are going on vacation. <HEAD1>(Special Field Test Considerations) <comment> Describe the type and number of field test sites required. <endcomment> There are no specific field test requirements for this project above the current requirement for OpenVMS. <HEAD1>(Documentation) <comment> Describe which current manuals will need changes, and what new manuals will need to be written. Identify the documentation contact for this project. <endcomment> <HEAD1>(Security) <comment> Describe any known security impact this project will have. If you are unsure how to assess this, see Bill Davenport. <endcomment> <HEAD1>(Internationalization) <comment> Describe and known impact this project will have on internationalization issues. If you are unsure how to assess this, see C. J. Coppersmith. <endcomment> <HEAD1>(Performance) <comment> Describe any potential performance issues that may be created by this project, and how you are measuring and handling them. If you are unsure how to assess this, see Sue Lindenberg. <endcomment> <HEAD1>(Issues) <comment> Provide a list of outstanding issues. As they are resolved describe the resolution in the resolved issues section when you update the project plan. New issues would be added to the outstanding issues section. <endcomment> <HEAD2>(Outstanding Issues) <HEAD2>(Resolved Issues) None at this time. <head1>(Project Milestones) <comment> This section describes your schedule <endcomment> <table>(Milestones) <table_attributes>(keep) <table_setup>(3\35\10) <table_heads>(Milestone\Date\Actual) <table_row>(Finish project \Oct. 31, 1995\) <endtable> <head1>(Changed Modules) <comment> To the best of your ability, list those modules and/or components that your project will be changing. This should be updated as the project moves along. <endcomment> <list>(unnumbered) <le>bigmodule.b32 <endlist>

$ DOCUMENT/CONTENTS PP-SCSIArchitecture.SDML REPORT PS This is the project plan template for the Gryphon release of OpenVMS. The template describes the information that the release team needs to do the best job possible integrating your project with V7.1. You are not _required_ to use this template; rather, Kathryn Begley designed this template in response to requests that many project leaders have made for a project plan template. This template was reviewed by several persons, among them Clair Grant, who provided these comments -- I think his words are well taken: A little history. If you haven't already, you should look at DOCD$:[EVMS.PROJECT_DOCUMENTS]LIFE_OF_A_PROJECT.PS to see what our thoughts were on what should be in a project plan. Also, an earlier version of this document had a third quote on the front page, "A template is no substitute for thinking." (PROJECT_NAME\SCSIArchitecture Project) (Project Plan for\ <REFERENCE>(PROJECT_NAME) <line><line> DIGITAL CONFIDENTIAL) <REVISION_INFO>(X0.2) <AUTHOR>(G. C. Everhart) <DATE> <ABSTRACT>(Abstract) This is the Project Plan for the development of <REFERENCE>(PROJECT_NAME). This capability is current planned as the basis for upgrades to the SCSI code base beginning in the GRYPHON release. This project plan is in: STAR::DOCD$:[EVMS.PROJECT_DOCUMENTS]SCSIArchitecture.PS and .TXT <ENDABSTRACT> <comment> <HEAD2>(Review Team) <SIGNATURES> <byline>(Ken Munsell\Group Manager) <byline>(Richard Critz\Technical Leader) <byline>(Pat St. Laurent\Supervisor) <endcomment> <ENDTITLE_PAGE> <COPYRIGHT_PAGE> <COPYRIGHT_DATE>(1995) <ENDCOPYRIGHT_PAGE> <CONTENTS_FILE> <PREFACE>(-4) This Project Plan describes how to build, test, integrate, and deliver the Software Component <REFERENCE>(PROJECT_NAME) for OpenVMS AXP (and/or) OpenVMS VAX. <SUBHEAD1>(Associated Documents) <LIST>(NUMBERED) <LE>Investigation Report: STAR::DOCD$:[EVMS.PROJECT_DOCUMENTS]IR-SCSIArchitecture.PS <LE>Design Specification: STAR::DOCD$:[EVMS.PROJECT_DOCUMENTS]DS-SCSIArchitecture.PS <ENDLIST> <SUBHEAD1>(Change History) <TABLE> <TABLE_ATTRIBUTES>(\MULTIPAGE) <TABLE_SETUP>(3\10\7) <TABLE_HEADS>(Date\Issue #\Description/Summary of Changes) <comment>Use as many <TABLE_ROW> tags as required, using the SCSIArchitectures shown as a guide. If you have a long list, use the tags <TABLE_ROW_BREAK>(FIRST) and <TABLE_ROW_BREAK>(LAST) to allow the table to break across pages. <endcomment> <TABLE_ROW>(April 1\0.1\Review version) <COMMENT> ***** BE SURE TO UPDATE DATE_LAST_CHANGED ******<ENDCOMMENT> <DEFINE_SYMBOL>(DATE_LAST_CHANGED\April 1) <ENDTABLE> <ENDPREFACE> <ENDFRONT_MATTER> <RUNNING_TITLE>(Digital Equipment Corporation--Project Plan\Digital Confidential) <HEAD1>(Project Description) <comment> Describe the project, stating what it is, and why the work should be done. Identify any unusual or problematical areas. Specify whether the work is for both VAX and Alpha, or for only one platform. <endcomment> The SCSI architecture project is part of an effort to proactively maintain the SCSI code base by producing first an overall architecture (meta design) document (which is the subject of the architecture project) and subsequently reworking parts of the SCSI code base to conform to the documented design. The problem, as has been determined by responsible technical people and confirmed by the SCSI group's own retrospective, is that the SCSI code has become difficult to maintain and understand. This has been attributed to the lack of any residual design, the absence from the scene of all the original designers of the ancestral code, and to the tendency the code shows to having grown by accretion as patches have been piled on patches to deal with one-up problems. At any rate, no functional specification, design, or other reliable document save the source code itself describes the existing SCSI code base, and there is no population of "code gurus" available to fill the gap with oral lore. That this tends to exacerbate the situation is obvious. It has been feared that leaving this situation unaltered would lead to a large amount of bug fixing activity and make adding new features, new device support, and performance improvement impossible. Investigation has been conducted informally. Alternatives rejected early on included porting the DEC Unix CAM code base to VMS (believed to be too costly in terms of handling the different VMS synchronization requirements and technically risky) and continuing a maintenance mode (believed to lead to paralysis and high QAR/CLD costs as new devices appear in the field). It was also stated early on that resources did not and do not exist to rewrite the entire SCSI code base all at once. The alternative preferred was to develop a clean architecture from the start, writing down the rationale for decisions embedded there, and develop a plan for selective migration of parts of the system while continuing to use others with possibly some glue code to enable use of existing components with new ones. The approach of simply cleaning up the existing implementation without considering other possibilities, it should be added, was also rejected early, since this would foreclose any possibility of major improvements which might result from encouraging "blue sky" thinking as input to the ultimate top level design. Rather, it was decided to attempt to elicit as many "blue sky" ideas as possible from the resident VMS SCSI experts in order to acquire a fund of such ideas some of which might be used in an improved top level ordering of the design. This was NOT intended to mean that a result of the group investigation might not be largely or even wholly identical to the VMS 6.2 SCSI design, but rather that it was necessary that group members examine alternatives, in a fairly unconstrained way, and write down what their conclusions were about what the best SCSI implementation they could think of would look like. The difference is that other possibilities WERE to be considered, and that choices, and reasons for choices, were to be written down. The architecture project specifically has been directed to produce a clean SCSI architecture. A bias was stated to the responsible engineer that a clean migration path exist, though this was treated as a refutable presumption. A sufficiently promising new design might cause downstream plans for migration to be readdressed, though it was considered most likely that such a revolutionary design would not be forthcoming. (That the current code base on the whole has been functioning well argued that the result would be closer to a cleanup than a rebuild from scratch.) The plan for migration becomes important late in the architecture definition phase, since it influences many detail decisions which must be made. The major uncertainty about the project stems from its level of abstraction. It involves creating a design FOR designs, at the very top level of abstraction, and hence is rather far removed from the usual and concrete problems one encounters in making actual devices work. While some aspects of the layering chosen are informed by the collective experience of the workers in how the existing code base is laid out, and while the result must conform to what the rest of VMS needs from disk, tape, etc. drivers, describing a top level design in the absence of many particulars runs the risk of losing touch with what is possible to real code and real devices. This risk has been mitigated by the tendencies of the SCSI experts to consider concrete examples, but cannot be fully retired until architecture-compliant code is built and tested, and the architecture revised to conform to any lessons learned. Therefore the architecture document is viewed not as a graven-in-stone monument, but as a mutable document which must be made to conform to the VMS understanding of the SCSI world over time. <HEAD2>(Goals) <comment> Give a list of the specific goals of the project <endcomment> <HEAD2>(Non-Goals) <comment> List any specific non-goals for the project <endcomment> <HEAD2>(Staffing) <comment> Show all team members involved in this project, the percentage of time dedicated to the project, and how long they expect to be involved. <endcomment> <table>(Project Staffing) <table_setup>(4\15\15\10) <table_heads>(Contributor\Function\Percentage\Time) <table_row>(Person 1\Developer\100%\6 months) <table_row>(Person 2\Project Leader\50%\8 months) <table_row>(Person 3\Test Writer\40%\1 month) <ENDTABLE> <HEAD1>(Tasks and Estimates) <comment> Describe each task, person responsible, and the length of time to complete it. <endcomment> <reference>(TASKS) contains the project tasks and time estimations for implementing <reference>(PROJECT_NAME). <table>(Project Tasks and Time Estimates\TASKS) <table_setup>(3\35\10) <table_heads>(Task\Engineer(s)\Time Estimate) <table_row>(Finish project\Person 1\1 day) <ENDTABLE> <head1>(Integration Criteria) <comment> List the contents of each project baselevel to be integrated. (Include coding milestones and regression tests.) Describe what criteria is being used to determine readiness for integration. Be sure to include any special configurations or requirements that may be needed at the time your project integrates. <endcomment> This section lists the integration steps for checking in changes for the SCSIArchitecture project. <table>(Integration Steps\ISTEPS) <table_setup>(3\5\35) <table_heads>(Step #\Description\Date Planned) <table_row>(1\Finish project\Oct. 31, 1995) <endtable> The following criteria will be used at each integration step to determine readiness to integrate: <HEAD1>(Defect Containment) <comment> Describe the work being done in the project for defect containment. This would include reqression tests, code review and/or inspection, special testing within QTV or elsewhere, etc. Work planned with groups other thant the project team should indicate the person in the other group who is the contact, and give an overview of the plans. <endcomment> <HEAD2>(Pre-integration testing ) <comment> Describe how you will be testing prior to integrating your code. If the QTV group is involved, provide the contact name. <endcomment> <HEAD2>(Post-integration testing ) <comment> Describe how you will be testing after integrating your code. If the QTV group is involved, provide the contact name. <endcomment> <HEAD2>(Dependencies of this Project on other Projects/Events/Resources ) <comment> Describe any dependencies your project has on outside forces that could affect its success. When possible describe what is being done to track and minimize these depencencies. <endcomment> There are no dependencies of this project on other project/events. <HEAD2>(Dependencies of other Project/Events on this Project) <comment> Describe any other projects that are dependent on your project for their success. When possible describe what is being done to minimize the impact to other projects. <endcomment> There are no other projects dependent on this project. <HEAD2>(Risks) <comment> State any currently known risks and the steps that are being taken to address them. <endcomment> <HEAD2>(Contingencies) <comment> Describe and contingency plans you are considering. For example, if this is a hardware based project, what will happen if the hardware slips. <endcomment> If the hardware slips we are going on vacation. <HEAD1>(Special Field Test Considerations) <comment> Describe the type and number of field test sites required. <endcomment> There are no specific field test requirements for this project above the current requirement for OpenVMS. <HEAD1>(Documentation) <comment> Describe which current manuals will need changes, and what new manuals will need to be written. Identify the documentation contact for this project. <endcomment> <HEAD1>(Security) <comment> Describe any known security impact this project will have. If you are unsure how to assess this, see Bill Davenport. <endcomment> <HEAD1>(Internationalization) <comment> Describe and known impact this project will have on internationalization issues. If you are unsure how to assess this, see C. J. Coppersmith. <endcomment> <HEAD1>(Performance) <comment> Describe any potential performance issues that may be created by this project, and how you are measuring and handling them. If you are unsure how to assess this, see Sue Lindenberg. <endcomment> <HEAD1>(Issues) <comment> Provide a list of outstanding issues. As they are resolved describe the resolution in the resolved issues section when you update the project plan. New issues would be added to the outstanding issues section. <endcomment> <HEAD2>(Outstanding Issues) <HEAD2>(Resolved Issues) None at this time. <head1>(Project Milestones) <comment> This section describes your schedule <endcomment> <table>(Milestones) <table_attributes>(keep) <table_setup>(3\35\10) <table_heads>(Milestone\Date\Actual) <table_row>(Finish project \Oct. 31, 1995\) <endtable> <head1>(Changed Modules) <comment> To the best of your ability, list those modules and/or components that your project will be changing. This should be updated as the project moves along. <endcomment> <list>(unnumbered) <le>bigmodule.b32 <endlist>