	"@(#)sde_int	1.7	93/08/09 SMI"

	Integration Tips for a "gatekeeper" setting up a workspace in the
	OS-Net software development environment

(In this document, a "gatekeeper" is anyone who manages a workspace
responsible for integrating changes into "golden" source--product source.)


	Introduction: Gate-keeper Roles

This document addresses several key roles played by the gatekeeper.

She or he provides to the team:
    information on our SCCS-based software development environment
    a construction set
    one or a few reference proto areas containing headers and libraries

and provides to the development community:
    "release-style" builds for preintegration testing
    cpio archives of this "release"
    preintegration information on changes to package definitions.


	Providing Information

Start by familiarizing yourself with documentation addressed to developers.
See "Tips for getting started..." (sde_start) and the documents that it
describes.  You can find it in /opt/teamware/doc.

Follow the "roadmap" file when steering yourself or others to answers to
questions about our software development environment.

Be ready to answer questions and give advice in use of the ws(1) script,
especially configuration of the protodefs(5) file.  The advice you give
will depend on your choice of means for providing a reference proto area.
More will be said about the choice.  A reliable, reference proto area is
needed by anyone building targets that depend on the headers and libraries
typically found in /usr/include and /usr/lib.  Developers worry about
specifying the reference; you worry about satisfying it.

Similarly, the ws script can reference a particular version of a construc-
tion set, so be ready to give advice on how to obtain it and when to
update it.  Construction sets are introduced in Avocet update 14 in
/opt/teamware/doc/avo_updates.  Show your team how to pkgadd SUNWonbld to
control the version of "forth" and other tools they use to do builds.
Alternatively, put the package on a server and tell your team when to
NFS-mount whichever version.


	Providing One or a Few Reference Proto Areas

A gatekeeper's workspace should contain full source, usr/src.  It should
be accessible via NFS from all machines used by your team and from the
machine hosting the workspace into which you will integrate.  You control
write access per team policy.  Exporting your reference proto area read-
only will reduce accidental writes from errant "make install" builds.

Your reference proto area can be the default proto directory created in
your gatekeeper's workspace, or it can be a copy of it.  This is the big
choice mentioned above.  Providing a separate reference copy of your proto
area, away from your gatekeeper's workspace, takes some extra space and
work but gives stability, control of updates, and a degree of isolation
for the on-going development in your gatekeeper's workspace.
Alternatively, using the proto area in your gatekeeper's workspace saves
time and space, but it removes isolation and exposes your team immediately
to changes in the proto area.  There are good and bad ramifications with
either choice.

Regardless of choice, build the default proto area using "make protolibs"
in the usr/src directory.  The build will create "proto" at the top of your
workspace (per the value of ROOT set by "ws").

If you choose the economical alternative above, then advise your team to
use default values provided by "ws" in protodefs.  Developers using "ws"
in child workspaces of your gatekeeper's workspace will automatically
reference your new proto area for any headers or libraries not found in
their own proto areas.

If you want the control and isolation afforded by the "separate copy"
alternative, use cpio or tar to copy the default proto area, made by the
"protolibs" target, into a selected location (for your team to reference).
Publish the location, so your team may configure their protodefs files
per your advice.

Consider maintaining a rotating set of proto areas: N, N-1, N-2.
Each developer then can choose when to "see" the updated proto area
and even return to older views for investigating build problems.

All proto areas may be built using the path and shell variables
mentioned in the "Tips..." document above.  You need not be "root"
to build a reference proto area.


	Providing a "Release-Style" Build

Pre-integration testing requirements often call for a "release-style"
build, which installs all things into a large proto area replete with
specified owner and group attributes.  Packages or cpio archives may be
generated from such a proto area.  Release-style builds are a discipline.
See the build overview document ( 5.x_bld_info in terminator:
/usr/integration/doc) for details, particularly how to set controlling
variables.  "root" does this build.

Consider doing release-style builds in a separate, dedicated workspace.
It should be a child of your gate-keeper workspace, stored on the local
disks of a separate build host.  This will speed the build and isolate the
machine load.  Integration will only be blocked during the update of the
build workspace rather than for the duration of the build.


	Providing Preintegration Impact-on-Packages Information

Recent attributes of all objects in proto areas, built release-style, can
be recorded in a file using the "protolist" utility.  The integration group
maintains reference "proto_list" files.  You are encouraged to run protolist
from the gate-keeper toolset to generate protolist files of your own.  These
reveal "impact on packages" when diff'ed with reference files, using the
"protocmp" utility.  Usage (by root): protolist $ROOT > my_proto_list
(comparison by anyone): protocmp ref_proto_list my_proto_list > pkg_impact


	Providing Convenient Public Access to Your Workspace

You may make the gatekeeper's workspace "public" and convenient by filing
a tasktool request to have its location added to the auto.ws map in NIS
for the automounter.  In the task description, mention that the NIS+
auto_ws table needs to parallel the NIS update.
