Inter-Office MemorandumToCedar ImplementorsDateMay 26, 1982FromRoy LevinLocationPalo AltoSubjectCedar Releases: Policies and ProceduresOrganizationPARC/CSLXEROX Filed on: [Indigo]Documentation>ReleaseProcedures.pressThis memo describes the policies and procedures that individuals contributing to Cedar releasesneed to understand and observe. It assumes general familiarity with Cedar and DF files.The Release ProcessComponents and DF FilesThroughout this memo, we call the unit of software submitted to the Cedar release process acomponent. Each component is described by a DF file, a simple description mechanism that ischiefly a list of file names (complete IFS paths) and creation dates (either explicit or implicit). Thismemo assumes familiarity with DF files; complete information may be found in the referencemanual stored on [Indigo]Documentation>DFFilesRefMan.press. On occasion, a particularly largeor complicated component may be more easily described by a collection of DF files. This is acceptable, but there mustbe a single "root" of the collection which includes (in the technical sense) the rest. A DF file containsinformation that describes the component for three distinct but related purposes. First, it identifieseverything needed by the implementor to build the component from scratch. Second, it identifiesthe subset of files that are necessary for a client of the component. Third, it describes the way inwhich the files that make up the component are to be distributed at release time. It is theresponsibility of the implementor to ensure that a DF file intended for release as part of Cedarfulfills all three of these descriptive functions; this memo contains rules that help him in doing so.Release PhasesA release cycle consists of a development phase following by an integration phase culminated by arelease. There is an individual, the Release Master, who monitors the release cycle and isresponsible for the orderly progression from one phase to the next. The development phase lastsfor days or weeks and is a period of largely unconstrained program modification and enhancement.The scope and duration of the development is release-dependent and is generally not completelyspecified when the development phase begins, although each implementor generally knowsapproximately what he intends to contribute to the next release. At some point, the Release Masterinitiates the integration phase and the following sequence of events then occurs:1)The Release Master sends a message to CedarImplementors^.pa announcing thebeginning of the integration phase. Obviously, you must be a member of CedarImplementors^.pato receive this message; if you are a new implementor, you should verify that you are on this list. Themessage requests implementors to complete the development of their releasecomponents and submit them by responding to the Release Master with a specific]gpi c8q]rX-q7Br ]q]r-q7Br Yq]r(-q 7BrSsr N#qF> GrV FX At >u ;Ar? 9ur$ur' 7&C 6K< 4 5v# 3 :< 1Pr /?( .M-3 ,Z *4( )WC ' Z $au !rurur kur: H $< u> V '@# Q 1:r;:v8:Jr: ;VW-: 4 p L>]0Cedar Releases: Policies and Procedures2message form. Both the contents of the form and the submission itself must satisfy anumber of rules before the Release Master will accept the submission for inclusion inthe upcoming release. These rules are presented in detail later in this memo. Themessage announcing a submission is also sent to CedarImplementors^.pa so that otherimplementors can complete the preparation of their components.A component cannot be submitted to the Release Master until all of the components it depends upon havebeen announced. Experience shows that, if the release is expected to contain changes to fundamentalinterfaces (e.g., Pilot, Rope, IOStream), the Release Master should probably send the "call for integration"message only to the implementors of those central components. Once these submissions have beenaccepted, the Release Master can then send the "call for integration" to all implementors.2)The Release Master assembles a top-level description of the contents of the release andruns the Release Tool. This program has three phases, the first two of which check therelease submissions for consistency and completeness. The third phase moves the filesto the release directory and produces descriptions (DF files) of the release contents.Generally, however, the Release Tool will detect some problems during the execution ofits first two phases.3)The Release Master analyzes the error messages produced by the initial phases of theRelease Tool and contacts the implementors of the components that are in error. Theintegration phase of the release cycle is stalled until the implementors correct their erros;consequently, it is the responsibility of the implementors to do so as soon as possible.They notify the Release Master when they completed the necessary repairs.4)Steps 2 and 3 are repeated until the Release Master is satisfied of the consistency andcompleteness of the submissions. The Release Master then sends a message toCedarUsers^.pa announcing that a release is imminent and that the release directory willbe in an inconsistent state while the release is installed.5)The Release Master runs the third phase of the Release Tool, which copies the releasefiles to the release directory. The Release Master tries to make this phase as brief aspossible, anticipating potentially disabling problems (e.g., insufficient disk space on therelease directory) and taking the necessary precautions.6)When the release has been completely installed, the Release Master sends a message toCedarUsers^.pa announcing the release. The Release Master should compose this message duringstep 5 in order to minimize the time during which the release directory is inconsistent. The ReleaseMaster stores a copy of the release message on the documentation subdirectory of therelease directory, then prints and saves the logs produced by the Release Tool. Therelease is then complete.The Need for RulesA Cedar release typically includes thousands of files and hundreds of DF files, the latter with acomplex interconnection structure. It is not surprising that errors are committed during theintegration phase that force steps 3 and 4 to be repeated several times. Attention to the details ofpreparing a release submission can significantly reduce the duration of the integration phase.Experience shows that the three phases of the Release Tool can be completed in a few hours for amajor release, but, nevertheless, such releases generally take two days. The rest of the time ischiefly spent waiting for implementors to correct errors in their submissions. It is important tounderstand that normally these are not programming bugs in the usual sense; rather, they are errorsin the DF files that describe the components. Certain kinds of errors occur again and again, releaseafter release, and the rules below are intended to eliminate these recurring problems. ft(G:br5:`vD:^N:](',:[>@XUv;+:VB":UQ:T3>!:RZ O`r:r7:MO:LP:Jj2$:HE:G C:r7:B%Pu:@~E:>r)/:=/I 9:rP:89L:68:4; 1:r J:/9:.MN :,8 )W:rB:'&v *:& Ir :$a@:"B:! u ur/2 &7 'O ;# P 1 S  U 7, ;F V> L>\nCedar Releases: Policies and Procedures3These rules should be considered stronger than guidelines or suggestions but somewhat weaker thancommandments. Uniformity promotes smooth and speedy releases, but exceptional cases invariablyarise that do not fit the general model. Occasional reasonable deviations will be tolerated, but theRelease Master establishes the definition of "reasonable". Unreasonable deviations jeopardize therelease process and cannot be permitted. In all cases the implementor assumes completeresponsibility for any deviation from these rules. The Release Master will not correct errors insubmissions and will delay a release as necessary until an offending submission conforms to therequirements below. Rules for Constructing a Cedar Release DF FileThe following is a complete list of requirements that a DF file must satisfy in order to beacceptable as a component of a Cedar release. Unless explicitly indicated otherwise, the terms"import" and "export" refer to the Imports and Exports clauses in a DF file and not the similarly-named Cedar language notions. Also, the phrase "released to [X]Z>" is an abbreviation for "hasa ReleaseAs clause with path [X]Z>".1)The DF file name is considered to be the "name" of the component and should generallycorrespond to the name of the major exported interface (in the Mesa sense) supplied by thecomponent. This rule is most easily applied to straightforward packages with a single publicinterface.2)The DF file must contain a self--reference that is released to [Indigo]Top>. The self-reference must be exported.3)If separate documentation files accompany the component, they should be included in the DF fileand released to [Indigo]Documentation>. Documentation files in suitable form for onlineuse (not press files) should also be exported. It is not mandatory that documentation filesaccompany a component; comments in the public interfaces may be sufficient for use.However, most substantial components will have separate documentation files, and theseshould be included in the DF file as indicated. If a component has recently undergone asubstantial revision that is visible to its users, the implementor should probably releaseseparate files containing the "change summary" and the "complete truth".4)All component-specific files other than the DF file and documentation should be released to asubdirectory with the same name as the component (e.g., the interfaces and implementation ofSomePackage.df should be released to [Indigo]SomePackage>. It is permissible to haveadditional subdirectory structure within the component-specific subdirectory. Subdirectoriesof either [Indigo]Top> or [Indigo]Documentation> are not permitted.5)If the component supplies a "public interface", the source and object files must be exported fromthe DF file. The debugging and help facilities tend to work better if they can access thesources of interfaces as well as their compiled representations. Disk space concerns areirrelevant here, since the files involved are small and improvements in the file system willsoon eliminate the size limitations of the local disk.6)The BCD or BCDs that contain the bound-up implementation of the component must beexported from the DF file. Exception: if the implementation is intended for inclusion in theCedar boot file, it should not be exported. The motivation here is obvious; the component can'tbe used unless its implementation is available. ft(G brL `v-2 ^!D ](,6 [0' YW X2_ V Rht. Or[ MrP KG J#D H|' E- uB C M ArM @7 < uT  ;A 7r u_ 6K.1 4$ r- 2S 1UP /$4 .+/ ,_H ) uG 'iK %,r $F "sQ % uS  } r6 A /G 6 9 u5 D +r% C/ =XKCedar Releases: Policies and Procedures47)The entry in the DF file for the bound-up implementation of the component must be preceded bya "+" to indicate that it is a root BCD for processing by VerifyDF. If the component exportsmultiple BCDs, each of them must obey this rule. It is permissible to have other BCDsmarked with a "+", e.g., test programs.8)A file that is not a part of the component should be referenced using an "Imports" entry with aUSING list. The entry forms introduced by "ReadOnly" and "@", while documented in theDF reference manual, are obsolete and should not be used. The USING list documentsexplicitly dependencies on other components, protects against certain mistakes in imported DFfiles, and speeds up BringOver.9)An import from the release directory may include either an explicit or an implicit (i.e., ">" or"~=") date. An import from a working directory must specify an implicit date. While theserules may seem a bit unintuitive at first, experience shows that they greatly streamline therelease process. Last-minute, minor changes in a DF file are common during a releaseintegration, and a failure to observe the second rule in a DF file depending on the one thatchanged forces an otherwise unnecessary reconstruction of the dependent DF file. The last-minute changes are rarely significant to the importer(s); when they are, inconsistencies willdetected by the release machinery.10)The DF file for a component should usually include a text file containing command lines forcompiling and binding the package. This is not mandatory, but strongly recommended. It isnot necessary that this file be a complete command file; rather, it is intended more as andocumentary aid to someone unfamiliar with the structure of the component who finds itnecessary to make a small change and rebuild it. There is no standardization on the name ofsuch text files; most have the extension ".cm" (whether or not they are true command files)and many include the word "Make" and the component name in their names.11)If programs other than the Compiler and Binder are needed to build the component, entriesimporting them should be included in the DF file. Examples of such programs include thePackager, MakeBoot, and the TableCompiler. If specific versions of the Compiler and/or Binder arerequired (a rare situation), entries for them should be included as well; however, it is not necessary to referencethe standard ones.12)The working directory used for all non-imported files must grant read and create access toCedarAdministrators^.PA. The need for read access is obvious; the component can't bereleased unless it can be read. The need for create access is rarely exercised but isoccasionally needed when a small change to a component is required in order to complete arelease integration and the implementor is not available. Note that the heavily-used workingdirectories [Indigo] and [Indigo] satisfy these requirements, whilepersonal directories typically do not. Implementors who use their personal directories forrelease submissions must explicitly alter the IFS access controls to their directories to conformto this rule.A Sample DF FileThe DF file below satisfies the requirements for submission to a Cedar release. It describes acomponent named Sample, which consists of a single configuration named SampleImpl.Sample has two public interfaces, named Sample and SampleExtras. The implementationconsists of two modules, SampleImplA and SampleImplB, which share a private definitionsmodule named SamplePrivate. It requires three other components, defined by DF files namedPilotInterfaces.df, Rigging.df, and Runtime.df. Finally, the component is documentedby a press file whose source is a Tioga document. ft(G br uA `v6 r ^ H ](' Y uM X2 rJ VD T] S< O u00 NFNr  L@ J1$ IPJ G9" F> DZ" A  u9" ?d"r5 =W <.( :n1+ 8A 7G 3 u'2 2)!r& 0v6 .s -z *+r uE (r / &6 %59 #F !#5 ?W 10  t r;$ wrw r 1wr"wrw r w rw r"  w r& ;wrw rw r% 1 L>\Cedar Releases: Policies and Procedures5Notations of the form {n} are not actually part of the DF file. They indicate that the entry somarked conforms to rule n, above.// Sample.df// last edited by Harry Bovik: May 10, 1982 5:26 PMExports [Ivy]Sample> ReleaseAs [Indigo]Top> {2} Sample.df!310-May-82 11:47:21 PDT {1}Exports [Ivy]Sample> ReleaseAs [Indigo]Sample> {2} Sample.bcd!2 9-May-82 17:45:27 PDT {3} Sample.mesa!2 9-May-82 17:44:55 PDT {3} SampleExtras.bcd!110-May-82 11:45:31 PDT {3} SampleExtras.mesa!110-May-82 11:33:19 PDT {3} +SampleImpl.bcd!710-May-82 14:53:09 PDT {6,7}Directory [Ivy]Sample> ReleaseAs [Indigo]Sample> {4} SampleImpl.config!210-May-82 13:24:52 PDT MakeSample.cm!3 10-May-82 13:25:19 PDT {11} SamplePrivate.bcd!210-May-82 12:36:12 PDT SamplePrivate.mesa!110-May-82 12:34:51 PDT SampleImplA.bcd!710-May-82 14:47:39 PDT SampleImplA.mesa!610-May-82 14:47:21 PDT SampleImplB.bcd!410-May-82 14:47:43 PDT SampleImplB.mesa!210-May-82 14:32:06 PDTExports [Ivy]Sample> ReleaseAs [Indigo]Documentation> {4} Sample.press!2 6-May-82 9:40:18 PDT Sample.tioga!2 6-May-82 9:37:23 PDTImports [Indigo]Top>PilotInterfaces.df!1 Of 1-Apr-82 15:43:56 PST Using [Environment.bcd, Process.bcd] {8,9}Imports [Indigo]Top>Rigging.df!9 Of 7-May-82 20:18:46 PDT Using [Rope.bcd] {8,9}Imports [Indigo]Runtime>Runtime.df Of > Using [SafeStorage.bcd] {8,9}Notice that the files that make up the component are all stored on a working directory chosen bythe implementor, in this case his personal directory on Ivy. (Note that, in accordance with rule 12,Bovik must grant create access on [Ivy] to CedarAdministrators^.pa.) The DF file specifiesthe locations on a release directory, [Indigo], where the files are to be stored at release time.The component depends on three other components, two of which have been previously released(since they are on the release directory) and one of which (Runtime.df) is not (and presumablywill be released when Sample is). ft(G br6* `v! ](w [4 X2C T 0 QD NF 0 L0 J0 IP0 F0 BF ?d0 =G :n0 80 5x0 30 2)0 00 -3H )0 (=0 $H #G. @ Q 2 [!  r"> eM K b o4' 4w r wrL >\2Cedar Releases: Policies and Procedures6Rules for Submitting a Component for ReleaseThe message from the Release Master that announces the integration phase of a release contains amessage form. This form, properly completed and returned, serves three important functions:1)It enables the Release Master to include the DF file describing the component in thetop-level description of the release.2)It notifies other implementors that the component is now available for reference in otherDF files.3)It provides the information to be included in the release message that will announce therelease to all Cedar users.The message form has been constructed to facilitate all three of these purposes. Since deviationsfrom the standard form complicate and delay the integration phase, implementors must observe thefollowing rules for submission of components:13)The component must satisfy the construction rules before the submission form is sent. Sendingthe form before the DF files are ready and stored confuses everyone.14)The implementor must have run VerifyDF on the component's DF file before submitting it forrelease. VerifyDF performs most of the completeness checks that the Release Tool's secondphase does; consequently, most errors of this form can be detected early in the integrationphase and without delaying other implementors.15)The submission form is the only acceptable way of announcing a release submission. Free-formmessages are not acceptable and will be rejected by the Release Master. If an implementorexpects to be unavailable during the integration phase and wishes to prepare his submission"in advance", it is his responsibility to obtain from the Release Master a copy of the form anduse it.16)All fields of the form must be completed appropriately. In particular, the working path andrelease path must be filled in correctly and expressed in conventional syntax (server name insquare brackets, directory and subdirectories in angle brackets); "/" syntax is not acceptable.The documentation pointer must conform to the requirements stated on the form. Theportion of the form that contains information destined for the release message should be filledin judiciously; it is generally not necessary or desirable to describe every bug fix and minorenhancement. The reference documentation should include this kind of information, while therelease message should contain a summary of the significant changes in the component sincethe last release. A chronology of changes is not appropriate. The release message portion ofthe form must also be coherent English prose that observes accepted standards ofcapitalization, spelling, punctuation, and grammar.Avoiding Common MistakesWhen the integration phase of a release cycle is underway, it is easy to forget one or more of theabove rules. Experience has shown that some rules are more likely to be broken than others andthat certain mistakes occur repeatedly. Careful observation of the following rules will helpimplementors avoid the most common errors that delay release integrations. ft(G b, ^r(8 ](G Y:/%:X2% T:P:S< O:A:NF JR IP+5 G- DZ u Hr BD ?d uA =rD  <H :n. 7 u?r  5x7# 3B 2)[ 0 -3 u7r +? )0/ (=: &:% $F #G8$ !/+ ur- Q0,1$ 3 t 9rb  R H CJ =X8Cedar Releases: Policies and Procedures717)When beginning development of a component following a release, use the released DF file as thebase, not the working DF file supplied to the previous release. Obsolete working DF files areperhaps the single greatest source of trouble in the integration phase. When an implementoruses a working DF file from a previous release as the base for new development, he invitesinconsistencies that cannot be easily detected until the Release Tool is run. The typicalproblem is a reference to a working DF file that is either obsolete or non-existant. SModel canonly detect the latter of these problems, and then typically only if /v is specified. 18)Be certain that all imports come from the correct location (working directory or releasedirectory). In a sense, this rule includes the preceding one, since incorrect imports frequentlyarise when an obsolete DF file has been used as the starting point for development of thecomponent.19)When correcting a problem uncovered by the Release Tool during the integration phase, alwaysrun VerifyDF before notifying the Release Master that the component is again ready forinclusion. It is quite common for phase one of the Release Tool to uncover a problem in aDF file which, when "fixed" quickly by the implementor, leads to a problem in phase two.This causes unnecessary delay while the implementor once again fixes the problem; runningVerifyDF before the first resubmission will nearly always avoid such delays.20)Before submitting a component for release, double-check the subdirectories to which files arebeing released. The Release Tool cannot, in general, check that rules 2-4 are obeyed.Uniformity here greatly simplifies browsing.21)After successfully running VerifyDF (rule 19), be sure to run SModel /v,. In the course ofmaking a DF file acceptable to VerifyDF, it is useful to run SModel /n, which, although itimproves the state of the files on the local disk, performs no transfers to file servers. SModel/v ensures that the cumulative effect of repeated runs of SModel /n is moved to the fileservers. ft(G br u? `v?r ^4( ](T [8" YUv  X2Uu Tr uC S< rD Q; O L u\ JL  IP rO GX FY DZL A  u@ ?drB =, :n u.r 8(2 7,5 5x6" 36 3=4 TIMESROMAN  HELVETICA TIMESROMAN LOGO TIMESROMAN  TIMESROMAN  TIMESROMANGACHA    y%+3.9j/<:*ReleaseProcedures.bravoLevin.PAMay 26, 1982 4:37 PM