first pass at editing

SCCS-vsn: share/doc/papers/relengr/0.t 1.2
SCCS-vsn: share/doc/papers/relengr/1.t 1.2
SCCS-vsn: share/doc/papers/relengr/2.t 1.2
SCCS-vsn: share/doc/papers/relengr/3.t 1.2

diff --git a/usr/src/share/doc/papers/relengr/0.t b/usr/src/share/doc/papers/relengr/0.t
index 7feb878..5a49c52 100644 (file)
--- a/usr/src/share/doc/papers/relengr/0.t
+++ b/usr/src/share/doc/papers/relengr/0.t
@@ -1,4 +1,4 @@
-.\"    @(#)0.t 1.1     (Copyright 1989 M. K. McKusick) 89/02/18
+.\"    @(#)0.t 1.2     (Copyright 1989 M. K. McKusick) 89/02/19

 .rm CM
 .nr Fn 0 1
 .ds b3 4.3\s-1BSD\s+1
 .rm CM
 .nr Fn 0 1
 .ds b3 4.3\s-1BSD\s+1


@@ -9,7 +9,7 @@
 Figure \\n(Fn - \\$1.
 ..
 .de SM
 Figure \\n(Fn - \\$1.
 ..
 .de SM

-\\s-1\\$1\\s+1
+\\s-1\\$1\\s+1\\$2

 ..
 .de NM
 \&\fI\\$1\fP\\$2
 ..
 .de NM
 \&\fI\\$1\fP\\$2


@@ -33,15 +33,22 @@ Department of Electrical Engineering and Computer Science
 University of California, Berkeley
 Berkeley, California  94720
 .AB
 University of California, Berkeley
 Berkeley, California  94720
 .AB

-This paper gives a brief overview of the release engineering
-techniques used during the release of the 4.3BSD UNIX\(dg
+This paper describes the approach used by a small group of people
+to develop and integrate a large software system.
+It details the development and release engineering strategy
+used during the preparation of the 4.3BSD UNIX\(dg

 .FS
 \(dgUNIX is a registered trademark of AT&T in the US and other countries.
 .FE
 operating system.
 .FS
 \(dgUNIX is a registered trademark of AT&T in the US and other countries.
 .FE
 operating system.

-It describes the approach that a small group of people can
-use to develop and integrate a large software system.
-It then describes the three step methodology used to
-engineer a clean, correct, and coherent release.
+Each release cycle is divided into an initial development phase
+followed by a release engineering phase.
+The release engineering of the distribution is done in three steps.
+The first step has an informal control policy for tracking modifications;
+it results in an alpha distribution.
+The second step has more rigid change mechanisms in place;
+it results in a beta release.
+During the final step changes are tracked very closely;
+the result is the final distribution.

 .AE
 .LP
 .AE
 .LP

diff --git a/usr/src/share/doc/papers/relengr/1.t b/usr/src/share/doc/papers/relengr/1.t
index 3b3582b..3011272 100644 (file)
--- a/usr/src/share/doc/papers/relengr/1.t
+++ b/usr/src/share/doc/papers/relengr/1.t
@@ -1,4 +1,4 @@
-.\"    @(#)1.t 1.1     (Copyright 1989 M. K. McKusick) 89/02/18
+.\"    @(#)1.t 1.2     (Copyright 1989 M. K. McKusick) 89/02/19

 .NH
 Introduction
 .PP
 .NH
 Introduction
 .PP


@@ -22,82 +22,9 @@ reflects the importance
 places on providing a reliable and robust system on which its
 user community can depend.
 .PP
 places on providing a reliable and robust system on which its
 user community can depend.
 .PP

-Developments from
-.SM CSRG
-are released in three steps: alpha, beta, and final.
-Alpha and beta releases are not true distributions\(emthey
-are test systems.
-Alpha releases are normally available to only a few sites, most of those
-within the University.
-More sites get beta releases, but they do not get them directly;
-a tree structure is imposed to allow bug reports, fixes, and new software
-to be collected, evaluated, and checked for redundancies
-by first-level sites before forwarding to
-.SM CSRG .
-For example,
-\*(b3 beta ran at more than 100 sites, but there were only about
-15 primary beta sites.
-The beta-test tree allowed the developers at
-.SM CSRG
-to concentrate on actual development rather than sifting through details
-from every beta-test site.
-.PP
-Many of the primary beta-test personnel not only had copies of the release
-running on their own machines, but also had login accounts on the development
-machine at Berkeley.
-Such users were commonly found logged in at Berkeley over the
-.SM ARPA
-Internet, or sometimes via telephone dialup, from places far away,
-such as Massachusetts, Utah, Maryland, Texas,
-and Illinois, and from closer places, such as
-Stanford.
-For the \*(b3 release,
-certain accounts and users had permission to modify the master copy of the
-system source directly.
-Several facilities, such as the
-Fortran and C compilers,
-as well as important system programs, such as
-.NM telnet
-and
-.NM ftp ,
-include significant contributions from people who did not work for
-.SM CSRG .
-One important exception to this approach was that changes to the kernel
-were made by only
-.SM CSRG
-personnel, although the changes often were suggested by the larger community.
-.PP
-People given access to the master sources
-were carefully screened beforehand, but were not
-closely supervised.
-Their work was checked at the end of the beta-test period by
-.SM CSRG
-personnel, who did a complete comparison of the source of the previous
-release with the current master sources\(emfor example, of \*(b3
-with 4.2\s-1BSD\s+1.
-Facilities deemed inappropriate, such as new options to
-the directory-listing command or a changed return value for the
-.RN fseek
-library routine, were removed from the source before final distribution.
-.PP
+The development of

 .SM BSD
 .SM BSD

-releases have usually included
-a pair of documents detailing
-changes to every user-level command
-.[
-Bug Fixes and Changes
-.]
-and to every kernel source file.
-.[
-Changes to the Kernel
-.]
-These documents are delivered with the final distribution.
-A user can look up any command by name and see immediately
-what has changed,
-and a developer can similarly look up any kernel
-file by name and get a summary of that file's changes.
-.PP
-This process illustrates an \fIadvantage\fP of having a few
+illustrates an \fIadvantage\fP of having a few

 principal developers:
 The developers all know the whole system thoroughly enough
 to be able to coordinate their own work with
 principal developers:
 The developers all know the whole system thoroughly enough
 to be able to coordinate their own work with


@@ -105,4 +32,4 @@ that of other people to produce a coherent final system.
 Companies with large development organizations find
 this result difficult to duplicate.
 This paper describes in more detail the process by which
 Companies with large development organizations find
 this result difficult to duplicate.
 This paper describes in more detail the process by which

-the release engineering is managed.
+the development effort is managed.

diff --git a/usr/src/share/doc/papers/relengr/2.t b/usr/src/share/doc/papers/relengr/2.t
index e156b9b..7a7e5fd 100644 (file)
--- a/usr/src/share/doc/papers/relengr/2.t
+++ b/usr/src/share/doc/papers/relengr/2.t
@@ -1,14 +1,16 @@
-.\"    @(#)2.t 1.1     (Copyright 1989 M. K. McKusick) 89/02/18
+.\"    @(#)2.t 1.2     (Copyright 1989 M. K. McKusick) 89/02/19

 .NH
 System Development
 .PP
 The first phase of each Berkeley system is its development.
 .NH
 System Development
 .PP
 The first phase of each Berkeley system is its development.

-We maintain a continuously evolving list of projects that we would
+.SM CSRG
+maintains a continuously evolving list of projects that they would

 like to see integrated into the system.
 Some additions are prompted by emerging ideas from the
 like to see integrated into the system.
 Some additions are prompted by emerging ideas from the

-research world such as the availability of new technology.
+research world, such as the availability of new technology.

 A typical project would be to incorporate support for the
 A typical project would be to incorporate support for the

-new technology into \*(b3.
+new technology into
+.SM BSD .

 Other additions are suggested from the commercial world such
 as the introduction of new standards like
 .SM POSIX .
 Other additions are suggested from the commercial world such
 as the introduction of new standards like
 .SM POSIX .


@@ -34,8 +36,8 @@ not too large is it developed in-house.
 Unlike larger development groups, the staff of
 .SM CSRG
 specializes by projects rather than by particular levels
 Unlike larger development groups, the staff of
 .SM CSRG
 specializes by projects rather than by particular levels

-of the system.
-Thus, a staff person will be responsible for all aspects of a project.
+of the system;
+a staff person will be responsible for all aspects of a project.

 This responsibility starts at the associated kernel device drivers;
 it proceeds up through the top of the kernel,
 through the C library and system utility programs,
 This responsibility starts at the associated kernel device drivers;
 it proceeds up through the top of the kernel,
 through the C library and system utility programs,


@@ -44,6 +46,41 @@ Each staff person is also responsible for the documentation and manual pages.
 Projects proceed in parallel,
 interacting with other projects as their paths cross.
 .PP
 Projects proceed in parallel,
 interacting with other projects as their paths cross.
 .PP

+Much of the development of
+.SM BSD
+is done by personnel that are located at other institutions.
+Many of these people not only have copies of the release
+running on their own machines,
+but also have login accounts on the development
+machine at Berkeley.
+Such users are commonly found logged in at Berkeley over the
+.SM ARPA
+Internet, or sometimes via telephone dialup, from places far away,
+such as Massachusetts, Utah, Maryland, Texas,
+and Illinois, and from closer places, such as
+Stanford.
+For the \*(b3 release,
+certain accounts and users had permission to modify the master copy of the
+system source directly.
+People given access to the master sources
+are carefully screened beforehand,
+but are not closely supervised.
+Their work is checked at the end of the beta-test period by
+.SM CSRG
+personnel who back out inappropriate changes.
+Several facilities, such as the
+Fortran and C compilers,
+as well as important system programs, such as
+.NM telnet
+and
+.NM ftp ,
+include significant contributions from people who did not work for
+.SM CSRG .
+One important exception to this approach is that changes to the kernel
+are made by only
+.SM CSRG
+personnel, although the changes often are suggested by the larger community.
+.PP

 All source code, documentation, and auxiliary files are kept
 under a source code control system.
 During development,
 All source code, documentation, and auxiliary files are kept
 under a source code control system.
 During development,

diff --git a/usr/src/share/doc/papers/relengr/3.t b/usr/src/share/doc/papers/relengr/3.t
index 5ec0fcd..55504a4 100644 (file)
--- a/usr/src/share/doc/papers/relengr/3.t
+++ b/usr/src/share/doc/papers/relengr/3.t
@@ -1,4 +1,4 @@
-.\"    @(#)3.t 1.1     (Copyright 1989 M. K. McKusick) 89/02/18
+.\"    @(#)3.t 1.2     (Copyright 1989 M. K. McKusick) 89/02/19

 .NH
 System Release
 .PP
 .NH
 System Release
 .PP


@@ -13,6 +13,21 @@ Projects that are not selected for completion are mothballed
 so that they can be restarted in the future.
 The remaining unfinished projects are
 brought to an orderly completion.
 so that they can be restarted in the future.
 The remaining unfinished projects are
 brought to an orderly completion.

+.PP
+Developments from
+.SM CSRG
+are released in three steps: alpha, beta, and final.
+Alpha and beta releases are not true distributions\(emthey
+are test systems.
+Alpha releases are normally available to only a few sites,
+mostly those that are working directly with
+.SM CSRG .
+More sites get beta releases,
+as the system is closer to completion,
+so needs wider testing to find more obscure problems.
+For example,
+\*(b3 beta ran at more than 100 sites, but there were only about
+15 alpha sites.

 .NH 2
 The Alpha Distribution
 .PP
 .NH 2
 The Alpha Distribution
 .PP


@@ -35,7 +50,7 @@ This prototype will eventually turn into the master for the
 final distribution.
 During the period that the alpha distribution is being created,
 .PN /nbsd
 final distribution.
 During the period that the alpha distribution is being created,
 .PN /nbsd

-is mounted read/write, and is highly fluid.
+is mounted read-write, and is highly fluid.

 Programs are created and deleted,
 new versions are dropped in,
 and the correspondence between the sources and binaries
 Programs are created and deleted,
 new versions are dropped in,
 and the correspondence between the sources and binaries


@@ -56,10 +71,10 @@ Unfortunately, this change broke the
 program that could no longer interpret the new diff output.
 Since both changes had originated outside Berkeley,
 .SM CSRG
 program that could no longer interpret the new diff output.
 Since both changes had originated outside Berkeley,
 .SM CSRG

-had to coordinate the authors of these two programs
-to get them to work together harmoniously.
+had to get the authors of these two programs
+to make the programs work together harmoniously.

 .PP
 .PP

-Once we are satisfied with the state of the sources,
+Once the state of the sources has stabilized,

 an attempt is made to build the entire source tree.
 Often this turns up errors because of changed header files,
 or use of obsoleted C library interfaces.
 an attempt is made to build the entire source tree.
 Often this turns up errors because of changed header files,
 or use of obsoleted C library interfaces.


@@ -86,6 +101,15 @@ an alpha distribution tape is made
 from the contents of
 .PN /nbsd .
 .PP
 from the contents of
 .PN /nbsd .
 .PP

+The alpha distribution is sent out to a small set of test sites.
+These test sites are selected to have a
+sophisticated user population that can not only find bugs,
+but can also determine the cause and find a fix to the problem.
+These sites are mostly composed of the groups
+that are involved in contributing software to the distribution.
+.NH 2
+The Beta Distribution
+.PP

 After the alpha tape is made,
 the distribution filesystem is changed over to read-only.
 Further changes are requested in a change log rather than
 After the alpha tape is made,
 the distribution filesystem is changed over to read-only.
 Further changes are requested in a change log rather than


@@ -94,19 +118,10 @@ The change requests are inspected and run by a
 .SM CSRG
 staff person, followed by a compilation of the affected
 programs to ensure that they still build correctly.
 .SM CSRG
 staff person, followed by a compilation of the affected
 programs to ensure that they still build correctly.

-Notably, once the alpha tape has been cut,
+Once the alpha tape has been cut,

 changes to the distribution are no longer made by people outside
 .SM CSRG .
 .PP
 changes to the distribution are no longer made by people outside
 .SM CSRG .
 .PP

-The alpha distribution is sent out to a select set of test sites.
-These test sites are selected to have a
-sophisticated user population that can not only find bugs,
-but can also determine the cause and find a fix to the problem.
-These sites are mostly composed of the groups
-that are involved in contributing software to the distribution.
-.NH 2
-The Beta Distribution
-.PP

 As the alpha sites install and begin running the alpha tape,
 they monitor the problems that they encounter.
 For minor bugs, they typically report back the bug along with
 As the alpha sites install and begin running the alpha tape,
 they monitor the problems that they encounter.
 For minor bugs, they typically report back the bug along with


@@ -118,12 +133,14 @@ they often have accounts on, and access to, the primary
 .SM CSRG
 development machine.
 Thus, they are able to directly install the fix themselves,
 .SM CSRG
 development machine.
 Thus, they are able to directly install the fix themselves,

-and simply notify us when they have fixed the problem.
+and simply notify
+.SM CSRG
+when they have fixed the problem.

 After verifying the fix, the affected files are added to
 the list to be updated on
 .PN /nbsd .
 .PP
 After verifying the fix, the affected files are added to
 the list to be updated on
 .PN /nbsd .
 .PP

-The more important task of the beta sites is to test out the
+The more important task of the alpha sites is to test out the

 new facilities that have been added to the system.
 The alpha sites often manage to find major design flaws
 or operational shortcomings of the facilities.
 new facilities that have been added to the system.
 The alpha sites often manage to find major design flaws
 or operational shortcomings of the facilities.


@@ -138,12 +155,13 @@ the alpha release of the networking did not have connection queueing.
 This shortcoming prevented the networking from handling many
 connections to a single server.
 The result was that the networking interface had to be
 This shortcoming prevented the networking from handling many
 connections to a single server.
 The result was that the networking interface had to be

-rearchitected to allow connection queueing.
+rearchitected to provide connection queueing.

 .PP
 The alpha sites are also responsible for ferreting out interoperability
 problems with the different utilities.
 .PP
 The alpha sites are also responsible for ferreting out interoperability
 problems with the different utilities.

-The sites are selected with different types of user populations so
-that the utilities will be exercised in ways that differ
+The user populations of the test sites differ from the user population at
+.SM CSRG ,
+so the utilities are exercised in ways that differ

 from the ways that they are used at
 .SM CSRG .
 These differences in usage patterns turn up problems that
 from the ways that they are used at
 .SM CSRG .
 These differences in usage patterns turn up problems that


@@ -161,12 +179,15 @@ to avoid spurious and voluminous reports.
 The direct alpha sites sift through the reports to find those that
 are relevant, and usually verify the suggested fix if one is given,
 or develop a fix if none is provided.
 The direct alpha sites sift through the reports to find those that
 are relevant, and usually verify the suggested fix if one is given,
 or develop a fix if none is provided.

-The tree structured testing process ensures that the small group
-of people at
+The tree structured testing process allows
+bug reports, fixes, and new software
+to be collected, evaluated, and checked for redundancies
+by first-level sites before forwarding to
+.SM CSRG .
+The alpha-test tree allows the developers at

 .SM CSRG
 .SM CSRG

-are not swamped by an overwhelming influx of reports.
-Instead, they can concentrate on tracking the changes being made
-to the system to ensure as high a level of consistency as possible.
+to concentrate on tracking the changes being made to the system
+rather than sifting through details from every alpha-test site.

 .PP
 Once the major problems have been attended to,
 the focus turns to getting the documentation synchronized
 .PP
 Once the major problems have been attended to,
 the focus turns to getting the documentation synchronized


@@ -190,7 +211,7 @@ have contributed complete software packages
 .PN RCS
 or
 .PN MH )
 .PN RCS
 or
 .PN MH )

-in the past to see if they wish to
+in previous releases to see if they wish to

 make any revisions to their software.
 For those that do,
 the new software has to be obtained,
 make any revisions to their software.
 For those that do,
 the new software has to be obtained,


@@ -202,11 +223,14 @@ across the network.
 .PP
 After the stream of bug reports has slowed down
 to a reasonable level,
 .PP
 After the stream of bug reports has slowed down
 to a reasonable level,

-we begin a carefully review of all the changes to the
+.SM CSRG
+begins a carefully review of all the changes to the

 system since the previous release.
 The review is done by running a recursive
 .PN diff
 system since the previous release.
 The review is done by running a recursive
 .PN diff

-of the entire source tree.
+of the entire source tree\(emhere, of
+.PN /nbsd
+with 4.2\s-1BSD\s+1.

 All the changes are checked to ensure that they are reasonable,
 and have been properly documented.
 The process often turns up questionable changes.
 All the changes are checked to ensure that they are reasonable,
 and have been properly documented.
 The process often turns up questionable changes.


@@ -219,14 +243,35 @@ the person responsible for the change is asked to explain
 what they were trying to accomplish.
 If the reason is not compelling,
 the change is backed out.
 what they were trying to accomplish.
 If the reason is not compelling,
 the change is backed out.

+Facilities deemed inappropriate in \*(b3 included new options to
+the directory-listing command and a changed return value for the
+.RN fseek
+library routine;
+the changes were removed from the source before final distribution.

 Although this process is long and tedious,
 Although this process is long and tedious,

-it forces us to get a picture of the entire set of
-changes to the system into out head.
+it forces the developers to get a picture of the entire set of
+changes to the system.

 This exercise often turns up inconsistencies that would
 otherwise never be found.
 .PP
 This exercise often turns up inconsistencies that would
 otherwise never be found.
 .PP

+The outcome of the comparison results in
+a pair of documents detailing
+changes to every user-level command
+.[
+Bug Fixes and Changes
+.]
+and to every kernel source file.
+.[
+Changes to the Kernel
+.]
+These documents are delivered with the final distribution.
+A user can look up any command by name and see immediately
+what has changed,
+and a developer can similarly look up any kernel
+file by name and get a summary of that file's changes.
+.PP

 Having completed the review of the entire system,
 Having completed the review of the entire system,

-we begin the preparation of the beta distribution.
+the preparation of the beta distribution is started.

 Unlike the alpha distribution, where pieces of the system
 may be unfinished and the documentation incomplete,
 the beta distribution is put together as if it were
 Unlike the alpha distribution, where pieces of the system
 may be unfinished and the documentation incomplete,
 the beta distribution is put together as if it were


@@ -236,15 +281,16 @@ is completed.
 Once the beta tape has been prepared,
 no further changes are permitted to
 .PN /nbsd
 Once the beta tape has been prepared,
 no further changes are permitted to
 .PN /nbsd

-without careful review as spurious changes made after the system has been
-.PN diff 'ed
+without careful review,
+as spurious changes made after the system has been
+.PN diff ed

 are unlikely to be caught.
 .NH 2
 The Final Distribution
 .PP
 The beta distribution goes to a larger set of sites than the
 alpha distribution for two main reasons.
 are unlikely to be caught.
 .NH 2
 The Final Distribution
 .PP
 The beta distribution goes to a larger set of sites than the
 alpha distribution for two main reasons.

-First, since it closer to the final release more sites are willing
+First, since it closer to the final release, more sites are willing

 to run it in a production environment without fear of catastrophic failures.
 Second, more commercial sites with
 .SM BSD
 to run it in a production environment without fear of catastrophic failures.
 Second, more commercial sites with
 .SM BSD


@@ -282,14 +328,14 @@ on the distribution has the proper owner, group, and modes.
 All source files must be checked to be sure that they have
 appropriate source code control system headers.
 Any unwanted error or temporary files must be removed.
 All source files must be checked to be sure that they have
 appropriate source code control system headers.
 Any unwanted error or temporary files must be removed.

-Finally we have to ensure that the installed binaries correspond
+Finally, the installed binaries must be checked to ensure that they correspond

 exactly to the sources and libraries that are on the distribution.
 .PP
 exactly to the sources and libraries that are on the distribution.
 .PP

-This is a formidable task given that there are over 20,000 files on
+This checking is a formidable task given that there are over 20,000 files on

 a typical distribution.
 Much of the checking can be done by a set of programs set to scan
 over the distribution tree.
 a typical distribution.
 Much of the checking can be done by a set of programs set to scan
 over the distribution tree.

-Unfortunately the exception list is long, and requires
+Unfortunately, the exception list is long, and requires

 hours of tedious hand checking.
 .PP
 Once the final set of checks has been run,
 hours of tedious hand checking.
 .PP
 Once the final set of checks has been run,