-*- Mode:Text -*-

				Proposal

		      Generating Internal Releases

		  (Jim O'Dell / Last modified 11/08/88)



SUMMARY:



This document puts forth the philosophy, definitions, procedure,
and frequency for generating internal Falcon software releases over
the lifetime of Falcon software development.  The goals of
making internal releases are:
 
 o provision of reliable snapshots of critical project components;
 o early detection of problems incurred by system file changes;
 o accommodation of individual and team project schedules;
 o minimization of required "code freeze" periods;
 o economical disk space usage.

As stated above, the Release mechanism exists partly for taking
snapshots of the Falcon source files upon completion of major
system components.  Sufficiently radical changes to the main
development line could warrant new Releases in and of
themselves; in such a case, all other developers should work to
"the soonest convenient stopping point," thus allowing the
Release process to proceed.  In any event, no more than six
months should ever elapse between two Falcon Releases.



BACKGROUND:



The Falcon system software is currently found in the directory
"JB:K;", and may be referred to by a logical pathname,
"K:<subsystem>;" where <subsystem> takes the form "K-<x>", <x>
being an integer that is to be incremented with each release.

As always, logical pathnames may be redefined by developers
wishing to use a different set of Falcon source and binary
files.

The files in the main line of Falcon system development (only)
are found in the directory "JB:K;". 



PROPOSAL:



The proposed release mechanism consists of six parts, each of
which will be discussed in the body of the proposal:

  1. Stating the Release Goals
  2. Copying the Falcon Source Files
  3. Compiling the Copies
  4. Regression Testing the Compiled Release
  5. Creating a New Falcon System
  6. Archiving Old Falcon Releases

1. Stating the Release Goals

Before any Release of the Falcon System is undertaken, all K
developers must come to terms with exactly which state of the
world they wish to capture in making the release.  This is
accomplished by having each design group (individual or team)
make a formal (i.e., written or ZMailed) statement of the
particular design efforts they wish to complete before the new K
Release is begun.  In this manner, potential problems due to
module incompleteness at the time of the Release may be averted.
For example, a developer involved in making a major revision to
the cross-compiler could request that the state of the Falcon
source files be such that the Release process await a particular
cross-compiler milestone.

Certain criteria should always be met before a new Falcon
Release is undertaken:

  1. All K developers should have arrived at a suitable stopping
     point;
  2. Mega-booting should work.
  3. (Any others?)



 Generating A Release Of The Falcon System Software

 
  Evaluate the form (make-k-system-release <host> <version>)

  where

  <host> is the name of the system host on which the release is
	 to be created (We are currently using "JB:")

  and
	
  <version> is the version number of the release. 

  Releases should be done when the relevant source files are relatively
quiescent; e.g., over the weekend.


 Finding The Current Version Number


  In the JB: root directory (obtainable by executing Dired on the
directory specification "JB:~;") will appear a series of directories
named "K-<version>" where <version> is a number.  The Release Version
Number is the number one greater than the <version> component of the
highest existing "K-" directory name.


 Compiling the Sources


  Requirements:  For now, it is necessary to recompile on a machine with
		 a Lambda installed.

  1.  Copy all source files into the trial directory "JB:TEST-K-SOURCES;".

  2.  Compile the copies, generating binary files into the
      "TEST-K-SOURCES" directory.

  3.  Repeat Step 2 until the system compiles correctly.

  4.  Run the regression test suite on the test system until minimal
      acceptability levels are recorded

  5.  Compile the original sources in the "JB:K-<version>"
      directory.

Steps 2, 3, and 5, involve the evaluation of the following forms, in
order:

	(load-k-system :recompile)

	(mega-boot :compile-type :recompile) 

If Steps 1-4 take more than a week to complete, the entire process shall
be repeated.


 System Maintenance Issues


Due to the limitations on disk space, only those
sources that are less than three months old will be kept online.
The only files that are exempt from quarterly deletion are those
without suffixes (such as .LISP, .QFASL, etc.)  These files
may be deleted only after discussion with the author.

COMMENTS:

STATUS: Open