





.













                           Aegis

                A Project Change Supervisor




                    CVS Transition Guide







                        Peter Miller

                  _m_i_l_l_e_r_p_@_c_a_n_b_._a_u_u_g_._o_r_g_._a_u































CVS Transition Guide                                   Aegis


.
























This document describes Aegis version 4.9
and was prepared 30 October 2002.






This  document  describing  the Aegis program, and the Aegis
program itself, are
Copyright (C) 1991, 1992,  1993,  1994,  1995,  1996,  1997,
1998,  1999,  2000,  2001,  2002  Peter  Miller;  All rights
reserved.

This program is  free  software;  you  can  redistribute  it
and/or  modify  it under the terms of the GNU General Public
License as published by the Free Software Foundation; either
version 2 of the License, or (at your option) any later ver-
sion.

This program is distributed in the hope that it will be use-
ful, but WITHOUT ANY WARRANTY; without even the implied war-
ranty of MERCHANTABILITY or FITNESS FOR  A  PARTICULAR  PUR-
POSE.   See the GNU General Public License for more details.

You should have received a copy of the  GNU  General  Public
License  along  with this program; if not, write to the Free
Software Foundation,  Inc.,  59  Temple  Place,  Suite  330,
Boston, MA 02111, USA.



Page 2         (lib/en/cvs-comparison/main.ms)  Peter Miller





Aegis                                   CVS Transition Guide


11..  CCVVSS CCoommppaarriissoonn

     This  chapter  presents a brief comparison of Aegis and
CVS.

11..11..  NNeevveerr TTrruusstt AA SSkkiinnnnyy CChheeff

     This is a comparison of Aegis and CVS, but it's written
by an Aegis expert who isn't a CVS expert.  This means that,
from time to time,  information  may  be  biased  in  Aegis'
favour  even  though  I'm  trying to be even handed.  Worse,
there are probably inaccuracies stemming  from  my  lack  of
familiarity with CVS: if you find any, I'd certainly like to
know, so I can correct this document.

11..22..  CCoonnttrriibbuuttoorrss

     In putting this chapter together,  I  solicited  assis-
tance from users on the aegis-users mailing list.  Where you
are reading their comments and not mine, you'll see it as  a
name at the end of the paragraph.

11..33..  TThhee AAeeggiiss PPrroocceessss

          ``_W_r_i_t_i_n_g _s_o_f_t_w_a_r_e _i_s _h_a_r_d_, _i_m_p_r_o_v_i_n_g _t_h_e _w_a_y _t_h_a_t
_s_o_f_t_w_a_r_e _i_s _w_r_i_t_t_e_n _i_s _h_a_r_d_e_r_.''  Bill Pugh

     Aegis sets out to perform configuration management.
This is very different to version control, but to see why
you'll need to understand what Aegis thinks a configuration
is.  Also that ``management'' word impies a degree of autho-
rization and reporting, which Aegis also provides.

+o A configuration is a snapshot of the source files, _a_l_l
  source files in the project, immediately after a commit.
  A single identifier can be used to recreate all source
  files for any one commit, and it isn't a date.  (It's like
  a CVS tag, but different.   It carries more information
  and exists long before the commit.)

+o The complete audit path for every file is available from
  this single identifier.  It includes who and when, with
  change set comments, not simply comments attached to each
  file which just happen to be the same.

+o Implicit in this, is that a commit is performed for a set
  of files, not one file at a time.

+o For each commit, the files are not simply plonked into the
  repository.  They must also compile successfully, they
  must also pass tests.  Just as some database systems vali-
  date transactions before allowing a commit, so does Aegis
  require validation.




Peter Miller    (lib/en/cvs-comparison/c1.so)         Page 3





CVS Transition Guide                                   Aegis


+o In order to enforce this validation, no-one on the project
  has write permission to the repository.  Not even the
  staff authorized to commit changes.

+o The only method of changing the repository is through
  Aegis, and this is always validated, and always peer
  reviewed, and it always leaves a record.

+o To support all of this, and private work areas too, Aegis
  imposes a process.  It is said that all software develop-
  ment uses a process, but it usually isn't written down.
  Aegis provides a process, but it is very flexible and can
  be easily adapted for your project's needs, from single
  person projects to huge team projects.

+o Version control is an important part of this process, but
  in Aegis it is like the foundations of a house: essential,
  but usually unattractive and largely out of sight.

Aegis delegates as much as possible to other tools, both
because they already exist and don't need re-writing, and
also to provide developers with maximum choice.  One of the
easiest ways to think of Aegis, to misquote the X11 folks,
is
              Aegis is about rules, not tools.
because the rules (the process) is the ``missing bit'' Aegis
was written to provide.  The "management" part of software
configuration management.

11..44..  CCVVSS hhaass nnoo BBuuiilltt--iinn PPrroocceessss

``By not having a process built into CVS, the team must work
out a process separately.  Since you're not likely to do
better than the Aegis process, the likely result is to do
worse.  Also you will have to expend effort to implement and
enforce the process.''  _T_r_e_n_t_o_n _G_. _T_w_i_n_i_n_g _<_t_g_t_@_c_y_c_l_e_-
_t_i_m_e_._c_o_m_>

``Every project I've seen _u_s_e either Aegis or an Aegis
approach, so drastically outshines other projects in the
same organization, it's clear to me that the Aegis approach
is the difference.  It works better with some analysis.  It
works better with some planning and forethought.  It
works.''  _T_r_e_n_t_o_n _G_. _T_w_i_n_i_n_g _<_t_g_t_@_c_y_c_l_e_t_i_m_e_._c_o_m_>

``For one thing, [Aegis] was actually designed, rather than
just having accreted like CVS.  And if you are looking for
code reviews and all that stuff, it's probably easier to do
them with Aegis (with CVS it is a roll-your-own type
affair).''  _J_i_m _K_i_n_g_d_o_n _<_k_i_n_g_d_o_n_@_p_a_n_i_x_7_._p_a_n_i_x_._c_o_m_> (for many
years, the chief CVS maintainer)






Page 4          (lib/en/cvs-comparison/c1.so)   Peter Miller





Aegis                                   CVS Transition Guide


11..55..  TThhee GGoooodd,, tthhee BBaadd aanndd tthhee UUggllyy

This section contains the answers to some frequently asked
questions.

11..55..11..  WWhhyy sshhoouulldd II cchhaannggee ffrroomm CCVVSS ttoo AAeeggiiss??

+o enforced review - damn important in a company environment
  _G_u_s _<_g_u_s_@_g_e_t_s_y_s_t_e_m_s_._c_o_m_>

+o mandatory testing (this may be disabled, per project)

+o More space efficient for large code trees, and only one
  copy of the baseline (also makes backup easier) _G_u_s
  _<_g_u_s_@_g_e_t_s_y_s_t_e_m_s_._c_o_m_>

+o To maintain control over your code repository.  The base-
  line can't even be written to by developers, so the audit
  trail is more secure.  _G_u_s _<_g_u_s_@_g_e_t_s_y_s_t_e_m_s_._c_o_m_>

+o Support for change sets.  My main complaint with CVS is
  that you are unable to associate modified files into a
  change so once the files are committed to the CVS reposi-
  tory, there is no easy way to back it out or work out
  which other files were changed as part of a logical set.
  _T_i_m _P_o_t_t_e_r _<_T_i_m_._P_o_t_t_e_r_@_a_n_u_._e_d_u_._a_u_>

+o Separation of the roles of developer, reviewer and inte-
  grator.  At the moment, typical distributed CVS develop-
  ment happens with people checking in stuff as they develop
  it with very little integration testing as they go along.
  It's pretty much up to people "in the know" to manually go
  through changed files and check to see if something has
  been broken by a developer.  It gets even tricker when
  there are particular assumptions made that aren't written
  down.  _T_i_m _P_o_t_t_e_r _<_T_i_m_._P_o_t_t_e_r_@_a_n_u_._e_d_u_._a_u_>

+o Automated testing support.

11..55..22..  WWhhaatt ffeeaattuurreess ddooeess CCVVSS hhaavvee tthhaatt AAeeggiiss hhaassnn''tt??

+o Low change overhead.  Developers can omit as much of the
  process as they feel like.

+o Partial checkins.  You can commit just a few files from
  your work area.

+o Works with both Windows and Unix.  Aegis still struggles
  with this, and only has weak support for Windows.

11..55..33..  HHooww ddoo II ddoo CCVVSS--ssttyyllee rreemmoottee ddeevveellooppmmeenntt??

     The short answer is: you can't.




Peter Miller    (lib/en/cvs-comparison/c1.so)         Page 5





CVS Transition Guide                                   Aegis


     The long answer will require quite a bit of understand-
ing how Aegis' development process works.  See the "Team-
work" portion of Aegis Howto and the "Geographically Dis-
tributed Development" chapter of the Aegis User Guide for
more information.




















































Page 6          (lib/en/cvs-comparison/c2.so)   Peter Miller





Aegis                                   CVS Transition Guide


22..  AAeeggiiss CCoommmmaannddss ffoorr uunnrreeccoonnssttrruucctteedd CCVVSS uusseerrss

This section compares Aegis commands and CVS commands.
There can be no exact correspondence, because they are each
actually attempting to achieve something different.

-------------------------------------------------------------
Create a new         aenpr                cvs init
project.  (In both
cases, you then
have to add con-
tent.)
-------------------------------------------------------------
Create a new work    aenc;aedb            mkdir
area.                _o_r tkaenc
-------------------------------------------------------------
Copy files into a    aecp                 cvs checkout
work area
-------------------------------------------------------------
Add a new file       aenf _f_i_l_e_n_a_m_e        cvs add _f_i_l_e_n_a_m_e
-------------------------------------------------------------
Add a whole direc-   aenf .               cvs import
tory tree as new
files.
-------------------------------------------------------------
Remove a file        aerm _f_i_l_e_n_a_m_e        cvs remove _f_i_l_e_-
                                          _n_a_m_e
-------------------------------------------------------------
Build in a work      aeb                  make
area.
-------------------------------------------------------------
Bring a work area    aem                  cvs update
up-to-date with      _(_h_o_w_e_v_e_r_, _m_e_r_g_i_n_g
the repository.      _(_t_h_e _`_`_m_'_' _i_n _a_e_m_)
                     _i_s _r_e_q_u_i_r_e_d _m_u_c_h
                     _l_e_s_s _o_f_t_e_n_)
-------------------------------------------------------------
Finish development   aede                 cvs commit
of a change.         _(_a_n_d _t_h_e_n _i_t _n_e_e_d_s
                     _t_o _b_e _r_e_v_i_e_w_e_d _a_n_d
                     _i_n_t_e_g_r_a_t_e_d_)
-------------------------------------------------------------
Rename a source      aemv _o_l_d_-_n_a_m_e _n_e_w_-   mv; cvs remove;
file                 _n_a_m_e                 cvs add
-------------------------------------------------------------
Show the differ-     aed                  cvs diff
ences between the
work area and the
repository.
-------------------------------------------------------------







Peter Miller    (lib/en/cvs-comparison/c2.so)         Page 7





CVS Transition Guide                                   Aegis


Partial commits      aeclone              cvs commit _f_i_l_e_-
are forbidden in     _T_h_i_s _c_l_o_n_e_s _t_h_e      _n_a_m_e
Aegis.  However,     _w_h_o_l_e _c_o_m_p_l_e_t_e
it is possible to    _c_h_a_n_g_e_.  _N_o_w _u_s_e
do something very    aecpu _e_t_c_, _i_n _t_h_e
similar.             _c_l_o_n_e_d _c_h_a_n_g_e _t_o
                     _g_e_t _r_i_d _o_f _t_h_e
                     _f_i_l_e_s _y_o_u _d_o_n_'_t
                     _w_a_n_t _t_o _c_o_m_m_i_t
                     _y_e_t_.
-------------------------------------------------------------
How do I browse      aecd -bl             mkdir _s_o_m_e_w_h_e_r_e
the sources?         _n_o_w _l_o_o_k _a_r_o_u_n_d      cd _s_o_m_e_w_h_e_r_e
Please note that                          cvs checkout
Aegis has a copy                          _n_o_w _l_o_o_k _a_r_o_u_n_d
sitting there
already.  With CVS
you have to create
one first.
-------------------------------------------------------------
How do I find        aefind | grep        find | grep
stuff in source
files?
-------------------------------------------------------------
Clean out every-     aeclean              make clean
thing but primary
source files from
a work area.
-------------------------------------------------------------
Make a separate      aecp -independent    cvs export
copy of sources in
the repository.
-------------------------------------------------------------


22..11..  HHooww ddoo II uussee aa RReemmoottee SSeerrvveerr??

There is no direct equivalent.  See _a_e_d_i_s_t(1) or the "Team-
work" section of the HOWTO, or the "Geographically Dis-
tributed Development" chapter of the User Guide.

















Page 8          (lib/en/cvs-comparison/c3.so)   Peter Miller





Aegis                                   CVS Transition Guide


33..  IImmppoorrttiinngg aanndd EExxppoorrttiinngg

It is possible to import a CVS repository into Aegis, while
preserving all of your history information.

Because Aegis uses change sets and CVS does not, it is nec-
essary for Aegis to ``synthesize'' the change sets during
the import process.  See the _a_e_i_m_p_o_r_t(1) command page for a
complete description of how this is done.  Once the change
sets have been discovered, the _a_e_i_m_p_o_r_t(1) command then syn-
thesizes an Aegis change for each one, and enters it into
the Aegis database as if it had taken place using Aegis.

Once this has occurred, you may then access all of the pre-
vious versions of the files as you would for any other Aegis
project.  See _a_e_c_p(1) for more information, particularly the
--ddeellttaa option.  All of the various lists and reports are
also available (see _a_e_l(1) and _a_e_r(1) for more information).
The usual web browsing is also available.

33..11..  IImmppoorrttiinngg ffrroomm CCVVSS

The command which does the importing is simple enough, but
there is some setup required first.

+o It is usual to have a separate account which "owns" an
  Aegis project.  This means that accidental file writes
  while browsing sources can't happen, among other reasons.
  Whether you have a separate account per project, or a
  hold-all source account doesn't bother Aegis (the more
  security conscious among you, however, will want one
  account per project).  If you have one account per
  project, name it after the project (there's less to remem-
  ber that way).  This example will call the both the
  account and the Aegis project ``example''.

+o It is also possible to have a separate Unix group for each
  project.  This means that you can have fine-grained con-
  trol over who has read access to your repository.  (Or, as
  above, you may want a simple source group.)  Note that
  write access to the repository is controlled via a differ-
  ent mechanism in Aegis; the repository itself will be
  read-only to _a_l_l staff, including authorized developers
  and integrators.  (See the User Guide for how your changes
  actually reach the repository.)  If you decide to have a
  group per project, use the same name as the project as,
  again, there is less to remember.

+o Login as the example user.

+o You need to decide where your Aegis project is going to
  live.  It could live below the example user's home direc-
  tory, but it does not have to.  (It is impractical for it
  to actually _b_e the example user's home directory.)



Peter Miller    (lib/en/cvs-comparison/c3.so)         Page 9





CVS Transition Guide                                   Aegis


  Wherever you put the project directory, it must be acces-
  sible from all workstations and/or servers upon which
  development _a_n_d code reviews are to be carried out.  (See
  the ``Teamwork'' chapter of the HOWTO for more informa-
  tion.)  In this example, we are going to put it in
  /projects/example; again, named for the project.

+o If you have a single project under your $CVSROOT directory
  tree, you use the commands

       unset AEGIS_PATH
       aeimport $CVSROOT -project example -dir /projects/example -verbose

  Depending on how big your project is, this may take some
  time.  You will be informed of progress, though it will
  not mean very much if you are new to Aegis.

+o If you have several modules under your $CVSROOT directory
  tree, and the module you wish to import is contained under
  a single directory, use a command such as this:

       unset AEGIS_PATH
       aeimport $CVSROOT/example -project example -dir /projects/example -verbose

  Again this may take some time.

+o If you have a more complex module structure below $CVS-
  ROOT, it may be necessary to duplicate and manually rear-
  range the directories until you have a single directory
  tree you can point the _a_e_i_m_p_o_r_t(1) command at.  There is
  no support for reading the $CVSROOT/CVSROOT/modules file
  at this time.

+o If something goes wrong part way through (_e_._g_. running out
  of disk space) you will be left with a partial Aegis
  project that isn't very useful.  Use the

       aermpr example

  command to get rid of it.

+o Once the _a_e_i_m_p_o_r_t(1) command completes successfully, you
  need to use the command

       ae_p example.1.0
       ael project_files

  to examine the names of the files Aegis has imported.  If
  they don't match your expectations (_e_._g_. if the directory
  tree is not the shape you need) remove the project
  (_a_e_r_m_p_r) and re-run _a_e_i_m_p_o_r_t(1) with the appropriate argu-
  ments.





Page 10         (lib/en/cvs-comparison/c3.so)   Peter Miller





Aegis                                   CVS Transition Guide


+o The above commands create a project called ``example'',
  with branches ``1'' and ``1.0'' (see the Branching chapter
  of the User Guide for how branching works in Aegis).  To
  access branch 1.0, you use the project name ``exam-
  ple.1.0''.  If you wanted no branches at all (just a
  trunk) then add ``-version -'' to the above _i_m_p_o_r_t(1) com-
  mands.  If you are new to Aegis, and don't understand what
  this paragraph is talking about, _d_o _n_o_t change anything.

+o The last thing you do as the example user is to add your
  normal account as a project administrator.

       aena _y_o_u_r_l_o_g_i_n

  Now logoff the example account, and login to your normal
  account.

+o Aegis has populated the development roles with staff found
  during the import.  Use the _p_r_o_j_e_c_t _s_t_a_f_f report to exam-
  ine and verify the resulting settings.

       ae_p example.1.0
       aer projstaff

  If there are staff in inappropriate roles, use the follow-
  ing commands to rearrange them.

                               Add       Remove
             Developer       _a_e_n_d(1)    _a_e_r_d(1)
             Reviewer        _a_e_n_r_v(1)   _a_e_r_r_v(1)
             Integrator      _a_e_n_i(1)    _a_e_r_i(1)
             Administrator   _a_e_n_a(1)    _a_e_r_a(1)

  See the User Guide for more information about the various
  roles within Aegis.

+o You need to customize the project config file for your
  project.  In order to do this, you will need to create a
  change set to modify the file.  The worked example in the
  User guide will be useful in understanding how this is
  done.  It is essential that you use a change set for this;
  editing the baseline directly is a _b_i_g no-no.  See also
  the configuration examples directory,
  /usr/share/aegis/config.example, for some pre-built con-
  figuration settings.  (It's probably a Bad Idea to mess
  with the history command settings, but the rest are fair
  game.)
  In  particular, your need to set the build command.  The
  _a_e_i_m_p_o_r_t(1) command has set it to ``exit 0''.  See the
  Dependency Maintenance Tool of the User Guide for more
  information.

You project should now be ready to use.  Happy developing!




Peter Miller    (lib/en/cvs-comparison/c3.so)        Page 11





CVS Transition Guide                                   Aegis


If you have questions, it is worth subscribing to the aegis-
users mailing list.  See
http://www.canb.auuf.org.au/~millerp/aegis/ for how to do
this.

33..22..  EExxppoorrttiinngg ttoo CCVVSS

If it becomes necessary to export your project from Aegis
into CVS, this may be done relatively simply.

+o This method only works if you have been using RCS as your
  history tool.

+o Backup your CVS repository.  The next step will change it.

+o Copy the ,v files from the Aegis history tree into the CVS
  root tree (the Aegis project in this example is called
  ``example''.

       ae_p example.1.0
       aecd -bl ../history
       tar cf - . | ( cd $CVSROOT ; tar xf - )

  Note that this assumes that the two directory trees are
  the same shape.  It is highly likely that you have a mod-
  ule called something like ``example'', which would change
  the last line above to look like

       tar cf - . | ( cd $CVSROOT/example ; tar xf - )

  More baroque directory structures will require more manual
  mangling during the copy.

Note that Aegis' expectations of locking, access lists, key-
word expansion, _e_t_c, are rather different to CVS, so it may
be necessary to use _f_i_n_d(1) and _r_c_s(1) to set things the way
you want.




















Page 12        (lib/en/cvs-comparison/main.ms)  Peter Miller





Aegis                                   CVS Transition Guide


.
























































Peter Miller   (lib/en/cvs-comparison/main.ms)       Page 13





CVS Transition Guide                                   Aegis


.
























































Page xiv       (lib/en/cvs-comparison/main.ms)  Peter Miller





Aegis                                   CVS Transition Guide


                     TTaabbllee ooff CCoonntteennttss


1. CVS Comparison . . . . . . . . . . . . . . . . . . . . . .   3
1.1. Never Trust A Skinny Chef  . . . . . . . . . . . . . . .   3
1.2. Contributors . . . . . . . . . . . . . . . . . . . . . .   3
1.3. The Aegis Process  . . . . . . . . . . . . . . . . . . .   3
1.4. CVS has no Built-in Process  . . . . . . . . . . . . . .   4
1.5. The Good, the Bad and the Ugly . . . . . . . . . . . . .   5
1.5.1. Why should I change from CVS to Aegis?   . . . . . . .   5
1.5.2. What features does CVS have that Aegis hasn't?   . . .   5
1.5.3. How do I do CVS-style remote development?  . . . . . .   5
2. Aegis Commands for unreconstructed CVS users . . . . . . .   7
2.1. How do I use a Remote Server?  . . . . . . . . . . . . .   8
3. Importing and Exporting  . . . . . . . . . . . . . . . . .   9
3.1. Importing from CVS . . . . . . . . . . . . . . . . . . .   9
3.2. Exporting to CVS . . . . . . . . . . . . . . . . . . . .  12








































Peter Miller   (lib/en/cvs-comparison/main.ms)       Page mi





CVS Transition Guide                                   Aegis



























































Page mii                     ()                 Peter Miller


