MULTICS ADMINISTRATIVE BULLETIN MAB-066 To: MAB Distribution From: Benson I. Margulies Ron Barstad Date: August 8, 1985 Subject: Multics Configuration Management: Software Development Abstract This document details the configuration management procedures to be followed during the development of Multics software. It is part of the set of documents that defines Multics Configuration Management. For an overview of this set, see MAB-070, "Multics Configuration Management: Policy Statement". _________________________________________________________________ Multics Project internal working documentation. Not to be reproduced or distributed outside the Multics project. i MAB-066 Config. Mgmt.: Software Development CONTENTS Page Introduction . . . . . . . . . . . 1 Scope of These Procedures . . . . . 1 Change Initiation . . . . . . . . . 1 Peer Review . . . . . . . . . . . . 1 Change Description . . . . . . . 2 Describing a Change With an MTB . . . . . . . . . . . . 2 Describing a Change With an MCR . . . . . . . . . . . . 3 Technical Change Review . . . . 3 Design Review . . . . . . . . 3 Submitting an MCR . . . . . . 4 Review of MCRs . . . . . . . 4 Tracking Changes . . . . . . . . . 5 Implementation . . . . . . . . . . 5 Standard Implementation . . . . 5 TCB implementation . . . . . . . 6 Audit . . . . . . . . . . . . . . . 7 TCB Security Audit . . . . . . . 7 Installation . . . . . . . . . . . 7 ii Config. Mgmt.: Software Development MAB-066 Introduction This document describes the software configuration management procedures that govern Multics software development. Scope of These Procedures These procedures apply to the following Multics materials: o Standard Product Software o TCB Design Documentation o TCB Security Functional Tests o TCB Functional Test Support Software These procedures describe the requirements for ordinary software development. Other procedures (emergency changes described in MAB-057 and critical fixes in MAB-063) govern changes made on an emergency basis to resolve a critical bug at an exposure or customer site. Note, though, that the emergency procedures require that the normal requirements be met after the emergency is resolved. These procedures assume that the driving item in a system change is a change to standard software or functional test support software. In such a case, the changes to documentation will be made to describe the change, and changes to tests will be made to test new features or to update a test to conform to a new interface specification. Sometimes, however, the documentation or the tests will be changed independently of the code. An example of this would be a bug in a test program. In these cases, there need not be any associated documentation or tests that must be updated as part of the change. Change Initiation Changes to Multics begin with individual members of the development community (contributorts). Contributors change the system because: * They respond to a requirement formally presented through management channels. * They respond to a reported bug. * They have an idea for an improvement to the system. 1 MAB-066 Config. Mgmt.: Software Development Peer Review No change may be included in the system under these procedures unless approved by peer review. The peer review process is completely described in MAB-048, "Rules for Multics Change Review Boards". To present a proposed change for peer review, a contributor must describe it in a document. CHANGE DESCRIPTION The form of the description required depends on the size of the change. If the change is large (as described below), the contributer first must prepare a Multics Technical Bulletin (MTB), a detailed description of his proposed design. After the MTB has been reviewed (see below), he must prepare a Multics Change Request (MCR) to formally request technical approval of his change. If the change is small, he may skip the MTB, and start with the MCR. In either case, he is required to describe: o Any new or changed user interfaces to the system. o Any new or changed internal interfaces that are callable outside of their particular area of the system. o important new data structures, or changes to existing important data structures. o significant changes or additions to design philosophies, in particular security policies. In short, he must provide enough information for his technical peers to intelligently evaluate his proposal. In particular, note that he must provide a complete description of any changes to interfaces that are described in published documentation. This description is used by the Documentation Unit to prepare user documentation. A complete and detailed description of the proposed implementation need not be provided unless the area of the system is one so crucial that prior technical review to that level is required. This requirement is established on a case-by-case basis by the peer review system. Describing a Change With an MTB Contributors write MTBs to describe large or complicated system changes. In particular, a contributor will write an MTB when he thinks that the change meets any of the following criteria: 2 Config. Mgmt.: Software Development MAB-066 o The change will alter the central design philosophy, data structures, or security policy of the system or one of its subsystems. o The change will add a new subsystem to the system.(1) o The documentation required will be more than six pages. o Teh change involves design issues which have several possible solutions. Describing a Change With an MCR An MCR is a brief specification of a change to the system. Contributors prepare MCRs by filling out a standard form which describes the change. Contributors write MCRs for changes that are not large enough to meet the criteria given above for MTBs, and to request final approval of the installation of changes described in MTBs. MAB-048, "Rules for Multics Change Review Boards", describes MCR forms. The following is a brief summary of the peer review process. TECHNICAL CHANGE REVIEW All change proposals are reviewed by the staff of the Multics Development Center. The focal point of technical review is the MCR Board. This board, which is described in more detail below and in MAB-048 "Rules for Multics Change Review Boards", reviews both large (MTB) and small (MCR) proposals. The Board does not directly examine MTBs. Instead, the author of the MTB conducts a design review in which a small group of knowledgable contributors examine the proposal in detail. When the design review is complete, the MTB is updated to reflect its results. The MCR presented before the MCR Board summarizes the updated design and refers to the MTB. Design Review To conduct a design review, a contributor must find other developers to serve as reviewers. To be effective, these reviewers will need to have knowledge of the changed software. _________________________________________________________________ (1) A subsystem is a significant body of code that provides a set of related functions, and has a clear modularization that separates it from the rest of the system. Page control, RCPRM, and the directory salvager are all examples of subsystems. 3 MAB-066 Config. Mgmt.: Software Development If the proposal includes changes to the TCB, the Security Coordinator must be one of the reviewers. Each of the reviewers reads the proposal and comments on its content. The contributor must resolve all questions, complaints, and suggestions. Ordinarily, he will seek a consensus of the reviewers. When no consensus can be reached, he must make his own decision. When the design review is complete, the contributor must make its results available to MDC. This facilitates the next step in the review process. If the design review resulted in any significant changes to the proposal, he must revise the MTB to reflect the changes. If there were significant disputes, and especially if there were issues on which no consensus was reached, he must prepare an additional MTB that describes the disputes and their resolution, if any. Once these steps are complete, he may proceed to MCR Board review of his proposal by preparing an MCR that offers his original MTB and the design review results MTB, if any, for review. Submitting an MCR To submit an MCR for consideration, a contributor must first obtain the approval of a sponsor and the contributor's manager. The sponsor of an MCR is a contributor who is willing to vouch for its correct format. The sponsor must check that the MCR is complete. For TCB-related MCRs, the sponsor also takes responsibility for its technical plausibility. The sponsor must be a contributor with some detailed knowledge of the area of the system involved. The manager listed on an MCR is the submitter's unit manager. The manager signs the MCR to indicate that he has checked the MCR for correct form, has ensured that the submitter has indeed chosen an appropriate sponsor, and has committed the necessary development resources to implement the change. Review of MCRs MCRs are initially reviewed by the Greater MCR Board (GMCRB), which consists of all of the contributors in the Multics development organization who volunteer their time. GMCRB members discuss the MCR amongst themselves. The discussion process may include friendly amendments. If no problems with the MCR surface during the GMCRB review, the MCR passes. If an MCR proves controversial, it is referred to the Executive MCR Board (EMCRB). This much smaller group has the final technical say. 4 Config. Mgmt.: Software Development MAB-066 Tracking Changes As a software module proceeds through development, auditing and installation, its progress is tracked by history comments placed at the beginning of the source module. The history_comment (hcom) command creates, updates and displays these comments, and checks that comments exist prior to submission and prior to installation. This method ensures that changes are properly tracked throughout the software development cycle. Refer to MTB-716 for a description of the history_comment command. Points in the development process at which the history_comment command should be used are identified below. Implementation When the MCR Board has approved an MCR, the contributor proceeds to implement the change. Ideally, no implementation precedes the review process. In fact, some implementation is often required to discover a feasible or optimal design to propose. The crucial requirement is that a contributor is obligated to implement the design as approved by the review process. If he has implemented in advance of approval, and the final, approved, design is different, he must change the implementation to conform to it. When a new module is created, or an existing module is changed, a history comment must be added to the module to summarize the change. This can be done with a history_command command line, such as: hcom add prog_path.pl1 The hcom command will prompt for an approval field (MCR, MECR or PBF number), and for a brief summary of the change. If the change has not been approved when the comment is first added, it can be added later with a command like: hcom update prog_path.pl1 -approve MCR7235 STANDARD IMPLEMENTATION The implementation must conform to coding standards. Coding standards are documented in MAB-068, "Programming Standards". This provides guidelines for writing efficient, readable Multics PL/I programs. In particular, it includes a section of standards for gate targets, privileged servers, and other security-critical programs. 5 MAB-066 Config. Mgmt.: Software Development In general, a programmer must make his program look like other programs in the same subsystem. If he does not, he must have a good reason. TCB IMPLEMENTATION When changing the TCB, the contributor must satisfy three additional implementation requirements: o Modify/Update Functional Tests If the change adds interfaces to the TCB, the contributor must provide functional tests. If the interface implements no security properties, and thus requires no functional test, the contributor must provide appropriate documentation. If the change modifies the functional behavior of a TCB interface, the contributor must update the relevant functional test. o Run Functional Tests The contributor must run the functional tests for the interface(s) affected by the change, and preserve the results. o Design Documentation If the change includes areas of the TCB covered by the the official design documents (Multics Design Documents (MDDs)), the contributor must prepare an updated version of any MDDs that cover areas changed. If the change adds a new subsystem to the TCB, an MDD must be written to describe the subsystem. MAB-068, "Programming Standards", includes standards for these documents. All changes to the TCB must be accompanied by a description of the changes to the system design and implementation. The MCR(s) and/or MTB(s) that document this change must contain an accurate summary of the changes to the code and design. The contributor is not required to include an implementation summary in his design review documentation. If he originally provided such a summary, and the implementation conforms to it perfectly, then no further work is required. If he did not provide it, or if the final implementation differs from it, he must prepare an updated version of the documentation (MCR and/or MTB) that correctly describes the implementation. He must publish updated MTBs as revisions. He must attach updated MCRs to the installation materials supplied to the Auditor. 6 Config. Mgmt.: Software Development MAB-066 Audit When the implementation is complete, the contributor proceeds with audit. An audit is a independent verification that the implementation meets its requirements. Procedures and standard for auditing are documented in MAB-069, "Multics Configuration Managemnet: Guidelines for Auditing Software". The following summarizes the audit process. The developer gives the auditor access to the directory containing the source and other changes (bind file for example). The auditor then removes the developer's access to modify that source and creates listing and compare_asciis of the new source and the installed versions. After a source module has passed all auditing guidelines, the auditor must update all new history comments in the program to indicate that it was audited. A typical command line might be: hcom update prog_path.pl1 -audit When finished, the auditor submits the MSCR form for installation, giving the pathnames of his copy of the source modules. Audit and implementation may be an iterative process; if the auditor finds deficiencies in the implementation the contributor fixes them and returns to the auditor for further audit. TCB SECURITY AUDIT If the implementation includes any changes to the TCB, the audit materials defined above must be submitted to the Security Coordinator for a post-audit. The Security Coordinator's approval is required for installation of the change. Installation When the implementation has passed audit, the contributor submits it to the installation project for installation in the standard libraries. To make the submission, the contributor prepares a set of materials that describes the installation. The requirements for these materials are specified in MAB-056 "Multics Configuration Management: Installing Planned Changes in System Libraries" and MAB-067 "Procedures for Software Installation and Integration. The auditor, the unit manager and the Security Coordinator (for TCB changes) must all approve the materials before they are submitted to the installation project. Just prior to submission of the installation, the auditor 7 MAB-066 Config. Mgmt.: Software Development uses a command line against all the source modules to ensure that the history comments are complete and ready for submission: hcom check prog_path.pl1 -validate hcom_mdc_validate_ This command line should be run after the programs are on System M, ready for installation, because the validation routine only works on System M where the MCR database is. 8