








                                      CCVVSS IIII::
                         PPaarraalllleelliizziinngg SSooffttwwaarree DDeevveellooppmmeenntt

                                   _B_r_i_a_n _B_e_r_l_i_n_e_r
                                    _P_r_i_s_m_a_, _I_n_c_.
                              _5_4_6_5 _M_a_r_k _D_a_b_l_i_n_g _B_l_v_d_.
                            _C_o_l_o_r_a_d_o _S_p_r_i_n_g_s_, _C_O  _8_0_9_1_8
                                _b_e_r_l_i_n_e_r_@_p_r_i_s_m_a_._c_o_m


                                      _A_B_S_T_R_A_C_T

                      The  program  described in this paper fills a
                 need in the UNIX community for a freely  available
                 tool  to manage software revision and release con-
                 trol in a multi-developer, multi-directory, multi-
                 group  environment.   This tool also addresses the
                 increasing need for  tracking  third-party  vendor
                 source  distributions  while  trying  to  maintain
                 local modifications to earlier releases.


            11..  BBaacckkggrroouunndd
                 In large software development projects, it  is  usually
            necessary for more than one software developer to be modify-
            ing (usually different) modules of  the  code  at  the  same
            time.   Some  of  these  code  modifications  are done in an
            experimental sense, at least until the code  functions  cor-
            rectly,  and  some  testing of the entire program is usually
            necessary.  Then, the modifications are returned to a master
            source  repository  so  that others in the project can enjoy
            the new bug-fix or functionality.  In order to manage such a
            project,  some sort of revision control system is necessary.
                 Specifically, UNIX1 kernel development is an  excellent
            example  of  the  problems that an adequate revision control
            system  must address.  The SunOS2 kernel is composed of over
            a thousand files spread across  a  hierarchy  of  dozens  of
            directories.3 Pieces of the kernel must be  edited  by  many
            -----------


              1 UNIX is a registered trademark of AT&T.


              2 SunOS is a trademark of Sun Microsystems, Inc.


              3 Yes,  the SunOS 4.0 kernel is composed of over












                                         -2-


            software  developers within an organization.  While undesir-
            able in theory, it is not uncommon to have two or more  peo-
            ple  making modifications to the same file within the kernel
            sources in order to facilitate a desired  change.   Existing
            revision  control  systems  like  RCS [Tichy] or SCCS [Bell]
            serialize file modifications by allowing only one  developer
            to  have  a  writable  copy  of a particular file at any one
            point in time.  That developer is said  to  have  ``locked''
            the  file  for  his exclusive use, and no other developer is
            allowed to check out a writable copy of the file  until  the
            locking  developer  has finished impeding others' productiv-
            ity.  Development pressures of  productivity  and  deadlines
            often  force organizations to require that multiple develop-
            ers be able to simultaneously edit copies of the same  revi-
            sion controlled file.
                 The  necessity  for  multiple  developers to modify the
            same file concurrently questions the value of serialization-
            based  policies in traditional revision control.  This paper
            discusses the approach that Prisma took in adapting a  stan-
            dard  revision  control  system, RCS, along with an existing
            public-domain collection of shell scripts that sits atop RCS
            and  provides the basic conflict-resolution algorithms.  The
            resulting program, ccvvss, addresses not only the issue of con-
            flict-resolution  in a multi-developer open-editing environ-
            ment, but also the issues of software  release  control  and
            vendor source support and integration.

            22..  TThhee CCVVSS PPrrooggrraamm
                 ccvvss  (Concurrent Versions System) is a front end to the
            RCS revision control system  which  extends  the  notion  of
            revision  control  from  a  collection  of files in a single
            directory to a hierarchical collection of  directories  each
            containing revision controlled files.  Directories and files
            in the ccvvss system can be combined together in many  ways  to
            form  a software release.  ccvvss provides the functions neces-
            sary to manage these software releases and  to  control  the
            concurrent  editing  of source files among multiple software
            developers.
                 The six major features of ccvvss  are  listed  below,  and
            will be described in more detail in the following sections:
                 1.   Concurrent  access  and  conflict-resolution algo-
                      rithms to guarantee that source  changes  are  not
                      ``lost.''
                 2.   Support  for  tracking  third-party  vendor source
                      distributions while maintaining the local  modifi-
                      cations made to those sources.
                 3.   A  flexible  module  database that provides a sym-
                      bolic mapping of names to components of  a  larger
                      software   distribution.   This  symbolic  mapping
            -----------


            a _t_h_o_u_s_a_n_d files!













                      provides  for  location  independence  within  the
                      software  release  and, for example, allows one to
                      check out a copy of the ``diff''  program  without
                      ever knowing that the sources to ``diff'' actually
                      reside in the ``bin/diff'' directory.
                 4.   Configurable logging support allows all  ``commit-
                      ted''  source  file  changes to be logged using an
                      arbitrary program to save the log  messages  in  a
                      file, notesfile, or news database.
                 5.   A  software release can be symbolically tagged and
                      checked out at any time based  on  that  tag.   An
                      exact  copy  of a previous software release can be
                      checked out at any  time,  _r_e_g_a_r_d_l_e_s_s  of  whether
                      files  or directories have been added/removed from
                      the ``current''  software  release.   As  well,  a
                      ``date''  can  be used to check out the _e_x_a_c_t ver-
                      sion of the software release as of  the  specified
                      date.
                 6.   A  ``patch''  format  file  [Wall] can be produced
                      between  two  software  releases,  even   if   the
                      releases span multiple directories.
                 The  sources maintained by ccvvss are kept within a single
            directory hierarchy  known  as  the  ``source  repository.''
            This ``source repository'' holds the actual RCS ``,v'' files
            directly, as well  as  a  special  per-repository  directory
            (CVSROOT.adm)  which  contains a small number of administra-
            tive files that describe the repository and how  it  can  be
            accessed.  See Figure 1 for a picture of the ccvvss tree.

            22..11..  SSooffttwwaarree CCoonnfflliicctt RReessoolluuttiioonn44
            -----------


              4 The  basic conflict-resolution algorithms used


            in the ccvvss program find their roots in the  origi-


            nal  work done by Dick Grune at Vrije Universiteit


            in Amsterdam and posted  to  ccoommpp..ssoouurrcceess..uunniixx  in


            the volume 6 release sometime in 1986.  This orig-


            inal version of ccvvss  was  a  collection  of  shell


            scripts  that  combined to form a front end to the











                                         -4-


                 __________________________________________________

                line from 4.112,9.200 to 5.550,8.887
                line from 5.447,8.884 to 5.550,8.887 to 5.458,8.933
                line from 4.112,9.200 to 4.550,8.950
                line from 4.451,8.978 to 4.550,8.950 to 4.476,9.021
                line from 4.112,9.200 to 3.737,8.887
                line from 3.798,8.971 to 3.737,8.887 to 3.830,8.932
                line from 3.612,8.762 to 4.737,8.137
                line from 4.638,8.164 to 4.737,8.137 to 4.662,8.208
                line from 3.612,8.762 to 3.737,8.137
                line from 3.693,8.231 to 3.737,8.137 to 3.742,8.240
                line from 3.612,8.762 to 2.612,8.200
                line from 2.687,8.271 to 2.612,8.200 to 2.712,8.227
                line from 2.362,9.262 to 2.737,8.950
                line from 2.645,8.995 to 2.737,8.950 to 2.677,9.033
                line from 2.362,9.262 to 1.925,8.950
                line from 1.992,9.028 to 1.925,8.950 to 2.021,8.988
                line from 3.362,9.762 to 4.050,9.387
                line from 3.950,9.413 to 4.050,9.387 to 3.974,9.457
                line from 3.362,9.762 to 2.487,9.387
                line from 2.570,9.450 to 2.487,9.387 to 2.589,9.404
                "newfs.c,v" at 4.487,8.043 ljust
                "mkfs.c,v" at 3.487,8.043 ljust
                "Makefile,v" at 2.237,8.043 ljust
                "newfs" at 3.487,8.793 ljust
                "halt.c,v" at 5.487,8.793 ljust
                "Makefile,v" at 4.237,8.793 ljust
                "modules,v" at 2.487,8.793 ljust
                "loginfo,v" at 1.488,8.793 ljust
                "etc" at 3.987,9.293 ljust
                "CVSROOT.adm" at 1.988,9.293 ljust
                "/src/master" at 2.987,9.793 ljust

                 __________________________________________________

                                     FFiigguurree 11..
                               ccvvss Source Repository

                 ccvvss allows several software developers to edit personal
            copies  of  a  revision  controlled  file concurrently.  The
            revision number of each checked out file is maintained inde-
            pendently for each user, and ccvvss forces the checked out file
            to be current with the ``head'' revision before  it  can  be
            ``committed''  as a permanent change.  A checked out file is
            brought up-to-date with  the  ``head''  revision  using  the
            ``update''  command  of  ccvvss.   This  command  compares  the
            ``head'' revision number with that of the  user's  file  and
            performs  an  RCS  merge operation if they are not the same.
            -----------


            RCS programs.













            The result of the merge is a file that contains  the  user's
            modifications  and  those  modifications that were ``commit-
            ted'' after the user checked out his version of the file (as
            well  as  a  backup  copy of the user's original file).  ccvvss
            points out any conflicts during the merge.  It is the user's
            responsibility  to resolve these conflicts and to ``commit''
            his/her changes when ready.
                 Although  the  ccvvss  conflict-resolution  algorithm  was
            defined  in  1986,  it  is remarkably similar to the ``Copy-
            Modify-Merge''  scenario included with NSE5 and described in
            [Honda] and [Courington].  The  following  explanation  from
            [Honda] also applies to ccvvss:
                 Simply  stated, a developer copies an object with-
                 out locking it, modifies the copy, and then merges
                 the   modified   copy  with  the  original.   This
                 paradigm allows developers to  work  in  isolation
                 from  one another since changes are made to copies
                 of objects.  Because locks are not used,  develop-
                 ment  is  not serialized and can proceed in paral-
                 lel.   Developers,  however,  must  merge  objects
                 after  the changes have been made.  In particular,
                 a developer must resolve conflicts when  the  same
                 object has been modified by someone else.
                 In practice, Prisma has found that conflicts that occur
            when the same object has been modified by someone  else  are
            quite  rare.   When  they do happen, the changes made by the
            other developer are usually easily resolved.  This practical
            use  has  shown that the ``Copy-Modify-Merge'' paradigm is a
            correct and useful one.

            22..22..  TTrraacckkiinngg TThhiirrdd--PPaarrttyy SSoouurrccee DDiissttrriibbuuttiioonnss
                 Currently, a large  amount  of  software  is  based  on
            source  distributions from a third-party distributor.  It is
            often the case that local modifications are to  be  made  to
            this  distribution,  _a_n_d  that  the vendor's future releases
            should be tracked.  Rolling your local modifications forward
            into  the  new  vendor release is a time-consuming task, but
            ccvvss can ease this burden somewhat.  The cchheecckkiinn  program  of
            ccvvss initially sets up a source repository by integrating the
            source modules directly from the vendor's release,  preserv-
            ing  the  directory  hierarchy of the vendor's distribution.
            The branch support of RCS  is  used  to  build  this  vendor
            release  as  a branch of the main RCS trunk.  Figure 2 shows
            how the ``head'' tracks a sample vendor branch when no local
            modifications  have  been  made  to  the file.  Once this is
            done, developers can check out files and make local  changes
            -----------


              5 NSE is the  Network  Software  Environment,  a


            product of Sun Microsystems, Inc.










                                         -6-


                 __________________________________________________

            ellipse at 3.237,6.763 wid 1.000 ht 0.500
            dashwid = 0.050i
            line dashed from 3.237,7.513 to 3.737,7.513 to 3.737,9.762 to 4.237,9.762
            line from 4.138,9.737 to 4.237,9.762 to 4.138,9.787
            line dashed from 2.237,8.262 to 3.237,8.262 to 3.237,7.013
            line from 3.212,7.112 to 3.237,7.013 to 3.262,7.112
            line from 3.737,6.763 to 4.237,6.763
            line from 4.138,6.737 to 4.237,6.763 to 4.138,6.788
            line from 2.237,6.763 to 2.737,6.763
            line from 2.637,6.737 to 2.737,6.763 to 2.637,6.788
            line from 1.738,6.013 to 1.738,6.513
            line from 1.762,6.413 to 1.738,6.513 to 1.713,6.413
            line from 1.238,7.013 to 2.237,7.013 to 2.237,6.513 to 1.238,6.513 to 1.238,7.013
            line from 4.237,9.012 to 5.237,9.012 to 5.237,8.512 to 4.237,8.512 to 4.237,9.012
            line from 4.237,8.012 to 5.237,8.012 to 5.237,7.513 to 4.237,7.513 to 4.237,8.012
            line from 4.237,7.013 to 5.237,7.013 to 5.237,6.513 to 4.237,6.513 to 4.237,7.013
            line from 4.737,7.013 to 4.737,7.513
            line from 4.763,7.413 to 4.737,7.513 to 4.712,7.413
            line from 4.737,8.012 to 4.737,8.512
            line from 4.763,8.412 to 4.737,8.512 to 4.712,8.412
            line from 4.237,10.012 to 5.237,10.012 to 5.237,9.512 to 4.237,9.512 to 4.237,10.012
            line from 4.737,9.012 to 4.737,9.512
            line from 4.763,9.412 to 4.737,9.512 to 4.712,9.412
            line from 5.987,5.013 to 5.987,6.013 to 0.988,6.013 to 0.988,5.013 to 5.987,5.013
            "
            "'SunOS'" at 2.987,6.293 ljust
            "1.1.1" at 3.050,6.793 ljust
            "1.1" at 1.613,6.793 ljust
            "1.1.1.1" at 4.487,6.793 ljust
            "1.1.1.2" at 4.487,7.793 ljust
            "1.1.1.3" at 4.487,8.793 ljust
            "1.1.1.4" at 4.487,9.793 ljust
            "'SunOS_4_0'" at 5.487,6.793 ljust
            "'SunOS_4_0_1'" at 5.487,7.793 ljust
            "'YAPT_5_5C'" at 5.487,8.793 ljust
            "'SunOS_4_0_3'" at 5.487,9.793 ljust
            "rcsfile.c,v" at 2.987,5.543 ljust

                 __________________________________________________

                                     FFiigguurree 22..
                             ccvvss Vendor Branch Example
            to  the  vendor's  source distribution.  These local changes
            form a new branch to the tree which  is  then  used  as  the
            source  for  future  check  outs.   Figure  3  shows how the
            ``head'' moves to the main RCS trunk when a local  modifica-
            tion is made.
                 When  a new version of the vendor's source distribution
            arrives, the cchheecckkiinn program adds the new and  changed  ven-
            dor's  files to the already existing source repository.  For
            files that have not been changed locally, the new file  from













                 __________________________________________________

            ellipse at 3.237,6.763 wid 1.000 ht 0.500
            dashwid = 0.050i
            line dashed from 2.800,9.075 to 1.738,9.075 to 1.738,8.012
            line from 1.713,8.112 to 1.738,8.012 to 1.762,8.112
            line from 1.738,7.013 to 1.738,7.513
            line from 1.762,7.413 to 1.738,7.513 to 1.713,7.413
            line from 1.238,8.012 to 2.237,8.012 to 2.237,7.513 to 1.238,7.513 to 1.238,8.012
            line from 3.737,6.763 to 4.237,6.763
            line from 4.138,6.737 to 4.237,6.763 to 4.138,6.788
            line from 2.237,6.763 to 2.737,6.763
            line from 2.637,6.737 to 2.737,6.763 to 2.637,6.788
            line from 1.738,6.013 to 1.738,6.513
            line from 1.762,6.413 to 1.738,6.513 to 1.713,6.413
            line from 1.238,7.013 to 2.237,7.013 to 2.237,6.513 to 1.238,6.513 to 1.238,7.013
            line from 4.237,9.012 to 5.237,9.012 to 5.237,8.512 to 4.237,8.512 to 4.237,9.012
            line from 4.237,8.012 to 5.237,8.012 to 5.237,7.513 to 4.237,7.513 to 4.237,8.012
            line from 4.237,7.013 to 5.237,7.013 to 5.237,6.513 to 4.237,6.513 to 4.237,7.013
            line from 4.737,7.013 to 4.737,7.513
            line from 4.763,7.413 to 4.737,7.513 to 4.712,7.413
            line from 4.737,8.012 to 4.737,8.512
            line from 4.763,8.412 to 4.737,8.512 to 4.712,8.412
            line from 4.237,10.012 to 5.237,10.012 to 5.237,9.512 to 4.237,9.512 to 4.237,10.012
            line from 4.737,9.012 to 4.737,9.512
            line from 4.763,9.412 to 4.737,9.512 to 4.712,9.412
            line from 5.987,5.013 to 5.987,6.013 to 0.988,6.013 to 0.988,5.013 to 5.987,5.013
            "1.2" at 1.613,7.793 ljust
            "
            "'SunOS'" at 2.987,6.293 ljust
            "1.1.1" at 3.050,6.793 ljust
            "1.1" at 1.613,6.793 ljust
            "1.1.1.1" at 4.487,6.793 ljust
            "1.1.1.2" at 4.487,7.793 ljust
            "1.1.1.3" at 4.487,8.793 ljust
            "1.1.1.4" at 4.487,9.793 ljust
            "'SunOS_4_0'" at 5.487,6.793 ljust
            "'SunOS_4_0_1'" at 5.487,7.793 ljust
            "'YAPT_5_5C'" at 5.487,8.793 ljust
            "'SunOS_4_0_3'" at 5.487,9.793 ljust
            "rcsfile.c,v" at 2.987,5.543 ljust

                 __________________________________________________

                                     FFiigguurree 33..
                      ccvvss Local Modification to Vendor Branch

            the vendor becomes the current ``head'' revision.  For files
            that have been modified locally, cchheecckkiinn warns that the file
            must  be  merged  with  the  new  vendor  release.   The ccvvss
            ``join'' command is a useful tool that aids this process  by
            performing  the  necessary  RCS merge, as is done above when
            performing an ``update.''










                                         -8-


                 There is also limited support for ``dual''  derivations
            for  source  files.   See Figure 4 for a sample dual-derived
            file.
                 __________________________________________________

            ellipse at 2.337,8.575 wid 0.700 ht 0.375
            ellipse at 2.312,9.137 wid 0.700 ht 0.375
            line from 1.225,9.012 to 1.225,9.363
            line from 1.250,9.263 to 1.225,9.363 to 1.200,9.263
            line from 0.875,9.725 to 1.600,9.725 to 1.600,9.363 to 0.875,9.363 to 0.875,9.725
            line from 0.875,9.012 to 1.600,9.012 to 1.600,8.650 to 0.875,8.650 to 0.875,9.012
            line from 4.050,10.200 to 4.775,10.200 to 4.775,9.850 to 4.050,9.850 to 4.050,10.200
            line from 4.050,9.475 to 4.775,9.475 to 4.775,9.113 to 4.050,9.113 to 4.050,9.475
            line from 4.050,8.762 to 4.775,8.762 to 4.775,8.400 to 4.050,8.400 to 4.050,8.762
            line from 4.425,8.762 to 4.425,9.113
            line from 4.450,9.013 to 4.425,9.113 to 4.400,9.013
            line from 4.425,9.475 to 4.425,9.850
            line from 4.450,9.750 to 4.425,9.850 to 4.400,9.750
            line from 3.050,10.000 to 3.775,10.000 to 3.775,9.637 to 3.050,9.637 to 3.050,10.000
            line from 3.050,9.312 to 3.775,9.312 to 3.775,8.950 to 3.050,8.950 to 3.050,9.312
            line from 0.713,7.325 to 0.713,8.075 to 4.925,8.075 to 4.925,7.325 to 0.713,7.325
            line from 1.238,8.075 to 1.238,8.637
            line from 1.262,8.537 to 1.238,8.637 to 1.213,8.537
            line from 1.613,8.825 to 1.975,8.575
            line from 1.878,8.611 to 1.975,8.575 to 1.907,8.652
            line from 2.675,8.575 to 4.050,8.575
            line from 3.950,8.550 to 4.050,8.575 to 3.950,8.600
            line from 2.675,9.137 to 3.050,9.137
            line from 2.950,9.112 to 3.050,9.137 to 2.950,9.162
            line from 3.425,9.325 to 3.425,9.637
            line from 3.450,9.537 to 3.425,9.637 to 3.400,9.537
            line from 1.613,8.825 to 1.925,9.137
            line from 1.872,9.049 to 1.925,9.137 to 1.837,9.084
            "'BSD'" at 2.138,9.481 ljust
            "1.2" at 1.113,9.543 ljust
            "1.1" at 1.125,8.831 ljust
            "1.1.1.1" at 4.175,8.543 ljust
            "1.1.1.2" at 4.175,9.281 ljust
            "1.1.1.3" at 4.175,9.993 ljust
            "1.1.2.2" at 3.175,9.793 ljust
            "1.1.2.1" at 3.175,9.106 ljust
            "rcsfile.c,v" at 2.425,7.706 ljust
            "1.1.1" at 2.175,8.568 ljust
            "'SunOS'" at 2.125,8.243 ljust
            "1.1.2" at 2.163,9.131 ljust

                 __________________________________________________

                                     FFiigguurree 44..
                        ccvvss Support For ``Dual'' Derivations

            This example tracks  the  SunOS  distribution  but  includes
            major  changes  from  Berkeley.   These  BSD files are saved













            directly in the RCS file off a new branch.

            22..33..  LLooccaattiioonn IInnddeeppeennddeenntt MMoodduullee DDaattaabbaassee
                 ccvvss contains support for a simple, yet powerful, ``mod-
            ule'' database.  For reasons of efficiency, this database is
            stored in nnddbbmm(3) format.  The module database  is  used  to
            apply  names  to  collections  of directories and files as a
            matter of convenience for checking out  pieces  of  a  large
            software  distribution.   The  database records the physical
            location of the sources as a  form  of  information  hiding,
            allowing  one  to  check  out whole directory hierarchies or
            individual files without regard for  their  actual  location
            within the global source distribution.
                 Consider   the  following  small  sample  of  a  module
            database, which must be tailored manually to  each  specific
            source repository environment:
                           ##kkeeyy      [[--ooppttiioonn aarrgguummeenntt]] ddiirreeccttoorryy [[ffiilleess......]]
                           ddiiffff      bbiinn//ddiiffff
                           lliibbcc      lliibb//lliibbcc
                           ssyyss       --oo ssyyss//ttoooollss//mmaakkee__lliinnkkss ssyyss
                           mmoodduulleess   --ii mmkkmmoodduulleess CCVVSSRROOOOTT..aaddmm mmoodduulleess
                           kkeerrnneell    --aa ssyyss llaanngg//aaddbb
                           ppss        bbiinn MMaakkeeffiillee ppss..cc
                 The ``diff'' and ``libc'' modules refer to whole direc-
            tory hierarchies that  are  extracted  on  check  out.   The
            ``sys''  module extracts the ``sys'' hierarchy, and runs the
            ``make_links'' program at the end of the check  out  process
            (the _-_o option specifies a program to run on check_out).  The
            ``modules'' module allows one to edit  the  module  database
            file and runs the ``mkmodules'' program on check_in to regen-
            erate the nnddbbmm database that ccvvss uses.  The ``kernel''  mod-
            ule  is  an  alias (as the _-_a option specifies) which causes
            the remaining arguments  after  the  _-_a  to  be  interpreted
            exactly  as  if they had been specified on the command line.
            This is useful for objects that  require  shared  pieces  of
            code  from  far  away  places to be compiled (as is the case
            with the kernel debugger, kkaaddbb, which shares code  with  the
            standard  aaddbb  debugger).   The ``ps'' module shows that the
            source for ``ps'' lives in the ``bin'' directory,  but  only
            _M_a_k_e_f_i_l_e and _p_s_._c are required to build the object.
                 The  module database at Prisma is now populated for the
            entire UNIX distribution and thereby allows us to issue  the
            following convenient commands to check out components of the
            UNIX distribution without regard for their  actual  location
            within the master source repository:
                           eexxaammppllee%% ccvvss cchheecckkoouutt ddiiffff
                           eexxaammppllee%% ccvvss cchheecckkoouutt lliibbcc ppss
                           eexxaammppllee%% ccdd ddiiffff;; mmaakkee
                 In  building the module database file, it is quite pos-
            sible to have name conflicts within a global  software  dis-
            tribution.   For  example,  SunOS provides two ccaatt programs:
            one for the standard environment, _/_b_i_n_/_c_a_t, and one for  the
            System  V  environment,  _/_u_s_r_/_5_b_i_n_/_c_a_t.   We  resolved  this










                                        -10-


            conflict by naming the standard ccaatt module ``cat'', and  the
            System  V  ccaatt  module ``5cat''.  Similar name modifications
            must be applied to other  conflicting  names,  as  might  be
            found  between  a  utility  program  and a library function,
            though Prisma chose not to include individual library  func-
            tions within the module database at this time.

            22..44..  CCoonnffiigguurraabbllee LLooggggiinngg SSuuppppoorrtt
                 The  ccvvss ``commit'' command is used to make a permanent
            change to the master source repository (where the RCS ``,v''
            files live).  Whenever a ``commit'' is done, the log message
            for the change is carefully logged by an  arbitrary  program
            (in  a  file, notesfile, news database, or mail).  For exam-
            ple, a collection of these updates can be  used  to  produce
            release  notices.  ccvvss can be configured to send log updates
            through one or more filter  programs,  based  on  a  regular
            expression  match  on  the  directory that is being changed.
            This allows multiple related or unrelated projects to  exist
            within  a  single ccvvss source repository tree, with each dif-
            ferent project sending its ``commit'' reports  to  a  unique
            log device.
                 A  sample logging configuration file might look as fol-
            lows:
                      ##rreeggeexx      ffiilltteerr--pprrooggrraamm
                      DDEEFFAAUULLTT     //uussrr//llooccaall//bbiinn//nnffppiippee --tt %%ss uuttiillss..uuppddaatteess
                      ^^ddiiaagg       //uussrr//llooccaall//bbiinn//nnffppiippee --tt %%ss ddiiaagg..uuppddaatteess
                      ^^llooccaall      //uussrr//llooccaall//bbiinn//nnffppiippee --tt %%ss llooccaall..uuppddaatteess
                      ^^ppeerrff       //uussrr//llooccaall//bbiinn//nnffppiippee --tt %%ss ppeerrff..uuppddaatteess
                      ^^ssyyss        //uussrr//llooccaall//bbiinn//nnffppiippee --tt %%ss kkeerrnneell..uuppddaatteess
                 This sample  allows  the  diagnostics  and  performance
            groups  to  share the same source repository with the kernel
            and utilities groups.   Changes  that  they  make  are  sent
            directly   to  their  own  notesfile  [Essick]  through  the
            ``nfpipe'' program.  A sufficiently simple title is  substi-
            tuted  for  the ``%s'' argument before the filter program is
            executed.  This logging configuration file is tailored manu-
            ally to each specific source repository environment.

            22..55..  TTaaggggeedd RReelleeaasseess aanndd DDaatteess
                 Any  release  can  be given a symbolic tag name that is
            stored directly in the RCS files.  This tag can be  used  at
            any time to get an exact copy of any previous release.  With
            equal ease, one can also extract an exact copy of the source
            files  as  of any arbitrary date in the past as well.  Thus,
            all that's required to tag the current kernel,  and  to  tag
            the kernel as of the Fourth of July is:
                      eexxaammppllee%% ccvvss ttaagg TTEESSTT__KKEERRNNEELL kkeerrnneell
                      eexxaammppllee%% ccvvss ttaagg --DD ''JJuullyy 44'' PPAATTRRIIOOTTIICC__KKEERRNNEELL kkeerrnneell
            The  following  command  would retrieve an exact copy of the
            test kernel at some later date:
                      eexxaammppllee%% ccvvss cchheecckkoouutt --ffpp --rrTTEESSTT__KKEERRNNEELL kkeerrnneell
            The _-_f option causes only files that match the specified tag
            to  be  extracted,  while the _-_p option automatically prunes













            empty directories.  Consequently, directories added  to  the
            kernel  after the test kernel was tagged are not included in
            the newly extracted copy of the test kernel.
                 The ccvvss date support has exactly the same interface  as
            that  provided with RCS, however ccvvss must process the ``,v''
            files directly due to the special handling required  by  the
            vendor  branch support.  The standard RCS date handling only
            processes one branch (or the main trunk) when  checking  out
            based on a date specification.  ccvvss must instead process the
            current ``head'' branch and, if a match is not  found,  pro-
            ceed  to  look for a match on the vendor branch.  This, com-
            bined with reasons of  performance,  is  why  ccvvss  processes
            revision  (symbolic  and  numeric)  and  date specifications
            directly from the ``,v'' files.

            22..66..  BBuuiillddiinngg ````ppaattcchh'''' SSoouurrccee DDiissttrriibbuuttiioonnss
                 ccvvss can produce a ``patch'' format [Wall]  output  file
            which  can  be  used to bring a previously released software
            distribution current with the newest  release.   This  patch
            file  supports an entire directory hierarchy within a single
            patch, as well as being able to add whole new files  to  the
            previous  release.   One  can combine symbolic revisions and
            dates together to display changes in a very generic way:
                      eexxaammppllee%% ccvvss ppaattcchh --DD ''DDeecceemmbbeerr 11,, 11998888'' \\
                                         --DD ''JJaannuuaarryy 11,, 11998899'' ssyyss
            This example displays the kernel changes made in  the  month
            of December, 1988.  To release a patch file, for example, to
            take the ccvvss distribution from version 1.0  to  version  1.4
            might be done as follows:
                      eexxaammppllee%% ccvvss ppaattcchh --rrCCVVSS__11__00 --rrCCVVSS__11__44 ccvvss

            33..  CCVVSS EExxppeerriieennccee

            33..11..  SSttaattiissttiiccss
                 A  quick  summary  of  the scale that ccvvss is addressing
            today can be found in Table 1.
            box center tab(:); c s c s c | c l | n .   RReevviissiioonn  CCoonnttrrooll
            SSttaattiissttiiccss  aatt  PPrriissmmaa  aass ooff 1111//1111//8899 _ How Many...:Total =
            Files:17243 Directories:1005 Lines of  code:3927255  Removed
            files:131 Software developers:14 Software groups:6 Megabytes
            of source:128
                                      TTaabbllee 11..
                                   ccvvss Statistics
            Table 2 shows the history of files changed or added and  the
            number  of  source  lines  affected by the change at Prisma.
            Only changes made to the kernel sources are  included.   The
            large  number  of  source file changes made in September are
            the result of merging the SunOS 4.0.3 sources into the  ker-
            nel.  This merge process is described in section 3.3.

            33..22..  PPeerrffoorrmmaannccee
                 The  performance  of ccvvss is currently quite reasonable.
            Little effort has been  expended  on  tuning  ccvvss,  although










                                        -12-


            box center tab(:); c s s s s c s s s s c || c | c || c | c c
            || c | c || c | c l || n | n || n | n.  PPrriissmmaa KKeerrnneell SSoouurrccee
            FFiillee CChhaannggeess BByy MMoonntthh,, 11998888--11998899 _ Month:# Changed:# Lines:#
            Added:#       Lines       :Files:Changed:Files:Added       =
            Dec:87:3619:68:9266    Jan:39:4324:0:0    Feb:73:1578:5:3550
            Mar:99:5301:18:11461                    Apr:112:7333:11:5759
            May:138:5371:17:13986 Jun:65:2261:27:12875  Jul:34:2000:1:58
            Aug:65:6378:8:4724  Sep:266:23410:113:39965 Oct:22:621:1:155
            Total:1000:62196:269:101799
                                      TTaabbllee 22..
                          ccvvss Usage History for the Kernel

            performance  related  decisions  were  made  during  the ccvvss
            design.  For  example,  ccvvss  parses  the  RCS  ``,v''  files
            directly  instead  of running an RCS process.  This includes
            following branches as well as integrating  with  the  vendor
            source  branches  and the main trunk when checking out files
            based on a date.
                 Checking  out  the  entire  kernel  source  tree  (1223
            files/59  directories) currently takes 16 wall clock minutes
            on a Sun-4/280.  However, bringing the tree up-to-date  with
            the  current  kernel  sources, once it has been checked out,
            takes only 1.5 wall clock minutes.   Updating  the  _c_o_m_p_l_e_t_e
            128  MByte  source  tree under ccvvss control (17243 files/1005
            directories) takes roughly 28 wall clock  minutes  and  uti-
            lizes  one-third  of  the machine.  For now this is entirely
            acceptable; improvements on these numbers will  possibly  be
            made in the future.

            33..33..  TThhee SSuunnOOSS 44..00..33 MMeerrggee
                 The  true  test  of  the ccvvss vendor branch support came
            with the arrival of the SunOS 4.0.3 source upgrade tape.  As
            described above, the cchheecckkiinn program was used to install the
            new sources and the resulting output file listed  the  files
            that  had  been locally modified, needing to be merged manu-
            ally.  For the kernel, there were 94 files in conflict.  The
            ccvvss  ``join'' command was used on each of the 94 conflicting
            files, and the remaining conflicts were resolved.
                 The ``join'' command performs  an  rrccssmmeerrggee  operation.
            This in turn uses _/_u_s_r_/_l_i_b_/_d_i_f_f_3 to produce a three-way diff
            file.  As it happens, the ddiiffff33  program  has  a  hard-coded
            limit of 200 source-file changes maximum.  This proved to be
            too small for a few of the kernel files that needed  merging
            by  hand,  due  to  the  large  number of local changes that
            Prisma had made.  The ddiiffff33 problem was solved by increasing
            the hard-coded limit by an order of magnitude.
                 The SunOS 4.0.3 kernel source upgrade distribution con-
            tained 346 files, 233 of which were modifications to  previ-
            ously  released  files,  and  113  of which were newly added
            files.  cchheecckkiinn added the 113 new files to the source repos-
            itory  without intervention.  Of the 233 modified files, 139
            dropped in cleanly by cchheecckkiinn, since Prisma had not made any
            local changes to them, and 94 required manual merging due to













            local modifications.  The 233 modified  files  consisted  of
            20,766 lines of differences.  It took one developer two days
            to manually merge the 94 files using  the  ``join''  command
            and  resolving  conflicts  manually.   An additional day was
            required for kernel debugging.  The entire process of  merg-
            ing  over  20,000 lines of differences was completed in less
            than a week.  This one time-savings alone was  justification
            enough  for  the  ccvvss  development effort; we expect to gain
            even more when tracking future SunOS releases.

            44..  FFuuttuurree EEnnhhaanncceemmeennttss aanndd CCuurrrreenntt BBuuggss
                 Since ccvvss was designed to be incomplete, for reasons of
            design  simplicity,  there  are  naturally  a good number of
            enhancements that can be made to make it  more  useful.   As
            well, some nuisances exist in the current implementation.
                 o  ccvvss  does  not  currently  ``remember''  who  has  a
                    checked out a copy of a module.  As a result, it  is
                    impossible  to know who might be working on the same
                    module that you are.  A simple-minded database  that
                    is updated nightly would likely suffice.
                 o  Signal  processing,  keyboard  interrupt handling in
                    particular, is currently somewhat weak.  This is due
                    to  the  heavy use of the ssyysstteemm(3) library function
                    to execute RCS programs like ccoo and  ccii.   It  some-
                    times  takes  multiple  interrupts to make ccvvss quit.
                    This can be fixed by  using  a  home-grown  ssyysstteemm()
                    replacement.
                 o  Security  of  the source repository is currently not
                    dealt with directly.  The  usual  UNIX  approach  of
                    user-group-other  security  permissions  through the
                    file system is  utilized,  but  nothing  else.   ccvvss
                    could  likely  be  a  set-group-id  executable  that
                    checks a protected database to  verify  user  access
                    permissions  for  particular objects before allowing
                    any operations to affect those objects.
                 o  With every checked-out directory, ccvvss maintains some
                    administrative  files  that record the current revi-
                    sion numbers of the checked-out files as well as the
                    location  of  the respective source repository.  ccvvss
                    does not recover nicely at all if these  administra-
                    tive files are removed.
                 o  The  source code for ccvvss has been tested extensively
                    on Sun-3 and Sun-4 systems, all running SunOS 4.0 or
                    later  versions  of the operating system.  Since the
                    code has not yet been  compiled  under  other  plat-
                    forms,  the overall portability of the code is still
                    questionable.
                 o  As witnessed in the previous section, the ccvvss method
                    for tracking third party vendor source distributions
                    can work  quite  nicely.   However,  if  the  vendor
                    changes  the  directory  structure or the file names
                    within the source distribution, ccvvss has  no  way  of
                    matching  the  old  release with the new one.  It is










                                        -14-


                    currently unclear as to how to solve this, though it
                    is certain to happen in practice.

            55..  AAvvaaiillaabbiilliittyy
                 The  ccvvss program sources can be found in a recent post-
            ing to the ccoommpp..ssoouurrcceess..uunniixx newsgroup.   It  is  also  cur-
            rently  available  via  anonymous  ftp  from ``prisma.com''.
            Copying rights for ccvvss will be covered by  the  GNU  General
            Public License.

            66..  SSuummmmaarryy
                 Prisma  has  used  ccvvss  since  December,  1988.  It has
            evolved to meet our specific needs of revision  and  release
            control.   We  will  make  our code freely available so that
            others can benefit from our work, and  can  enhance  ccvvss  to
            meet broader needs yet.
                 Many of the other software release and revision control
            systems, like the one described in [Glew], appear to  use  a
            collection of tools that are geared toward specific environ-
            ments -- one set of  tools  for  the  kernel,  one  set  for
            ``generic'' software, one set for utilities, and one set for
            kernel and utilities.  Each of these  tool  sets  apparently
            handle  some  specific  aspect of the problem uniquely.  ccvvss
            took a somewhat different approach.   File  sharing  through
            symbolic  or  hard links is not addressed; instead, the disk
            space is simply burned since it is ``cheap.''   Support  for
            producing   objects   for   multiple  architectures  is  not
            addressed; instead, a parallel checked-out source tree  must
            be  used  for each architecture, again wasting disk space to
            simplify complexity and ease of use -- punting on this issue
            allowed  _M_a_k_e_f_i_l_es  to remain unchanged, unlike the approach
            taken in [Mahler], thereby maintaining closer  compatibility
            with  the  third-party vendor sources.  ccvvss is essentially a
            source-file server, making no assumptions  or  special  han-
            dling of the sources that it controls.  To ccvvss:
                 A source is a source, of course, of course, unless
                 of course the source is Mr. Ed.6
            Sources  are  maintained, saved, and retrievable at any time
            based on symbolic or numeric revision or date in  the  past.
            It  is  entirely  up  to ccvvss wrapper programs to provide for
            release environments and such.
                 The major advantage of ccvvss over the many other  similar
            systems that have already been designed is the simplicity of
            -----------


              6 ccvvss, of course, does not  really  discriminate


            against Mr. Ed.7


              7 Yet.













            ccvvss.  ccvvss contains only three programs that do all the  work
            of release and revision control, and two manually-maintained
            administrative files for each source repository.  Of course,
            the  deciding  factor  of any tool is whether people use it,
            and if they even _l_i_k_e to use it.  At Prisma,  ccvvss  prevented
            members of the kernel group from killing each other.

            77..  AAcckknnoowwlleeddggeemmeennttss
                 Many thanks to Dick Grune at Vrije Universiteit in Ams-
            terdam for his work on the original version of ccvvss  and  for
            making  it  available  to the world.  Thanks to Jeff Polk of
            Prisma for helping with the design of the  module  database,
            vendor  branch  support,  and  for writing the cchheecckkiinn shell
            script.  Thanks also to the entire software group at  Prisma
            for taking the time to review the paper and correct my gram-
            mar.

            88..  RReeffeerreenncceess
            [Bell]      Bell Telephone Laboratories.  ``Source Code Con-
                        trol  System  User's  Guide.''   _U_N_I_X _S_y_s_t_e_m _I_I_I
                        _P_r_o_g_r_a_m_m_e_r_'_s _M_a_n_u_a_l, October 1981.
            [Courington]
                        Courington, W.  _T_h_e  _N_e_t_w_o_r_k  _S_o_f_t_w_a_r_e  _E_n_v_i_r_o_n_-
                        _m_e_n_t,   Sun   Technical   Report   FE197-0,  Sun
                        Microsystems Inc, February 1989.
            [Essick]    Essick, Raymond B.  and  Robert  Bruce  Kolstad.
                        _N_o_t_e_s_f_i_l_e  _R_e_f_e_r_e_n_c_e  _M_a_n_u_a_l, Department of Com-
                        puter Science Technical Report #1081, University
                        of  Illinois  at Urbana-Champaign, Urbana, Illi-
                        nois, 1982, p. 26.
            [Glew]      Glew, Andy.  ``Boxes, Links, and Parallel Trees:
                        Elements of a Configuration Management System.''
                        _W_o_r_k_s_h_o_p _P_r_o_c_e_e_d_i_n_g_s _o_f _t_h_e _S_o_f_t_w_a_r_e  _M_a_n_a_g_e_m_e_n_t
                        _C_o_n_f_e_r_e_n_c_e, USENIX, New Orleans, April 1989.
            [Grune]     Grune,  Dick.   Distributed  the  original shell
                        script version of ccvvss in  the  ccoommpp..ssoouurrcceess..uunniixx
                        volume 6 release in 1986.
            [Honda]     Honda, Masahiro and Terrence Miller.  ``Software
                        Management Using a CASE Environment.''  _W_o_r_k_s_h_o_p
                        _P_r_o_c_e_e_d_i_n_g_s  _o_f  _t_h_e _S_o_f_t_w_a_r_e _M_a_n_a_g_e_m_e_n_t _C_o_n_f_e_r_-
                        _e_n_c_e, USENIX, New Orleans, April 1989.
            [Mahler]    Mahler, Alex and  Andreas  Lampen.   ``An  Inte-
                        grated Toolset for Engineering Software Configu-
                        rations.''   _P_r_o_c_e_e_d_i_n_g_s   _o_f   _t_h_e   _A_C_M   _S_I_G_-
                        _S_O_F_T_/_S_I_G_P_L_A_N  _S_o_f_t_w_a_r_e  _E_n_g_i_n_e_e_r_i_n_g _S_y_m_p_o_s_i_u_m _o_n
                        _P_r_a_c_t_i_c_a_l  _S_o_f_t_w_a_r_e  _D_e_v_e_l_o_p_m_e_n_t   _E_n_v_i_r_o_n_m_e_n_t_s,
                        ACM,  Boston,  November  1988.  Described is the
                        sshhaappee toolkit posted  to  the  ccoommpp..ssoouurrcceess..uunniixx
                        newsgroup in the volume 19 release.
            [Tichy]     Tichy,  Walter F.  ``Design, Implementation, and
                        Evaluation of a Revision Control System.''  _P_r_o_-
                        _c_e_e_d_i_n_g_s  _o_f _t_h_e _6_t_h _I_n_t_e_r_n_a_t_i_o_n_a_l _C_o_n_f_e_r_e_n_c_e _o_n
                        _S_o_f_t_w_a_r_e  _E_n_g_i_n_e_e_r_i_n_g,  IEEE,  Tokyo,  September










                                        -16-


                        1982.
            [Wall]      Wall, Larry.  The ppaattcchh program is an indispens-
                        able tool for applying a diff file to an  origi-
                        nal.    Can   be   found   on   uunet.uu.net  in
                        ~ftp/pub/patch.tar.























































