





.













                           Aegis

                A Project Change Supervisor




                           HOWTO







                        Peter Miller

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































Howto                                                  Aegis


.






This document describes Aegis version 3.28
and was prepared 30 August 2001.






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 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/howto/introductio.so)   Peter Miller





Aegis                                                  Howto


11..  IInnttrroodduuccttiioonn

This manual contains a series of brief lessons or ``How To''
guides  for  using  Aegis.   Each  is  arranged to cover two
pages, so that when the manual lies open on  the  desk,  the
whole subject is easily visible in front of you.

When  printing this manual, it is essential to print it dou-
ble sided, or the ``subject at once'' effect will not occur.

The  table  of  contents  will  be  printed last.  Insert it
(there should be two pages, on one sheet  of  paper)  before
this page.

11..11..  AAssssuummeedd KKnnoowwlleeddggee

Many  of these sections are written for use by beginners, so
there is a fairly low level of assumed knowledge.   However,
you  may  want  to  have _T_h_e _A_e_g_i_s _U_s_e_r _G_u_i_d_e, and _T_h_e _A_e_g_i_s
_R_e_f_e_r_e_n_c_e _M_a_n_u_a_l very close by, as all of the material  con-
veyed  here is available in a more expended or detailed form
on those manuals.

11..22..  HHoowwttoo IInnssttaallll AAeeggiiss

The description of how to build, test and install Aegis  may
be  found  in  the  Reference  Manual, under the heading _T_h_e
_B_U_I_L_D_I_N_G _F_i_l_e, which reproduces the BUILDING  file  included
in the Aegis source distribution.

If  you  installed  Aegis  using a RedHat or Debian package,
this will not be at all relevant to you, simply ignore it.

11..33..  HHoowwttoo CCoonnttrriibbuuttee

If you would like to see other ``How To''  subjects,  please
drop  me  an e-mail.  Better yet, write one and e-mail it to
me.



















Peter Miller       (lib/en/howto/main.ms)             Page 3





Howto                                                  Aegis


22..  CChheeaatt SShheeeett

This page is a quick reference into the  common  Aegis  com-
mands.

+o Usually,  ``man  _c_o_m_m_a_n_d___n_a_m_e''  can  be  used to get more
  details on a particular command.

+o See also the official Aegis quick reference  in  the  User
  Guide, page 88.

+o The  ``-p  _n_a_m_e''  option  is  used to specify the project
  name.

+o The "``-c _n_u_m_b_e_r'' option is used to  specify  the  change
  number.

+o The ``-l'' (or ``-List'') option can often be used to list
  subjects for the given command (eg. change numbers or pro-
  jects)  or simply to list rather than edit (_e_._g_. a file or
  change attributes).

22..11..  CCoommmmoonn CCoommmmaannddss

ae_p _p_r_o_j_e_c_t_-_n_a_m_e_._b_r_a_n_c_h_-_n_u_m_b_e_r
        Set current project number for all  following  Aegis
        commands.   The  ae_p command with no arguments will
        `unset' this forced default.

ae_c _n_u_m_b_e_r
        Set current change number for  all  following  Aegis
        commands.   The  ae_c command with no arguments will
        `unset' this forced default.

aecd [ -bl ]
        Change directory [change to baseline].

aeb     Aegis build - used by developers, reviewers and/  or
        integrators.

aet     Run tests - used by developers.

aed     Difference of change files with baseline.

aedless View difference files generated with aed.

ael cd  List change details.

aeca [ -l ]
        Edit [list] change attributes.

tkaenc  Create a new change (see _a_e_n_c(1) for details), using
        a GUI interface.  This makes it a damn sight  easier
        to type in the description field.



Page 4             (lib/en/howto/cheat.so)      Peter Miller





Aegis                                                  Howto


tkaeca  Edit  change  attributes  (see _a_e_c_a(1) for details),
        using a GUI interface.  This makes it a  damn  sight
        easier to edit the description field.

ael ll  List all of the lists (there are a lot).

ael c   List all of the changes for a project (branch).

ael cf  List all of the files in a change.

_a_e_u_c_o_n_f(5)
        This  is  a man page documenting the ~/.aegisrc file
        format.

22..22..  DDeevveellooppeerr CCoommmmaannddss

Procedure: ael cd -> aedb -> _d_o _s_t_u_f_f -> aeb -> aet  ->  aed
-> aedless [ -> aeclean ] -> aede

aedb[u]
     Develop begin [undo].

aede[u]
     Develop end [undo].

aeclean
     This will remove all files in the development directory
     which are not in the change  as  new  files  or  copied
     files.   This  may  delete  files  that you want, so be
     careful.

The _a_e_c_l_e_a_n(1) command uses Aegis' knowledge of what is _s_u_p_-
_p_o_s_e_d  to  be  in  the  change.  You are meant to tell Aegis
about all source files you create in  a  development  direc-
tory.  If you have forgotten to do this, it is highly likely
that the integration would fail in any case.

If you are importing files from elsewhere,  use  ``_a_e_n_f  _.''
and  all  of  the files in the directory tree below dot (the
current directory) will be added to the  change  (make  sure
there are no object files when you do this).

aecp Prepares  a  file in the project for editing within the
     change; _i_._e_.  copy  file  into  change  from  baseline.
     Remove simlink if necessary, etc.

aecpu
     Reverse the effects of the above.

aecpu -unch
     Will  check all files in your change to see if any have
     not been modified, and perform an _a_e_c_p_u on them.   This
     will  stop  an unnecessary version number increment for
     files that have not changed.  (And also  improves  test



Peter Miller       (lib/en/howto/cheat.so)            Page 5





Howto                                                  Aegis


     correlations.)

aem  Merge out-of-date files.  See the _-_O_n_l_y_-_m_e_r_g_e option of
     the _a_e_d(1) command.

aenf[u]
     Create/ add a new file [undo].

aemv Rename (move) files.

aerm[u]
     This tells Aegis the file is to  be  removed  from  the
     baseline  when  the  change is integrated.  Or _a_e_r_m_u to
     undo this _b_e_f_o_r_e the change is finished.

22..33..  RReevviieewweerr CCoommmmaannddss

Procedure: ael cd -> aecd -> aedless -> _v_i_e_w _o_u_t_p_u_t_,  _r_e_v_i_e_w
_s_o_u_r_c_e _f_i_l_e_s -> aerpass

Remember: the point of reviews is to find problems, not be a
rubber stamp.  You are expected to fail some reviews.

aerpass
     Review pass.

aerpu
     Review pass undo.

aerfail
     Review fail.

22..44..  IInntteeggrraattoorr CCoommmmaannddss

Procedure: aeib -> aeb -> aet -> aed -> aeipass

There is a script distributed with Aegis to do  this  proce-
dure     automatically:     it     may     be    found    at
_/_u_s_r_/_s_h_a_r_e_/_a_e_g_i_s_/_i_n_t_e_g_r_a_t_e___q_._s_h if  it  has  been  installed
inthe standard place.

aeib[u]
     Integrate begin [undo].

aeipass
     Integrate pass.

aeifail
     Integrate fail.

22..55..  PPrroojjeecctt AAddmmiinniissttrraattoorr CCoommmmaannddss

This  includes  all of the commands that don't fit the cate-
gories above.



Page 6             (lib/en/howto/cheat.so)      Peter Miller





Aegis                                                  Howto


aenc[u]
     Create  a  new  change  [undo].   See  _a_e_c_a_t_t_r(5)   for
     description of file format, or use _t_k_a_e_n_c(1) instead.

aend and aerd
     New developer; remove developer.

aenrv and aerrv
     New reviewer; remover reviewer.

aeni and aeri
     New integrator; remove integrator.

aena and aera
     New (project) administrator; remove administrator.

aepa [-l]
     Edit [list] project attributes (see _a_e_p_a_t_t_r(5) for file
     format).

aeca [-l]
     Edit [list] change attributes (see _a_e_c_a_t_t_r(5) for  file
     format).

tkaeca
     Edit change attributes using a GUI.  This makes it much
     easier to type in the description field.






























Peter Miller       (lib/en/howto/main.ms)             Page 7





Howto                                                  Aegis


33..  HHooww ttoo SSttaarrtt UUssiinngg AAeeggiiss

For the first-time user, Aegis can appear to be very  daunt-
ing.  It has a huge number of configuration alternatives for
each project, and it is difficult to know where to begin.

It is assumed that you already have Aegis installed.  If you
do  not,  see the section of the _R_e_f_e_r_e_n_c_e _M_a_n_u_a_l called _T_h_e
_B_U_I_L_D_I_N_G _F_i_l_e.  This reproduces the BUILDING  file  included
in the Aegis source distribution.

33..11..  FFiirrsstt,, CCrreeaattee TThhee PPrroojjeecctt

You  need  to create a new project.  Follow the instructions
in the _H_o_w _t_o _C_r_e_a_t_e _a _N_e_w _P_r_o_j_e_c_t section, and then  return
here.

33..22..  SSeeccoonndd,, UUssee aa TTeemmppllaattee PPrroojjeecctt

The very first time you use Aegis, it will be easiest if you
download one of the template projects.   This  gives  you  a
project which (almost always) works correctly the first time
``out of the box''.

+o The template projects can be found on the Aegis home page:
  http://www.canb.auug.org.au/~millerp/aegis/

+o If  you  are  a long-time GNU Make user, you probably want
  the Make-RCS template, at least to start with.

+o Follow the instructions found on the web page and you will
  have a working Aegis project, complete with self tests.

+o From  this starting point, create changes (the _t_k_a_e_n_c com-
  mand is good for this, as it gives you a simple  GUI)  and
  try  modifying  the calculator, or adding more programs to
  the project.

+o The template projects is intended to be generally  useful.
  Many  users  have simply retained this format and inserted
  their own projects into it.  (Use a change to  delete  the
  calculator and its tests.)

33..33..  SSeeccoonndd,, CCooppyy aa TTeemmppllaattee PPrroojjeecctt

If  this isn't the very first time, you may wish to get more
adventurous, and try copying the  relevant  bits  out  of  a
working  project.   Usually,  when sites first try this, the
working project will be one of the  template  projects  from
the previous section.

+o Create  a  new  project.   For this exercise, you probably
  want a single user project.




Page 8          (lib/en/howto/first_time.so)    Peter Miller





Aegis                                                  Howto


+o Create a new change

+o Copy the project _c_o_n_f_i_g file, and and files referenced  by
  it,  such as the new file templates and the build configu-
  ration file (_M_a_k_e_f_i_l_e or _H_o_w_t_o_._c_o_o_k, depending).

+o Copy the sources of the existing project into the develop-
  ment  directory.   If  you have several levels of directo-
  ries, reproduce this, too.

+o Remove files which are not primary sources (_e_._g_. the  gen-
  erated C sources of you have yacc input files).

+o Using  the  ``_a_e_n_f _.'' command (yes, that's a dot, meaning
  ``the current directory'') you can tell Aegis to  add  all
  of  the  source  files in the development directory to the
  change set.

+o You will probably need to modify your build method to meet
  Aegis'  expectations.   Rather  than  do this immediately,
  change the _b_u_i_l_d___c_o_m_m_a_n_d in the  project  _c_o_n_f_i_g  file  to
  read  ``build_command = "exit 0";'' and fix it in the next
  change set.

+o Now, build, develop end, review and integrate, as found in
  the  _U_s_e_r _G_u_i_d_e worked example.  (Except, of course, there
  is only one member of staff.)

+o Create a second change, and copy the project _c_o_n_f_i_g  file,
  and   the   build   config   file  (probably  _M_a_k_e_f_i_l_e  or
  _H_o_w_t_o_._c_o_o_k) into the change.

+o This would be a good time to read the  _D_e_p_e_n_d_e_n_c_y  _M_a_i_n_t_e_-
  _n_a_n_c_e  _T_o_o_l  chapter  of  the  Aegis  User Guide, and also
  _R_e_c_u_r_s_i_v_e _M_a_k_e _C_o_n_s_i_d_e_r_e_d _H_a_r_m_f_u_l (see  the  author's  web
  site) if you haven't already.

+o Edit the build config, try the _a_e_b command; it will proba-
  bly fail.  Iterate until things build correctly.

+o develop end, review and integrate as normal.  Your project
  is now under Aegis.















Peter Miller       (lib/en/howto/main.ms)             Page 9





Howto                                                  Aegis


44..  HHooww ttoo CCrreeaattee aa NNeeww PPrroojjeecctt

Before  you can do anything else with Aegis, you need a pro-
ject to do it to.  The advantage of this is that  each  pro-
ject is administered and configured independently.

If  this is your first time using Aegis, you probably want a
single-user project.  You can change  the  number  of  users
later, if you ever want to add more staff to the project.

You  need to select the name with some care, as changing the
project name later is tedious.  Adding aliases, however,  is
simple.

44..11..  SSiinnggllee UUsseerr PPrroojjeecctt

A  single  suer  project  is  one where all of the different
staff roles are filled by the same person, and a  number  of
interlocks are disabled, as you will see in a moment.

Unfortunately,  there  is no Tcl/Tk GUI for this, yet, which
makes this documentation bigger then it needs to be.

_D_o_n_'_t _d_o _a_n_y_t_h_i_n_g _y_e_t_!  Read through all of the steps first.

+o You may want to read the _a_e_n_p_r(1) man page for more infor-
  mation.

+o The command ``_a_e_n_p_r name _-_v_e_r_s_i_o_n _-'' will create the pro-
  ject  with  no branches.  This will automatically make you
  (that is, the executing user)  the  project  administrator
  and the project owner.  The _u_m_a_s_k is remembered, too.

+o The  root  of  the  project directory will be in your home
  directory, named after the  project  name.   If  you  want
  something else, use the _a_e_n_p_r _-_-_d_i_r_e_c_t_o_r_y option.

+o The  default group at the time of execution determines the
  file group of the project.  Make sure the account  created
  for the project has the correct group.  (Even if you don't
  understand this, your system administrator should.)

+o The _u_m_a_s_k at the time of execution  determines  the  group
  access  to  the  project.  Even if you usually work with a
  restrictive _u_m_a_s_k, set it to the right one for the project
  before running this _a_e_n_p_r command.

+o For additional security, it is often _v_e_r_y useful to create
  a UNIX user for each project.  You  may  need  to  consult
  your system administrator for assistance with this.  It is
  usual to name the user and the project the same thing,  to
  avoid  confusion.  Log in as this user to execute the ini-
  tial project creation commands; once completed nnoo oonnee will
  ever login to this account again.



Page 10         (lib/en/howto/new_project.so)   Peter Miller





Aegis                                                  Howto


+o Add  the  staff  to  the  project: the ``_a_e_n_a your-normal-
  login'' command adds your  normal  account  as  a  project
  administrator.   You  need this if you are using a special
  project account, so that your normal self  can  administer
  the project.

+o At  this  point,  log  out of the special project account.
  Ask the system administrator to permanently disable it.

+o Add the rest of the staff: the ``_a_e_n_d your-login'' command
  makes  you  a  developer, the ``_a_e_n_r_v your-login'' command
  makes you a reviewer and the ``_a_e_n_i  your-login''  command
  makes you an integrator.

+o You  need to edit the project attributes next.  The ``_a_e_p_a
  _-_e_d_i_t'' command does this.  You will be placed into a text
  editor, and will see something similar to this:

       description = "The \"_e_x_a_m_p_l_e\" project";
       developer_may_review = false;
       developer_may_integrate = false;
       reviewer_may_integrate = false;
       developers_may_create_changes = false;
       umask = 022;

  Ignore  any  extra  stuff, you should not change it at the
  moment.  To get a single user project, edit the  field  to
  read

       developer_may_review = true;
       developer_may_integrate = true;
       reviewer_may_integrate = true;
       developers_may_create_changes = true;

  Be extra careful to preserve the semicolons!  You may also
  want to change the description at this time,  too.   Don't
  forget the closing double-quote _a_n_d semicolon.

+o Create  the  first branch now.  They inherit all staff and
  attributes at creation time, which is why we worked on the
  trunk  project  first.   The command ``_a_e_n_b_r name _1'' fol-
  lowed by followed by ``_a_e_n_b_r name_._1 _0'' will  give  you  a
  branch called _n_a_m_e.1.0 for use wherever Aegis wants a pro-
  ject name.  (See the branching chapter of the  User  Guide
  for more information.)

44..22..  TTwwoo UUsseerr PPrroojjeecctt

Everything  is  done  as  above,  except you want to project
attributes to look like this:







Peter Miller    (lib/en/howto/new_project.so)        Page 11





Howto                                                  Aegis


     developer_may_review = false;
     developer_may_integrate = true;
     reviewer_may_integrate = true;
     developers_may_create_changes = true;

This says that developers can't review their own work.

You will need to add the  other  person  to  the  developer,
reviewer and integrator roles, too.

Converting  a single user project to a two person project is
simply editing the project  attributes  to  look  like  this
later.   _R_e_m_e_m_b_e_r_: each branch inherited its attributes when
it was created - you need to  edit  the  ancestor  branches'
project attributes too.

44..33..  MMuullttii UUsseerr PPrroojjeecctt

Everything  is  done  as  above,  except you want to project
attributes to look like this:

     developer_may_review = false;
     developer_may_integrate = false;
     reviewer_may_integrate = false;
     developers_may_create_changes = true;

This says that developers can't review their own  work,  and
reviewers  can't  integrate their own reviews.  This ensures
the maximum number of eyes validate each change.

You will need to add the  other  staff  to  the  appropriate
developer,  reviewer  and  integrator  roles.  Staff need to
always be permitted all  roles:  it  is  common  for  junior
staff, for example, _n_o_t to be authorised as reviewers.

Converting  a  single user project to a multi-person project
is simply editing the project attributes to look  like  this
later.   _R_e_m_e_m_b_e_r_: each branch inherited its attributes when
it was created - you need to  edit  the  ancestor  branches'
project attributes too.

44..44..   WWaarrnniinngg  TThhee _/_u_s_r_/_l_o_c_a_l_/_c_o_m_/_a_e_g_i_s_/_s_t_a_t_e ffiillee ccoonnttaaiinnss
ppooiinntteerrss ttoo ""ssyysstteemm"" pprroojjeeccttss..   _P_o_i_n_t_e_r_s_.   UUsseerrss  mmaayy  aadddd
tthheeiirr  oowwnn  pprroojjeecctt  ppooiinntteerrss  ((ttoo  tthheeiirr  oowwnn  pprroojjeeccttss)) bbyy
ppuuttttiinngg aa sseeaarrcchh ppaatthh iinnttoo tthhee _A_E_G_I_S___P_A_T_H eennvviirroonnmmeenntt  vvaarrii--
aabbllee..   TThhee  ssyysstteemm ppaarrtt iiss aallwwaayyss aauuttoommaattiiccaallllyy aappppeennddeedd bbyy
_A_e_g_i_s..  TThhee ddeeffaauulltt,, aallrreeaaddyy  sseett  bbyy  tthhee  _/_u_s_r_/_l_o_c_a_l_/_l_i_b_/_-
_a_e_g_i_s_/_c_s_h_r_c  ffiillee,,  iiss  _$_H_O_M_E_/_l_i_b_/_a_e_g_i_s..  DDoo nnoott ccrreeaattee tthhiiss
ddiirreeccttoorryy,, _A_e_g_i_s iiss ffiinniicckkyy aanndd wwaannttss ttoo ddoo tthhiiss iittsseellff..

     Where projects reside is completely flexible,  be  they
system  projects  or user projects.  They are not kept under
the _/_u_s_r_/_l_o_c_a_l_/_c_o_m_/_a_e_g_i_s directory, this directory only con-
tains pointers.



Page 12         (lib/en/howto/new_project.so)   Peter Miller





Aegis                                                  Howto


44..44..11..  CCrreeaattiinngg PPrroojjeeccttss

When  you  create  a  new  project, the _f_i_r_s_t element of the
AEGIS_PATH is used as the  place  to  remember  the  project
_p_o_i_n_t_e_r.   This  means  the  project will not show up in the
global project list if you have set  AEGIS_PATH  to  include
private projects.

There  are  two  ways  to  make sure that you are creating a
global project.   Either  ``_u_n_s_e_t  _A_E_G_I_S___P_A_T_H''  immediately
before  using  the ``_a_e_n_p_r'' command, or use the ``--library
_/_u_s_r_/_l_o_c_a_l_/_c_o_m_/_a_e_g_i_s'' option of the _a_e_n_p_r command.

44..44..22..  WWeebb VViissiibbiilliittyy

If you have a Web server, and the aegis.cgi  was  installed,
you can set its _A_E_G_I_S___P_A_T_H environment variable, if you want
it to be able to see more projects than just the global pro-
jects.    You   do   this  by  creating  a  _/_u_s_r_/_l_o_c_a_l_/_l_i_b_/_-
_a_e_g_i_s_._c_g_i_._c_o_n_f file (there isn't one, by default)  and  set-
ting  the  _A_E_G_I_S___P_A_T_H environment variable in it.  This is a
fragment of Bourne shell script, not just the name.

44..55..  CChhaannggiinngg TThhee PPrroojjeecctt OOwwnneerr

Typically, when folks try Aegis for  the  first  time,  they
don't worry about having a separate user for their projects.
However, once things are ticking along, it is less and  less
attractive  to toss it all and start again cleanly.  So, now
you need to change the  project  owner  from  the  user  who
started  the  Aegis  evaluation  to  the unique project user
account.

1. You need to be _r_o_o_t to perform this procedure.

2. Create the user account.  It  doesn't  need  to  work  to
   login,  so  the  password  can be disabled.  You probably
   want to arrange to have this user's email forwarded some-
   where  sensible  (maybe  see  the Distributed Development
   chapter of the User Guide).

3. The owner of the project is taken from the owner  of  the
   project  directory  tree,  so  this  is  what needs to be
   changed.  Go to the root of the project tree - the direc-
   tory which appears in the ``_a_e_l _p_r_o_j_e_c_t_s'' listing.  This
   isn't the trunk baseline, but the directory above it (you
   will see _i_n_f_o, _h_i_s_t_o_r_y and _b_a_s_e_l_i_n_e sub-directories).

4. Use the command

        chown -R _u_s_e_r_n_a_m_e .

   to  change the ownership of this directory, and all files
   and sub-directories below it.  Insert the username of the



Peter Miller    (lib/en/howto/new_project.so)        Page 13





Howto                                                  Aegis


   account  you created in step 2.  (You need the ddoott on the
   end of the command, its not mere punctuation.)

     There is no need to change  the  owner  of  any  active
changes, or any other change attributes.




















































Page 14            (lib/en/howto/main.ms)       Peter Miller





Aegis                                                  Howto


.
























































Peter Miller       (lib/en/howto/main.ms)            Page 15





Howto                                                  Aegis


55..  HHooww ttoo MMoovvee aa NNeeww PPrroojjeecctt

There  are  two  ways to move a project.  One is from within
Aegis, and one is from outside Aegis.

55..11..  FFrroomm wwiitthhiinn AAeeggiiss

This works best when you  are  moving  a  project  from  one
machine  to  another.  It is a VERY good ide if there are no
active changes on ANY branch.

Step 1: You need to know where in the file system  the  pro-
ject  currently  resides.   Take a look in the projects list
(ael p) and see the directory reported for the trunk of  the
project.  Ignore any active branches.

Step  2:  Usually,  when you remove a project, Aegis deleted
all of the project files.  However  the  aerm  -keep  option
tells  Aegis to remove the project name, but keep all of the
project files.

Step 3: Move the files to their new location, you  need  ALL
of  the  files below the directory tree you found in step 1.
This may be a simple file move, or may involve  copying  the
files  to tape, and then unpacking on a new machine.  Remem-
ber to make sure the file ownerships are  set  the  way  you
want.

Step  4:  Tell  Aegis where the project is.  To do this, use
the -dir and -keep options of the aenpr command.

55..22..  FFrroomm oouuttssiiddee AAeeggiiss

This works best of  the  project  is  staying  on  the  same
machine, or the same NFS network.

Step  1:  You need to know where in the file system the pro-
ject currently resides.  Take a look in  the  projects  list
(ael  p) and see the directory reported for the trunk of the
project.  Ignore any active branches.

Step 2: Move the files to the new location.

Step 3: Edit the /usr/local/com/aegis/state  file  and  edit
the  path  appropriately  to  tell Aegis where you moved the
files to.  You will need to be root for this step.











Page 16            (lib/en/howto/main.ms)       Peter Miller





Aegis                                                  Howto


.
























































Peter Miller       (lib/en/howto/main.ms)            Page 17





Howto                                                  Aegis


66..  WWoorrkkiinngg iinn TTeeaammss

Aegis supports teamwork in two basic ways: local development
and  distributed development.  Local development breaks down
into a single machine, and networked machines  on  a  common
LAN.   By  building the description a little at a time, this
section will show how each of these modes of development are
related in the model used by Aegis.

66..11..  LLooccaall


66..11..11..  SSiinnggllee UUsseerr,, SSiinnggllee MMaacchhiinnee

The simplest case to understand is the single user.  In such
an environment, there  is  a  project  and  the  user  makes
changes  to  this  project in the usual way described in the
User Guide and earlier sections of this How-To.

Even in this environment, it is often the case that a single
user  will  be  working on more than one thing at once.  You
could have a large new feature being added, and a series  of
bug  fixes  happening  in parallel during the course of this
development.  Or some-one may  interrupt  you  with  a  more
important  feature  they need to be added.  Aegis allows you
to simply and rapidly create as many or as  few  independent
changes (and development directories) as required.

By  using  independent  work areas, things which are not yet
completed cannot  be  confused  with  immediate  bug  fixes.
There is no risk of untested code "contaminating" a bug fix,
as would be the case in one large work area.

66..11..22..  MMuullttii UUsseerr,, SSiinnggllee MMaacchhiinnee

Having multiple developers working on the  same  project  is
very  little different than having one developer.  There are
simple many changes all being worked on in  parallel.   Each
has  its  own  independent work area.  Each is independently
validated before it may be integrated.

One significant difference with multiple developers is  that
you  now  have  enough people to do real code reviews.  This
can make a huge difference to code quality.

66..11..33..  MMuullttii UUsseerr,, MMuullttii MMaacchhiinnee

Aegis assumes that when working on a LAN,  you  will  use  a
networked  file  system,  of some sort.  NFS is adequate for
this task, and commonly available.  By using NFS,  there  is
very  little  difference between the single-machine case and
the multi-machine case.





Page 18          (lib/en/howto/team_work.so)    Peter Miller





Aegis                                                  Howto


There are some system administration constraints imposed  by
this, however: it is assumed that each machine is apparently
"the same", in terms of environment.

66..11..33..11..  GGeenneerraall RReeqquuiirreemmeennttss

You need some sort of network file system  (_e_._g_.  NFS,  AFS,
DFS), but it needs working locks (_i_._e_. not CODA at present).
I'll assume the ubiquitous NFS for now.

+o You need exactly the same _/_e_t_c_/_p_a_s_s_w_d and _/_e_t_c_/_g_r_o_u_p  file
  on  every machine.  This gives a uniform environment, with
  uniform security.  (It also gets the UIDs right, which NFS
  needs.)  Keeping _/_e_t_c_/_p_a_s_s_w_d and _/_e_t_c_/_g_r_o_u_p in sync across
  more than about 3 machines can be time consuming and error
  prone  if  done manually - so don't.  Use NIS or similar -
  do sys admin once, automatically takes effect  everywhere.

+o All  of  the  machines  see the same file systems with the
  same path names as all the others.   (Actually,  you  only
  need worry about the ones Aegis is interested in.)  Again,
  you can try to keep all those  _/_e_t_c_/_f_s_t_a_b  files  in  sync
  manually,  but  you are better off using NIS (or NIS+) and
  the automounter or amd.

+o All of the machines need their clocks synchronized.   Oth-
  erwise tools which use time stamps (obviously _m_a_k_e(1), but
  also a few others) will get confused.  NTP  or  XNTP  make
  this  simple  and  automatic.   In  a  pinch,  you can use
  _r_d_a_t_e(1) from cron every 15 minutes.

+o Many sites are worried about the security  of  NFS.   Usu-
  ally,  you  need to take the root password away from work-
  station users; once the environment is uniform across  all
  of  them,  the  need  for  it usually disappears.  It also
  means they can't abuse NFS,  and  they  can't  run  packet
  sniffers,  either.   By  using  netgroups (I'm _n_o_t talking
  about the _/_e_t_c_/_g_r_o_u_p_s file) you can further  restrict  who
  NFS  will  talk to.  By using NIS+ and NFSv3 you can quash
  the last couple of security issues, but  unless  you  have
  military contracts, it's rarely worth it.

Fortunately, NFS and NIS readily available, both for propri-
etary systems and open  source  systems.   Large  sites  use
these  techniques successfully and securely - and they ddoonn''tt
have _O_(_n_^_2_) or even _O_(_n_) sys admin issues, they get most sys
admin tasks down to _O_(_1_).

But,  _b_u_t,  bbuutt!!   Many sites are _v_e_r_y concerned about being
able to work when the server(s) are down.  I agree,  however
I  suggest  sweet talking your sys admin, not bashing NFS or
NIS or Aegis.  It is possible to get very high  availability
from  modern  systems  (and even ancient PCs, using Linux or
BSD).



Peter Miller     (lib/en/howto/team_work.so)         Page 19





Howto                                                  Aegis


The fact is, working in a team requires  interaction.   Lots
of  interaction.   It is an illusion that you can work inde-
pendently indefinitely.  In the  ultimate  siege  mentality,
you  need  a full and complete private copy of everything in
order to pull this off; but expect the other team member  to
carefully inspect everything you produce this way.

66..11..33..22..  AAeeggiiss--ssppeecciiffiicc RReeqquuiirreemmeennttss

There  are  a  couple  of things required, once you have the
above up and running.

+o All of the Aegis distribution can be installed locally for
  performance,  if  that's  what you need.  (Except, see the
  next item.)  Or, you can install it all on an NFS  mounted
  disk,  which guarantees everyone is always running exactly
  the same software revision which can sometimes  be  impor-
  tant (shortens upgrade times, too.)

+o Except  the  _$_{_p_r_e_f_i_x_}_/_c_o_m_/_a_e_g_i_s  directory, which must be
  the one NFS disk mounted by every single  machine  identi-
  cally,  and  must be read write.  _I_._e_. unique to the whole
  network (well, all machines using Aegis).  This  is  where
  the  pointer  to  the projects are kept, and this is where
  the database locks are kept.  If this directory isn't com-
  mon  to  every  machine,  the  Aegis database will quickly
  become corrupted.

+o The project directory tree must be on an  NFS  disk  which
  all  machines  see,  and must be the same absolute path on
  all machines.  This is  so  that  the  absolute  paths  in
  _$_{_p_r_e_f_i_x_}_/_c_o_m_/_a_e_g_i_s_/_s_t_a_t_e mean something.

+o The  development directories need to be on NFS disks every
  machine can see.  Usually, this means a common home direc-
  tory  disk,  or a common development directory disk.  This
  can still be a disk local to  the  workstation,  but  they
  must all be exported, and all must appear in the automount
  maps.  This is because Aegis assumes that  every  worksta-
  tion  has  a uniform view of the entire system (so reviews
  can review your development directory, and integrators can
  pick up the new files from your development directory).

Large software shops have used these techniques without dif-
ficulty.

66..22..  DDiissttrriibbuutteedd

The distributed functionality of Aegis  is  designed  to  be
able  to  operate  through  corporate  firewalls.  Corporate
firewall administrators, however, take a very  dim  view  of
adding  holes to the for proprietary protocols.  Aegis, as a
result, requires none.  Instead it uses  existing  protocols
such  as  e-mail,  FTP  and  HTTP.   It  will even work with



Page 20          (lib/en/howto/team_work.so)    Peter Miller





Aegis                                                  Howto


"sneaker net" (hand carried media).

The other aspect of Aegis, which you have  probably  noticed
already,  is  that it is very keen on security.  Security of
the "availability, integrity and confidentiality" kind.

Incoming change sets are subject to the same scrutiny  as  a
change  set  produced  locally.   It  is dropped into a work
area, built and tested, before being presented  for  review.
Just like any local change set would be.

66..22..11..  MMuullttiippllee SSiinnggllee--UUsseerr SSiitteess

In  the  case  of an Open Source project maintainer, this is
essential, because incoming  contributions  are  of  varying
quality,  or  may  interact  in  unfortunate ways with other
received change sets.  This careful integration checking  is
essential.   Imaging  the chaos which could ensure if change
sets  were  unconditionally  dropped  into   the   baseline.
(Deliberate malice or sabotage, of course, also being a grim
possibility.)

The careful reader will by now be  squirming.   "How",  they
wonder,  "can  the  maintainer  examine  every  change every
developer makes.  Surely it doesn't scale?"

Indeed, it would not.  Aegis provides a mechanism for aggre-
gating  changes  into "super changes".  These larger changes
can then be shipped around.  (See the Branching  chapter  in
the User Guide for more information.)

In  the  reverse  direction,  from the maintainer out to the
developer, developers in an  Open  Source  project  probably
aren't  going  to want to see each and every change set made
to the project.  Again, they can use  an  aggregation  (_e_._g_.
grab  the latest snapshot when each release is announced) to
resync in larger chunks, less  often.   The  chances  of  an
intersection  are fairly low (otherwise someone is duplicat-
ing effort) so the merge is usually quite simple.

66..22..22..  MMuullttiippllee MMuullttii--UUsseerr SSiitteess

Most distributed large-scale corporate operations are  actu-
ally  similar  to  Open Source projects, though they usually
have more staff.  There is usually a "senior" site, and  the
other  sites make their contributions, which are scrutinized
carefully before being promoted to full acceptance.

Again, aggregations become essential to the system  integra-
tion  phase  of a product.  There may even be a hierarchy of
concentrators along the way.

Junior corporate sites can sync periodically with the senior
site, too, rather than double handle (or worse) every change



Peter Miller     (lib/en/howto/team_work.so)         Page 21





Howto                                                  Aegis


set.

66..22..33..  TTeelleeccoommmmuuttiinngg

One of the most desired cases is that of telecommuting.  How
do  remote  worker,  who  may never make it into the office,
develop projects using Aegis?

There are many way to do this, but the simplest is to have a
central cite ("the office") with satellite developers.

66..22..33..11..  OOffffiiccee ttoo DDeevveellooppeerr

The  office  makes available a web interface to Aegis.  From
this, it is possible to download individual changes,  branch
updates,  or whole projects.  All of this is already present
in the Aegis distribution.

However, many corporate sites are not going to want to  make
all of their intimate development details to comprehensively
available on the web.   For  such  sites,  I  would  suggest
either  a direct "behind the firewall" dial-in, or some vir-
tual private networking software (which means users can  use
a  local  ISP, and still be treated "as if" they were behind
the firewall).

If a VPN won't fly (due to company security policies),  then
selected  encrypted  updates  could  be posted "outside", or
perhaps an procmail "change set service" could be  arranged.

66..22..33..22..  DDeevveellooppeerr ttoo OOffffiiccee

It  is  unlikely (though possible) that you would have a web
server on the developer's machine - usually you aren't  con-
nected,  to the office pulling changes sets back is probably
not viable.

The simplest mechanism is for  the  satellite  developer  to
configure  their  Aegis project so that the trunk tracks the
office version.  Once a week (or more often if you get noti-
fied  something significant has happened) pull down the lat-
est version of "the office" as a change set  and  apply  it.
This way, the trunk tracks the official version.

The developer works in a sub-branch, with aeipass configured
to e-mail branch integrations  (but  not  individual  change
sets)  back  to the office.  In this way, a work package can
be encapsulated in a branch, and sent  when  finished.   You
also  have  the  ability  to manually send the branch at any
earlier state, and it still encapsulates the set of  changes
you have made to date.






Page 22            (lib/en/howto/main.ms)       Peter Miller





Aegis                                                  Howto


.
























































Peter Miller       (lib/en/howto/main.ms)            Page 23





Howto                                                  Aegis


77..  HHooww ttoo uussee AAeeggiiss wwiitthh PPyytthhoonn

This  section  describes  how  to use Aegis to supervise the
development of Python programs.  Some of the remarks in this
section  may  also  be  helpful  to  people who use Aegis to
supervise development in other non-compiled languages.

This section is contributed courtesy  of  Tangible  Business
Software, www.tbs.co.za.  Python-specific questions relating
to  this  section  may  be   sent   to   Pieter   Nagel   at
<pnagel@tbs.co.za>.

77..11..  HHaannddlliinngg AAeeggiiss sseeaarrcchh ppaatthhss

77..11..11..  TThhee AAeeggiiss mmooddeell vvss.. tthhee PPyytthhoonn mmooddeell

Aegis'  view of a project is that it consists of a hierarchy
of project baselines.  Each baseline consists of only  those
files  that were modified as part of that (sub)project, plus
all files that were built by the DMT (see the section of the
_U_s_e_r  _G_u_i_d_e  called _T_h_e _D_e_p_e_n_d_e_n_c_y _M_a_i_n_t_e_n_a_n_c_e _T_o_o_l).  Aegis
expects the DMT to be able to  collect  the  entire  project
into one piece by searching up this baseline search path for
all needed files.

This works fine when  using  statically  compiled  languages
such  as  C.  The build process "projects" source files from
various Aegis baselines onto one or more executables.   When
these  are  run they do not need to search through the Aegis
search path for parts of themselves; they are  already  com-
plete.

Python programs, however, are never compiled and linked into
a single executable.  One could say that a Python program is
re-linked  each  time it is run.  This means that the Python
program will need to be able to find its components at  run-
time.  More importantly, it will need to avoid importing the
old versions of files from the baseline when newer  versions
are present in the development or integration directories.

77..11..22..  TThhee ssoolluuttiioonn

The  simplest  (and only recommended) way to marry Aegis and
Python is to configure Aegis to keep all  of  the  project's
files  visible in a the development and integration directo-
ries, at all times.  That way  Aegis'  search  path  becomes
irrelevant to Python.

Use  Aegis  version  3.23 or later, and set the following in
the project _c_o_n_f_i_g file:







Page 24           (lib/en/howto/python.so)      Peter Miller





Aegis                                                  Howto


     create_symlinks_before_build
             = true;
     remove_symlinks_after_integration_build
             = false;

The second directive is not available in earlier versions of
Aegis.

If you keep your Python files in a subdirectory of your pro-
ject, such as _s_r_c_/_p_y_t_h_o_n, you  will  need  that  directory's
relative  in  your  _P_Y_T_H_O_N_P_A_T_H  whenever Aegis executes your
code for testing, i.e. by setting

     test_command="\
     PYTHONPATH=$$PYTHONPATH:src/python \
     python _._._.";

in your project config file (example split  across  multiple
lines for formatting only).

It  may seem strange to you that we are not substituting the
Aegis _S_e_a_r_c_h___P_a_t_h variable into _P_Y_T_H_O_N_P_A_T_H at all - it  does
at  first  seem  to be the solution that is called for.  The
reason why we don't is very simple: _i_t _d_o_e_s _n_o_t _w_o_r_k.  It is
worth stressing the following rule:

NNeevveerr  iinnjjeecctt  aannyy  aabbssoolluuttee ppaatthh ooff aannyy AAeeggiiss bbaasseelliinnee iinnttoo
tthhee PPyytthhoonn sseeaarrcchh ppaatthh..

77..11..33..  WWhhyy sseettttiinngg PPYYTTHHOONNPPAATTHH ttoo tthhee AAeeggiiss sseeaarrcchh ppaatthh wwiillll
nnoott wwoorrkk

The reason why _P_Y_T_H_O_N_P_A_T_H does not work as Aegis expects  is
due  to  the  way  Python searches for packages.  For a full
explanation of what packages are, you can see _S_e_c_t_i_o_n _6_._4 of
the  _P_y_t_h_o_n _T_u_t_o_r_i_a_l, but the crucial point is that a Python
package consists of a directory with an _____i_n_i_t_____._p_y file  in
which  the  other  files  in  that directory which should be
treated as part of that package are listed.

When Python imports anything from a  package,  Python  first
searches for the _____i_n_i_t_____._p_y file and remembers the absolute
path of the directory where it found it.  It will thereafter
search  for  all  other parts of the package within the same
directory.   Without  the  _c_r_e_a_t_e___s_y_m_l_i_n_k_s___b_e_f_o_r_e___b_u_i_l_d  and
_r_e_m_o_v_e___s_y_m_l_i_n_k_s___a_f_t_e_r___i_n_t_e_g_r_a_t_i_o_n___b_u_i_l_d   settings  enabled,
all the needed files are not guaranteed to _b_e present in one
directory  at  all  times, however; they will most likely be
spread out over the entire Aegis search path.

The result is that if you were to try and use  the  approach
of  setting the _P_Y_T_H_O_N_P_A_T_H to the Aegis search path, package
import will mysteriously fail under (at  least)  two  condi-
tions:



Peter Miller      (lib/en/howto/python.so)           Page 25





Howto                                                  Aegis


+o Whenever  you modify a file in a package without modifying
  the  accompanying  _____i_n_i_t_____._p_y,  Python  will   find   the
  _____i_n_i_t_____._p_y  file in the baseline and import the _o_l_d files
  from there.

+o Whenever you modify the _____i_n_i_t_____._p_y and leave  some  other
  file  in  the  package  unmodified,  Aegis  will  find the
  _____i_n_i_t_____._p_y in the development/integration  directory  but
  fail to find the unmodified files there.

77..22..  TThhee bbuuiilldd sstteepp

Python programs do not need to be built, compiled, or linked
before they can be run, but Aegis requires a build  step  as
part of the development cycle.

One  perfectly  valid  option  is  to explicitly declare the
build step to be a no-op, by setting

     build_command = "true";

in the project config file. _t_r_u_e(1) is a Unix command  which
is guaranteed to always succeed.

In  practice,  however,  there often are housekeeping chores
that can be done as part of the build process,  so  you  can
just  as well go ahead and reate a Makefile, Cook recipe, or
script that performs these tasks and make  that  your  build
step.

Here are some examples of tasks that can be performed during
the build step:

+o Setting the executable flag on your main  scripts.   Aegis
  does  not  store file modes, but it is often convenient to
  have one or more of the Python source files in  your  pro-
  ject  be  excutable,  so  that one does not need to invoke
  Python explicitly to run them.

+o Delete unwanted Python object files (_._p_y_c and _._p_y_o files).
  These  could  arise  when  you  aerm  and  delete a Python
  script, but  forget  to  delete  the  accompanying  Python
  object  file(s).   Other files will then mysteriously suc-
  ceed in importing the removed  scripts,  where  you  would
  expect them to fail.  Your build process could use _a_e_l _-_c_f
  and _a_e_l _-_p_f) to get  a  list  of  'allowed'  scripts,  and
  remove  all Python object files which do not correspond to
  any of these.

+o Autogenerate  your  packages  _____i_n_i_t_____._p_y  files.   Python
  wants  you  to  declare  your  intent  to have a directory
  treated as a package  by  creating  the  _____i_n_i_t_____._p_y  file
  (otherwise  a  stray  directory  with  a  common name like
  'string', 'test', 'common' or  'foo'  could  shadow  like-



Page 26           (lib/en/howto/python.so)      Peter Miller





Aegis                                                  Howto


  named  packages  later  on in the search path).  But since
  Aegis is, by definition, an authoritative source  on  what
  is  and  what  is  not part of your program it can just as
  well declare your intent for you.

77..33..  TTeessttiinngg

Testing under Aegis using Python is no  different  from  any
other  language, only much more fun.  Python's run-time type
checking makes it  much  easier  to  develop  software  from
loosely-coupled  components.   Such components are much more
suited to unit testing than strongly-coupled components are.

If  the  testing  script which Aegis invokes is part of your
project, there is one important  _P_Y_T_H_O_N_P_A_T_H-related  caveat:
when  Aegis  runs the tests, it specifies them with an abso-
lute path.  When Python runs any scripts  with  an  absolute
path, it prepends that path to its search path, and the dan-
ger is that the baseline directory (with the old,  unchanged
versions  of  files)  is  prepended  to the search path when
doing regression testing.

The solution is to use code like this to remove  the  test's
absolute path from the Python path:

     selfdir = os.path.abspath(sys.argv[0])
     if selfdir in sys.path:
             sys.path.remove(selfdir)


Instead  of copying these lines into each new test file, you
may want to centralize that code in  a  test  harness  which
imports  and  runs the tests on Aegis' behalf.  This harness
can also serve as a central place where  you  can  translate
test  success  or  failure  into  the  exit  statuses  Aegis
expects.

The test harness must take care to import  the  file  to  be
tested  without needing to add the absolute path of the file
to _s_y_s_._p_a_t_h.  Use _i_m_p_._f_i_n_d___m_o_d_u_l_e and _i_m_p_._f_i_n_d___m_o_d_u_l_e.

I can strongly recommend _P_y_U_n_i_t,  the  _P_y_t_h_o_n  _U_n_i_t  _T_e_s_t_i_n_g
_F_r_a_m_e_w_o_r_k  by  Steve  Purcell,  available  from  http://pyu-
nit.sourceforge.net.  It is based on  Kent  Beck  and  Erich
Gamma's  _J_U_n_i_t  framework  for Java, and is becoming the _d_e_-
_f_a_c_t_o standard testing framework for Python.

One bit of advice when using _P_y_U_n_i_t: like Aegis, _P_y_U_n_i_t also
distinguishes  between  test  failures  as  opposed  to test
errors, but I find it best to report _P_y_U_n_i_t test  errors  as
Aegis  test failures.  This is to ensure that baseline tests
fail as Aegis expects them to.  _P_y_U_n_i_t will consider a  test
which  raises  anything other than a _A_s_s_e_r_t_i_o_n_E_r_r_o_r to be an
'error', but in practice baseline test  failures  are  often



Peter Miller      (lib/en/howto/python.so)           Page 27





Howto                                                  Aegis


_A_t_t_r_i_b_u_t_e_E_r_r_o_r  exceptions which arise when the test invokes
methods not present in the old code.  This is  a  legitemate
way  to  verify,  as  Aegis  wants us to, that the test does
indeed invoke and test functionality which  is  not  present
the old code.

77..44..  RRuunnnniinngg yyoouurr pprrooggrraammss

Of  course you will at some stage want to run the program(s)
you are developing.

The simplest approach is to have your program's main  script
be   located   at   the  top  of  your  Python  source  tree
(_s_r_c_/_p_y_t_h_o_n) in our example.  Whenever you run that  script,
Python  will automatically add the directory it was found in
to the Python path, and will find all your other files  from
there.

You  can  safely  let your shell's _P_A_T_H environment variable
point to that script's location, since the  shell  _P_A_T_H  and
the _P_Y_T_H_O_N_P_A_T_H do not mutually interfere.

Just  avoid  the temptation to set the absolute path of that
script into your _P_Y_T_H_O_N_P_A_T_H, or otherwise  your  development
code and baseline code will interfere with each other.  This
is not an Aegis-specific problem, though, since there  would
be potential confusion on any system, in any language, where
two versions of one program are simultaneously visible  from
the same search path.




























Page 28            (lib/en/howto/main.ms)       Peter Miller





Aegis                                                  Howto


.
























































Peter Miller       (lib/en/howto/main.ms)            Page 29





Howto                                                  Aegis


88..  HHoowwttoo EEnndd AA BBrraanncchh

``OK,  I  give  up.   I  do  not  understand  the  ending of
branches.''

Usually, you end development of a branch the  same  way  you
end development of a simple change.  In this example, branch
_e_x_a_m_p_l_e_._1_._4_2 will be ended:

     % aaeeddee --pp eexxaammppllee 11 --cc 4422
     aegis: project "example.1": change 42: file "_f_u_b_a_r" in
     the baseline has changed since the last 'aegis -DIFFer-
     ence' command, you need to do a merge
     %

Oops.  Something went wrong.  Don't panic!

I'm going to assume, for the purposes of explanation, that
there have been changes in one of the  ancestor branches,
and thus require a merge, just like file _f_u_b_a_r, above.

You need to bring file _f_u_b_a_r up-to-date.  How?  You do it in
a change set, like everything else.

At his point you need to do 5 things: (1) create a new
change on example.1.42, (2) copy _f_u_b_a_r into it, (3) merge
_f_u_b_a_r with branch "example.1" (4) end development of the
change and integrate it, and (5) now you can end exam-
ple.1.42

The -GrandParent option is a special case of the -BRanch
option.  You are actually doing a cross-branch merge, just
up-and-down rather than sideways.

     % aaeemm --ggpp _f_u_b_a_r
     %

And manually fix any conflicts... naturally.

At this point, have a look at the file listing, it will show
you something you have never seen before - it will show you
what it is _g_o_i_n_g _t_o set the branch's edit_number_origin to
for each file, at _a_e_i_p_a_s_s.

     % aaeell ccff
     Type   Action Edit        File Name
     ------ ------ -------     -----------
     source modify 1.3         aerect/rect.c
                   {cross 1.2}

Now finish the change as usual...  _a_e_b_, _a_e_d_, _a_e_d_e_, _a_e_r_p_a_s_s_,
_a_e_i_b_, _._._._, _a_e_i_p_a_s_s nothing special here.





Page 30           (lib/en/howto/branch.so)      Peter Miller





Aegis                                                  Howto


One small tip: merge file files one at a time.  It makes
keeping track of where you are up to much easier.

Now you can end development of the branch, because all of
the files are up-to-date.

In some cases, Aegis has detected a logical conflict where
you, the human, know there is none.  Remember that the _a_e_m
command saves the old version of the file with a ,B suffix
(`B' for backup).  If you have a file like this, just use

     % mmvv _f_u_b_a_r,,BB _f_u_b_a_r
     %

to discard everything from the ancestor branch, and use the
current branch.









































Peter Miller       (lib/en/howto/main.ms)            Page 31





Howto                                                  Aegis


99..  BBeeccoommiinngg aann AAeeggiiss DDeevveellooppeerr

This section describes how to become an Aegis developer, and
gives some procedures, some ideas of areas which need work,
and some general guidelines.

99..11..  RReeqquuiirreedd SSooffttwwaarree

There are a number of pieces of software you will need to
work on Aegis.

+o It will probably come as no surprise that Aegis is devel-
  oped using Aegis (never trust a skinny chef) so the first
  thing you need is to install Aegis and become familiar
  with using it.

+o You will need to install Cook, in order to build things.
  Version 2.8 or later, preferably you should track the lat-
  est release.

+o GNU autoconf 2.13.  Be careful on this one, I'm told 2.50
  doesn't work.

+o You will need to install FHist, for the history tool.

+o You will need to install _t_a_r_d_y, for manipulating tarballs.

+o You will need the developer libraries for the _r_x library
  (if you installed from the tarball, you have these, but if
  you installed from RPM, you probably

+o You will need the developer libraries for the _z_l_i_b library
  (if you installed from the tarball, you have these, but if
  you installed from RPM, you probably don't).

+o You need to install Bison, the GNU Yacc replacement.

+o You need to GNU Gettext tools installed.  Even though
  Glibc 2.0 and later include gettext, you need to developer
  tools as well.  (You need GNU Gettext even on Solaris,
  because the Solaris Gettext implementation is... well...
  stuffed.)

+o You need psutils (e.g.
  http://www.dcs.ed.ac.uk/home/ajcd/psutils/) for the psse-
  lect utility, to manipulate the doucmentation files,
  mostly to put the tables of contents at the start, rather
  than at the end as GNU Groff generates them.

+o You need GNU Ghostscript, for tht ps2pdf utility, so that
  you can create PDF documents.

+o You need _u_u_e_n_c_o_d_e with a -o option (to redirect the out-
  put).  It is part of GNU Sharutils.



Page 32          (lib/en/howto/developer.so)    Peter Miller





Aegis                                                  Howto


+o You need _p_t_x, to form the permuted indices.  It is part of
  GNU Textutils.

+o _P_r_o_b_a_b_l_y _m_o_r_e _t_h_i_n_g_s _I_'_v_e _f_o_r_g_o_t_t_e_n_.

99..22..  CCrreeaattee TThhee AAeeggiiss PPrroojjeecctt

The next thing to do is create an Aegis project to hold the
Aegis source.  This is done in the usual way.  I suggest you
create branches which match the current public release, _e_._g_.
it is 3.28 at present.

The best-practice technique of having a separate user
account to mind the sources is recommended.  The following
commands should be run as that user, not your usual login.
This prevents a variety of accidents which can happen when
you are browsing the baseline (master source).

You could use the following command:

     % aaeennpprr aaeeggiiss..33..2288
     aegis: project "aegis": created
     aegis: project "aegis.3.28": created
     %

but experienced Aegis users will know that this means a
laborious setting of project attributes.  It is easier to
create the top-level project, set the attributes, and the
create the branches, so that they inherit the attributes on
creation.

     % aaeennpprr aaeeggiiss --vveerrssiioonn --
     aegis: project "aegis": created
     % aaeeppaa --ee --pp aaeeggiiss
     _e_d_i_t_s _t_h_e _p_r_o_j_e_c_t _a_t_t_r_i_b_u_t_e_s _f_o_r _s_i_n_g_l_e _u_s_e_r
     % aaeennaa --pp aaeeggiiss _y_o_u
     aegis: user "_y_o_u" is now a administrator
     % aaeenndd --pp aaeeggiiss _y_o_u
     aegis: user "_y_o_u" is now a developer
     % aaeennrrvv --pp aaeeggiiss _y_o_u
     aegis: user "_y_o_u" is now a reviewer
     % aaeennii --pp aaeeggiiss _y_o_u
     aegis: user "_y_o_u" is now an integrator
     % aaeennbbrr --pp aaeeggiiss 33..2288
     aaeeggiiss:: pprroojjeecctt ""aaeeggiiss..33..2288"":: ccrreeaatteedd
     %%


At this point, the rest of the commands in this chapter may
(should!) be executed as ``_y_o_u,'' your usual login account.
When you added your normal account as an administrator just
now, you authorized yourself to perform the necessary
actions.




Peter Miller     (lib/en/howto/developer.so)         Page 33





Howto                                                  Aegis


You will need about 120MB of free space to build and inte-
grate Aegis changes, or more, depending on the changes you
make and the size of your development directories.

The _._f_o_r_w_a_r_d file of the ``aegis'' user needs to be set to
someone appropriate to read mail directed at the project.

You can now set the ``aegis'' user's password field to
``*''.  This effectively prevents the ``aegis'' user from
logging in.  Aegis is designed to make this unnecessary from
now on.

99..33..  TThhee DDoowwnnllooaadd

The Aegis project is distributed in the form of an _a_e_d_i_s_t(1)
change set.  The file to download is called
http://www.canb.auug.org.au/~millerp/aegis/aegis-3.28.ae and
can be grabbed using your favorite web browser.

The downloaded change set is applied using the following
command

     % aaeeddiisstt ----rreecceeiivvee --ff aaeeggiiss--33..2288..aaee --pp aaeeggiiss..33..2288
     _._._._l_o_t_s _o_f _o_u_t_p_u_t_._._.
     %


It is a good idea to give the project name on the command
line, or _a_e_d_i_s_t will try to use the project name it finds in
the change set, and it probably wont find it if you are
using different numbering to the chief maintainer's copy.

The _a_e_d_i_s_t command will, in turn, issue a number of other
commands.  These are all normal Aegis commands you could
issue yourself, if you were familiar with Aegis.  It will,
however, stop with a moderately alarming message:

     Warning: This change contains files which could host a
     Trojan horse attack.    You should review it before
     building it or testing it or completing development.
     This change remains in the being_developed state.

This message comes because in order to build the project,
you are going to have to execute a number of commands con-
tained in the project _c_o_n_f_i_g file, and in the _e_t_c_/_H_o_w_t_o_._c_o_o_k
file.  For your own protection, _a_e_d_i_s_t stops at this point.
You may want to inspect these two files before continuing.

_I _r_e_a_l_l_y _m_u_s_t _g_e_t _a_r_o_u_n_d _t_o _s_i_g_n_i_n_g _i_t _w_i_t_h _P_G_P_.  _T_h_i_s _w_o_u_l_d
_m_a_k_e _t_h_e _-_n_o_t_r_o_j_a_n _o_p_t_i_o_n _s_a_f_e_, _b_e_c_a_u_s_e _y_o_u _c_o_u_l_d _t_e_l_l _t_h_e
_f_i_l_e _i_s _d_i_r_e_c_t _f_r_o_m _t_h_e _c_h_i_e_f _m_a_i_n_t_a_i_n_e_r_, _a_n_d _t_h_u_s _a_s
_t_r_u_s_t_a_b_l_e _a_s _y_o_u _t_h_i_n_k _t_h_e _c_h_i_e_f _m_a_i_n_t_a_i_n_e_r _h_a_p_p_e_n_s _t_o _b_e_.





Page 34          (lib/en/howto/developer.so)    Peter Miller





Aegis                                                  Howto


In order to complete development of the change set, you must
first build it...

     % aaeeccdd
     % aaeebb
     _._._._y_o_u _w_i_l_l _s_e_e _c_o_m_m_a_n_d_s _w_h_i_c_h _b_u_i_l_d _t_h_e _p_r_o_j_e_c_t_._._.
     %


Things that can go wrong...

+o If you don't have Cook installed, the build command (aeb)
  will fail.

+o If you don't have GNU Bison installed, the build will
  fail.

+o If you don't have Gettext installed, including the devel-
  oper tools, the build will fail.

Once the change builds, you need to difference it (this is a
little redundant for this first command, but you'll see how
useful it is later).

     % aaeedd
     _._._._y_o_u _w_i_l_l _s_e_e _c_o_m_m_a_n_d_s _w_h_i_c_h _"_d_i_f_f_" _t_h_e _p_r_o_j_e_c_t_._._.
     %


Things that can go wrong...

+o If you don't have the FHist package installed, the differ-
  ence (aed) will fail.  The _f_c_o_m_p command it is looking for
  is a whole-file context difference command (the GNU ddiiffff
  --cc is a bit too terse for humans).

Now you will need to test the change.  This is the basic
test suite for Aegis, it ensures nothing is broken.  It
takes a while, go grab a cup of coffee.

     % aaeett &&&& aaeett --bbll
     _._._._l_o_t_s _o_f _o_u_t_p_u_t_._._.
     %


The change is now ready to end development.

     % aaeeddee
     aegis: project "aegis.3.28": change 10: development complete
     %


The change set is now ready to be reviewed.  In a single-
person project like this one, you can review your own work.



Peter Miller     (lib/en/howto/developer.so)         Page 35





Howto                                                  Aegis


Obviously this is a conflict of interest, and larger pro-
jects are usually configured to have Aegis prevent this.

     % aaeerrppaassss --pp eexxaammppllee..11..00 --cc 1100
     aegis: project "aegis.3.28": change 10: review pass
     %


The change is now ready to be integrated.  Only when inte-
gration is complete are the files actually committed to the
repository.

     % aaeeiibb --pp eexxaammppllee..11..00 --cc 1100
     % aaeebb
     _._._._y_o_u _w_i_l_l _s_e_e _c_o_m_m_a_n_d_s _w_h_i_c_h _b_u_i_l_d _t_h_e _p_r_o_j_e_c_t_._._.
     Integrator: please use the following command:
       su1 -c "chown root _a_r_c_h/bin/aegis && chmod u+s _a_r_c_h/bin/aegis"
     %


This message at the end of the build is where Aegis is made
set-uid-root in the repository.  You want to do this,
because you are going to symlink out of _/_u_s_r_/_l_o_c_a_l_/_b_i_n (or
wherever you installed Aegis) right into the baseline.  In
this way, you will be executing your bleeding-edge version
of Aegis, exercising it before you send it to anyone else.
Hang on a bit, that comes later.

If you don't have my _s_u_1(1) command, just use _s_u(1) instead,
or _s_u_d_o or something.  Then continue with the integration...

     % aaeedd
     _._._._y_o_u _w_i_l_l _s_e_e _c_o_m_m_a_n_d_s _w_h_i_c_h _"_d_i_f_f_" _t_h_e _p_r_o_j_e_c_t_._._.
     % _a_e_t _&_& _a_e_t _-_b_l
     _._._._l_o_t_s _o_f _o_u_t_p_u_t_._._.
     % ccdd
     % aaeeiippaassss
     _._._._y_o_u _w_i_l_l _s_e_e _c_o_m_m_a_n_d_s _c_o_m_m_i_t_t_i_n_g _t_h_e _f_i_l_e_s _t_o _f_h_i_s_t_._._.
     aegis: project "aegis.1.0": change 10: integrate pass
     %


The ``_c_d'' command you see is actually important: you need
to be out of the development directory and integration
directory so that they can be cleaned up (deleted) when the
change completes.

99..44..  TThhee BBlleeeeddiinngg EEddggee

As I mentioned above, the next thing to do is create sym-
bolic links out of _/_u_s_r_/_l_o_c_a_l_/_b_i_n into your Aegis baseline.
The reason for doing this is so that you exercise your Aegis
changes by using Aegis before you send them to anyone else.
(Never trust a skinny chef.)



Page 36          (lib/en/howto/developer.so)    Peter Miller





Aegis                                                  Howto


I use the following shell script...

     #!/bin/sh
     project=aegis.3.28
     arch=linux-i486 # _s_e_t _t_h_i_s _t_o _m_a_t_c_h _y_o_u_r _s_y_s_t_e_m
     prefix=/usr/local
     bin=$prefix/bin # _s_e_t _t_h_i_s _t_o _m_a_t_c_h _y_o_u_r _s_y_s_t_e_m
     dir=`$ibin/aegis -cd -bl -p $project`
     test $? -eq 0 || exit 1
     bin=$dir/$arch/bin


     echo bin...
     cd $prefix/bin
     for f in aegis aereport aefind aerect aesub \
             tkaegis tkaeca tkaenc aedist
     do
             rm $f
             ln -s $dir/$arch/bin/$f $f
     done


     echo lib...
     cd $prefix/lib/aegis
     for f in en
     do
             rm -rf $f
             ln -s $dir/$arch/lib/$f $f
     done
     for f in profile cshrc
     do
             rm $f
             ln -s $dir/$arch/lib/$f $f
     done


     echo share...
     cd $prefix/share/aegis
     for f in en/html report config.example wish
     do
             rm -rf $f
             mkdir $f
             ln -s `$bin/aefind -p $project -bl -baserel
     lib/$f -type f ! -name "*,*" ! -name "*.d" -print
     -resolve` $f/.
     done
     for f in report.index aegis.icon aegis.mask
     do
             rm $f
             ln -s `$bin/aefind -p $project -bl -baserel
     lib/$f -type f ! -name "*,*" ! -name "*.d" -print
     -resolve` $f
     done




Peter Miller     (lib/en/howto/developer.so)         Page 37





Howto                                                  Aegis


     echo web...
     cd /home/httpd/cgi-bin
     for f in aegis.cgi
     do
             rm $f
             ln -s $dir/$arch/lib/$f $f
     done


99..55..  UUnnddiissccoovveerreedd CCoouunnttrryy

If you go this far, your local Aegis project is ready for
use.

It is strongly suggested that you complete the first change
``as is'' and perform your own customizations in later
changes, rather than trying to get the project started and
customize it at the same time.

The rest of this file describes how to perform various com-
mon changes to the example project.

99..66..  SSeennddiinngg CChhaannggeess

First, read the Distributed Development chapter of the User
Guide.

Use a simple command such as

     aedit -p aegis.3.28 -bl | \
     pgp | \
     mail millerp@canb.auug.org.au

or similar.  A suitable subject line would be very helpful.

99..77..  GGuuiiddeelliinneess


99..77..11..  WWhhaatt YYoouu CCaann DDoo

Write more documentation.  There is a crying need for docu-
mentation of all sorts: better manual pages, more and better
information in the User Guide, more and better HOWTOs.  If
you work out how to do something, and it isn't in the docu-
mentation, write some documentation and put it in a change
set because other folks have probably missed it too.

Add more ease-of-use functionality.  Stuff which makes the
development process more efficient, or makes the information
in the repository more accessible.

Extend the GUI.  All of the commands which manipulate the
change whil ein the _b_e_i_n_g _d_e_v_e_l_o_p_e_d state are candidates.
Some kind of wrapper that ties it all together would be



Page 38          (lib/en/howto/developer.so)    Peter Miller





Aegis                                                  Howto


good, too.  User preferences, project attributes and creat-
ing projects are candidates, too.

Most new project configuration things belong in the project
_c_o_n_f_i_g file.  Only add new project attribytes (aepa -e) for
things which (a) are catch 22 to change in a change set, or
(b) allow a security abuse if in a change set (e.g. the
notify commands, particuly aede), or (c) allow the reposi-
tory to be damaged.  (My thanks to Ralf Fassel
<ralf@akutech.de> 2 Feb 1999 for pointing this out.)

99..77..22..  WWhhaatt YYoouu CCaann''tt DDoo

You can't change Aegis' semantics.  Developers around the
world, and their managers, rely on  Aegis working just the
way it does right now.  You can't change things that will
compromise their ability to get things done.

Particularly, Aegis has a strong security story.  Availabil-
ity, integrity and configentiality, and all that.  If you
want it more flexible, that's good, but you can't change the
defaults and you can't make it irretrievably weaker.

Aegis (the executable, not the whole package) is quite big
enough.  Don't add code to _a_r_c_h/bin/aegis than can be done
with the report generator, or as a separate program like
aesub or aefind.  More GUI can be added using Tk/Tcl -
unless you have grander plans and even then it _s_t_i_l_l
shouldn't be added to the set-uid-root executable.

Probably need a GNU Indent profile for code formatting, too.

99..88..  TThhee TToo--DDoo LLiisstt

99..88..11..  DDooccuummeennttaattiioonn

+o Add a section to the branching chapter of the User Guide,
  describing how a developer may use a branch to temporarily
  waive the build command.  After a series of chnages on
  this branch, the build command is restored, and the branch
  development ended.  This allows regular "non working" com-
  mits, without losing any of the strengths of the Aegis
  process.  Submitted: 7-Mar-2000

+o The manual pages need to have an example(s) section added
  to make them clearer.  This isn't just for beginners,
  infrequently used commands need examples even for sophis-
  ticated Aegis users..  Submitted: Geoff Soutter
  <geoff@whitewolf.com.au>, 3 Mar 2000

+o Get tkdiff 3-way merge working with Aegis (see
  http://www.ede.com/free/tkdiff/ for code).  There is also
  a suggestion of using tkdiff instead of _m_o_r_e in _a_e_d_m_o_r_e or
  _l_e_s_s in _a_e_d_l_e_s_s.  Submitted: 24-jan-2000



Peter Miller    (lib/en/howto/devel_to_do.so)        Page 39





Howto                                                  Aegis


+o Add information to the History Tool chapter, describing
  how to use CVSup to access the RCS history tree.  Submit-
  ted: 28-jan-2000

+o the RCS history commands in the aegis user guide all use
  the `-u' option for `ci' to check out a copy after regis-
  tering/updating a file.  However `ci -u' always does key-
  word expansion.  To avoid this, we have omitted the -u, so
  the working file is gone after the `ci'.  We check it out
  again using `co', this time with the `-ko' option to avoid
  keyword expansion.  Note that the -ko option is always
  given to the `co' command, never to `ci' or `rcs'.  Sub-
  mitted: Ralf Fassel <ralf@akutech.de>, 18 Jan 2000

+o * diff ; test $? -le 1 -> diff ; test $? -ne 1 means that
  unchanged files prevent aede!!  (Only fly in the ointment
  is moving files - need to cope with this.)  Submitted: Gus
  <gus@getsystems.com> 28 Jul 1999

+o document HOWTO change project name.  Didn't I do this
  already?  Submitted: Marko Schuetz <marko@ki.infor-
  matik.uni-frankfurt.de>, 7 Jul 1999

+o mention in the diff tool part of the User Guide, that you
  can mess with diff_command to exclude with binary files,
  or file with CR in them, or lines too long, _e_t_c.  Submit-
  ted: PMiller, 28-jun-99

+o in the branching chapter, have a section about using sub-
  branches to turn build_command off (or to ignore exit sta-
  tus), and inregrate lots of teeny tiny bug fixes, and then
  turn it on again.  In the front, reference the branching
  chapter in ``how to extend the Aegis process''  Can men-
  tion extra review steps there, too.  Submitted: choff-
  man@dvcorp.com, 22 Jun 1999

+o Document the build_time_adjust_notify_command in the DMT
  chapter of the User Guide.  Update the example projects to
  use it.  Update the config exmaple to use it.  Submitted:
  PMiller, 4-apr-99

+o Mention binary files in the history tool section, also
  diff and merge (may provide aebinfil command to help
  choose which behaviour?)  Submitted: PMiller, 31-mar-99

+o mention ``rcs -ko'' in the User Guide and put it into the
  examples AND also fhist keywords in the User Guide and put
  it into the examples.  and make sure the examples all have
  hist_{put,create} the same.  Subject: Ralf Fassel
  <ralf@akutech.de>, 9 Mar 1999

+o worked example, ``5.2.7 says that the cook file contains
  all of the above commands but my copy doesn't have them
  ...''  [for config file and howto.cook file] BUT



Page 40         (lib/en/howto/devel_to_do.so)   Peter Miller





Aegis                                                  Howto


  integration diffs not in the worked example.  Submitted:
  Michael McCarty <mmccarty@xinetix.com>, 26-Feb-99

+o need discussion (Howto, or maybe the User Buide) of how to
  use Aegis when you site has a mix of Unix and Wintel.
  Submitted: Paolo Supino <paolo@schema.co.il>, 4 Feb 1999

+o add chapter to User Guide, saying how to config web inter-
  face and how to use it.  Submitted: Graham Wheeler
  <gram@cdsec.com>, 27 Jan 1999

+o User Guide: big changes bouncing: how to use a branch to
  get smaller reviews and smaller diffs.  Submitted: Ralf
  Fassel <ralf@akutech.de>, 27 Jan 1999

+o note for User Guide: metrics software form
  ftp://ftp.qucis.queensu.ca/pub/software-eng/software/-
  Cmetrics/

+o The -reason option doesn't work (aerf, aeif) with with the
  empty string as the argument - well the alias doesn't like
  it actually.  Warn them about this is the man page (also
  -rea is ambig, need -reas)

+o RCS example needs to have identical hist put and hist cre-
  ate commands Check fhist and sccs as well.

+o correct documentation of file locking in UG: correct the
  example around the file locking - it gives the wrong text
  of the aede error - and probably other stuff.  also, the
  wrong person comes back from aerobics

99..88..22..  MMoorree RReeppoorrttss

+o Add a -REVerse option, so that all of the listings (ael)
  come out in the reverse order to that used at present.
  Submitted: John Darrington <johnd@ot.com.au>, 20-Jul-2001

+o Write an _a_e_r_e_p_o_r_t file to produce MS-Project views of a
  project, making sure that the states of each change are
  linked, use averages to predict any incomplete states.
  And maybe another to produce HTML pages of the same thing.
  Submitted: 15-Jan-2000

+o On the aegis.cgi web pages, link the file edit numbers to
  pages which will retrieve the historical version.  Submit-
  ted: Anoop Kulkarni <anoop@sasi.com>, 22 Dec 1999

+o When you download a .ae file via aegis.cgi, it uses a
  stupid name as the save file.  Is there a HTML header we
  can set to suggest a much better name?  Submitted: Mark
  Veltzer <mark2776@yahoo.com>, 16 Aug 2001





Peter Miller    (lib/en/howto/devel_to_do.so)        Page 41





Howto                                                  Aegis


+o Add a user_change report (just like ``ael user_changes'')
  which takes a user name, so you can get a list of changes
  by user.  Make aegis.cgi do this, too.  Submitted: Ralf
  Fassel <ralf@akutech.de>, 9 Dec 1999 Add a outstand-
  ing_changes report (just like ``ael outstanding_changes'')
  which takes a user name, so you can get a list of out-
  standing changes by user.  Make aegis.cgi do this, too.
  Submitted: Ralf Fassel <ralf@akutech.de>, 9 Dec 1999

+o Write a report which says when you have to do to get a
  change completed (needs to know arch, hence core item
  which accesses pconf).  Jerry says he has written most of
  this.  Submitted: jerry.pendergraft@endocardial.com
  3-Nov-99

+o ael change_history - write as a repot and then include
  project history for sub branches.  Don't forget the web
  reports, too.  Sumbitted:Jerry Pendergraft <jerry@endocar-
  dial.com>, 30 Aug 1999

+o ael outstanding_changes - rewite as a report and then
  include sub branches.  Don't forget the web reports, too.
  Submitted: Jerry Pendergraft <jerry@endocardial.com>, 30
  Aug 1999

+o ael project_history - rewrite as a report and then include
  parents and sub branches.  Don'f forget the web reports,
  too.  Submitted: Jerry Pendergraft <jerry@endocar-
  dial.com>, 30 Aug 1999

+o aer file_history - include parents and sub branches.
  Don't forget the web reports, too.  Submitted: Jerry Pen-
  dergraft <jerry@endocardial.com> 30 Aug 1999

+o Some kind of web report which makes ``train track'' dia-
  grams of file branching.

+o Some kind of web report which makes ``train track'' dia-
  grams of project branching.

+o multivariate linear regression: needed as a report genera-
  tor function: needed for metrics analysis

+o more blurb in the statistics web pages, so they are more
  self-explaining Submitted: Ralf Fassel <ralf@akutech.de>,
  13-Oct-98

+o Add anew report like ``ael uc'' except that it (option-
  ally) takes a user name as well, to list a particular
  user's changes.

+o File Activity Report (web) does not translate user name
  and give email link.  Should also put user name under
  change state, as in change lists.



Page 42         (lib/en/howto/devel_to_do.so)   Peter Miller





Aegis                                                  Howto


99..88..33..  CCoorree EEnnhhaanncceemmeennttss

+o It would be nice to have a way to specify a timeout for
  aegis tests.  If a single test does not finish within this
  time, it should be aborted and considered `No Result'.
  Then aet should continue with the next test (as appropri-
  ate if --perservere was given).  A `--timeout' argument to
  `aet' would do the trick, and also a project config field.
  The implementation could be interesting, since signalling
  the forked aegis child process might not be enough to stop
  all processes (process groups?).  Submitted: Ralf Fassel
  <ralf@akutech.de>, 24-Jan-2001

+o Problem with aepa that doesn't specify the default values
  for all the test features in aeca (there are three types
  in aeca and only one in aepa).  Submitted: Mark Veltzer
  <mark2776@yahoo.com>, 16 Aug 2001

+o The _a_e_d_i_s_t(1) program should send changes with no files,
  or changes in "being developed".  Submitted: Mark Veltzer
  <mark2776@yahoo.com>, 16 Aug 2001

+o Have _a_e_m merge changes properly if another changed moved
  the file in the baseline.  You need to do this across the
  board, not just in aegis/aed.c Submitted: Ralf Fassel
  <ralf@akutech.de>, 25 Feb 2000

+o Change the aeclean --list option to list files and direc-
  tories it would delete.  Submitted: Peter Nann,
  9-Jan-2000.  Submitted: Ralf Fassel <ralf@akutech.de>, 29
  Jan 1999.

+o Add progess (%) indicators (aeib was specific example, but
  there may be others _e_._g_. symlink farms and aecp, even aede
  for big changes) for use by the GUI interfaces - and maybe
  the text interface too.  Submitted: Ralf Fassel
  <ralf@akutech.de> 10 Dec 1999

+o Extend the create_symlinks_before_build functionality to
  copy, not just symlink.  Because they would edit the files
  direct, we then need an implicit aecpcorne detector.  You
  need to look for other boundary conditions this is also
  going to affect.  You need a remove_symlinks_after_build
  analogue, too.  Submitted: Darrin Thompson <dthomp-
  son@characterlink.net>, 15 Nov 1999

+o Give _a_e_r(1) access to pconf (the project config file).
  Submitted: jerry.pendergraft@endocardial.com, 3-Nov-99

+o Make the spec file use the icon in the tar file.  Submit-
  ted: Bob Barry <bobb@adsme.co.za>, 8 Nov 1999

+o os.h is a system header on some systems, so os.h has to
  move Sumbitted: Christophe Broult <broult@info.unicaen.fr>



Peter Miller    (lib/en/howto/devel_to_do.so)        Page 43





Howto                                                  Aegis


  30 Sep 1999

+o aedist -rec needs to preserve (a) copyright years, (b)
  test exemptions (subject to permissions), and (c) archi-
  tecture (if possible).  AND CHANGE NUMBER?  Submitted:
  Ewolt Wolters <ewolt@pallas-athena.com>, 27 Jul 1999

+o It seems to me that I need to specify -DELta on the aedist
  -receive.  Submitted: David Brown <aegis@davidb.org>, 14
  Feb 2001

+o Aedist to add project history to end of description when
  sending change set.  Submitted: Jerry Pendergraft
  <jerry@endocardial.com>, Dec-2000

+o can we separate change creation from other adminstrator
  permissions?  can we make "everyone" able to create
  changes?  Submitted: Ewolt Wolters <ewolt@pallas-
  athena.com>, 28 Jun 1999

+o aecp -delta-date needs to warn (error!) when you go beyond
  the valid date range for the branch.  (Otherwise can bet
  varying answers depending on when you issue the command,
  probably not what the user intended.)  Submitted: Damon
  Poole <damon@ede.com>, 17 Jun 1999

+o aenbru needs to use the project user, not the change user
  Submitted: PMiller, 23-May-99

+o aefind dumps core if there is a syntax error on the com-
  mand line (or just missing dir list?)  [default dir list
  to dot?]  Submitted: PMiller, 8 Apr 1999

+o add_path_suffix substitution Submitted: Jerry Pendergraft
  <jerry@endocardial.com>, 28 Mar 1999

+o give URL for zlib on BUILDING file, give link to zlib on
  web page.  (ditto for rx?) Also, John mentions should
  explicitly mention CPPFLAGS=-I/usr/local/include; export
  CPPFLAGS LDFLAGS=-L/usr/local/lib; export LDFLAGS in the
  configuring section.  Submitted: John Huddleston
  <jhudd@cody.itc.nrcs.usda.gov>, 19 Mar 1999

+o It would be nice if there was a way to tell
  `change_file_command' what is currently happening to the
  source files.  ``We use `change_file_command' to set up an
  RCS repository for each file in the development directory
  on each aecp and aenf, but I would like to clean up on
  aecpu and aenfu.  I could guess from the presence/absence
  of files on the kind of action, but a more cleaner way
  would be if there was $change_file_case available which
  would expand to the current operation (copy_file,
  copy_file_undo, _e_t_c).''  Submitted: Ralf Fassel
  <ralf@akutech.de>, 9 Mar 1999



Page 44         (lib/en/howto/devel_to_do.so)   Peter Miller





Aegis                                                  Howto


+o [IF there were editable file attributes] add coupling
  between files (as file attribute) this means when you
  aecp, you get a set of files (see a command to set it,
  need to carry it thu integration, etc.)  Submitted:
  PMiller, 18-Feb-99

+o The aed command does not promote aenf->aecp unless the ,D
  file does not exist.  This is annoying, should always do
  it.  (So should some other commands.)  Subject: Ralf Fas-
  sel <ralf@akutech.de>, 1 Feb 1999

+o Add a default_regression_test_exemption project attribute.
  Submitted: Ralf Fassel <ralf@akutech.de>, 31 Jan 1999,
       Jerry Pendergraft <jerry@endocardial.com>, 2 Feb
  2001.

+o Need a clean_exceptions file in the project config file
  (list of strings) so can have local RCS dirs, and do "ci
  `aegis -l cf -ter`" in the develop_end_command Submitted:
  1-Feb-99

+o aenpr -dir -keep: allow directory to already exist if has
  right owner and is empty?  Submitted: Jerry Pendergraft
  <jerry@endocardial.com>, 22 Jan 1999

+o Add a new post_merge_command so can generate summary of
  files needing editing.  Subject: Ralf Fassel
  <ralf@akutech.de>, 21 Dec 1998

+o Create a new aepatch command: ``aepatch -send'' to create
  "ordinary" OpenSource source patches, and ``aepatch
  -receive'' to turn patches into an Aegis change - and not
  necessarily only patches generated with aepatch.  Yes,
  intentionally similar to aedist.

+o integrate difference should look for missing ,D files
  (usually impossible) and re-instate them.  Submitted:
  PMiller, 22-Sep-98

+o tests 7, 20, 70 warn symlink.c: In function `main': sym-
  link.c:5: warning: return type of `main' is not `int' Sub-
  mitted: Bruce Stephen Adams <brucea@cybernet-
  ics.demon.co.uk>, 10 Sep 1998

+o change_set_env needs to set LINES and COLS

+o commands which accept -branch and/or -trunk should also
  accept -grandparent but not all do.  check.

+o Add a --no-baseline-lock option to the aeb and aecp com-
  mands.  Warn them not to in the manual pages.

+o list locks - need to spot the case where *all* of a set
  are taken (all 64k) and report sensably (not 64K lines)



Peter Miller    (lib/en/howto/devel_to_do.so)        Page 45





Howto                                                  Aegis


+o integrate_q.sh needs work 1. needs to diff 2. needs to see
  if there is a current integration 3. subjects in emails?

+o aemv does not correctly check the -to- filename.  (spe-
  cific example = file name length)

+o aefind needs a sort option

+o aefind needs the rest of the find functionality added

+o * Add a -output option to the aent command (_o_t_h_e_r_s_?)  for
  scripting support.

+o aed - when auto upgrade create to modify, clear move if
  set.

+o aede needs to make sure that the files (and directories)
  are readable (and searchable) by reviewers.

+o make aemv rename files within a change

+o aecp -anticipate

+o Make the listing more specific for aecp aecpu aenfu aentu
  aerm aermu, etc

+o add a file copy notification command to the project config
  file

+o Add pseudo change do can do many integrations at once
  (this pseudo change would be created by aeib and destroyed
  by aeipass, aeifail or aeibu).

+o Version punctuation: at the moment ypou gets dots between
  the branch numbers.  Need more flexible punctuation: espe-
  cially, want a hyohen first, then dots (sometimes).

+o * aecp -delta bug      ``I've been making good use of the
  "-delta" option of aecp lately.       But there has been a
  complication in its use.  Let's say a file      was
  aerm'ed in delta 100.  Let's further say that we are at
  delta      175 and are trying to restore the source code
  as of delta 75.       If I do a "aecp - delta 75 file.c"
  I'm told that file.c is no      longer part of the pro-
  ject.''  Should aecp -del fake aenf for deleted files in
  earlier deltas?  Submitted: markm@endo.com

+o initernationalize -interactive

+o Enhance aet to allow reviewers to run tests.

+o check library state files on project creation      ``I was
  creating a new release from a large project. After copying
  the      baseline and creating hundreds of history files



Page 46         (lib/en/howto/devel_to_do.so)   Peter Miller





Aegis                                                  Howto


  the aenrls failed      because the library dir I specified
  wasn't writeable by aegis and no      state file was cre-
  ated. Couldn't this be checked first?''  Submitted: Lloyd
  Fischer <lloyd@dvcorp.com>

+o Add precedence constraints: a list of prerequisite
  changes, which must all be in the ``completed'' state
  before the change may end development.  Submitted: Chris-
  tian F. Goetze <c-goetze@u-aizu.ac.jp>

+o If there is a read error when reading the template source
  file during aent, get a stupid error within error message,
  and never tells you about the file

99..88..33..11..  MMoorree OO((11)) SSccaallaabbiilliittyy

+o Need to suppliment the {project,change}_file_find and
  {project,change}_file_nth interfaces with {pro-
  ject,change}_file_name_nth interfaces.  Then, use them as
  often as possible.

+o Need the fstate file to have a manifest field; access this
  for file names.  Then, store each file into in a separate
  file; only access this file is file state is requied.

+o The presence or absence of the manifest field in the top-
  level fstate file tells you if the old or new file state
  usage is present.

99..88..44..  GGUUII

+o tkaeca barfs when there are no changes on the branch.
  should be more graceful.  Submitted: Ewolt Wolters
  <ewolt@pallas-athena.com>, 11 Aug 1999

+o using tkaegis: project > branch > role > integrate, a win-
  dow pops up "Error in tcl script, Error: invalid command
  name ".mbar.review.menu"".  Submitted: Ewolt Wolters
  <ewolt@pallas-athena.com> 9 Aug 1999

+o user pasted in text (including back slash) into aeifail
  edit window.  which was accepted, but broke change state
  (illegal escape sequence).  Submitted: Michael McCarty
  <mmccarty@xinetix.com>, 10 May 1999

+o A new ${architecture_list} substitution to give all archi-
  tectures in a command.  Submitted: jerry.pendergraft@endo-
  cardial.com, 31 Mar 1999

+o have aedist -rec accept a -delta option, so you can tell
  it where to apply from.  Anticipated use is ``-delta 0''
  meaning start of branch.  (also a -reg option).  Submit-
  ted: PMiller, 22-mar-99




Peter Miller    (lib/en/howto/devel_to_do.so)        Page 47





Howto                                                  Aegis


99..88..55..  RReelleeaassee aanndd BBuuiilldd aanndd IInnssttaallll

+o add debian .deb file, add notification to <cd@debian.org>
  for new releases.  Submitted: PMiller, 22-Jun-99

+o building documentation needs to talk about libz some more.
  particularly, you either need it on ROOT's LD_LIBRARY_PATH
  or you need to static link it.  Submitted: Ralf Fassel
  <ralf@akutech.de> 5-apr-99

+o have configure script whine about missing libz Submitted:
  PMiller, 7 apr 99

+o have configure script whine about missing regcomp Submit-
  ted: PMiller, 7 apr 99

+o Sample documentation needs to make the _g_r_o_u_p thing obvi-
  ous.  And also the umask at aenpr time!  Submitted: Alan
  Zimmerman <alanz@electrosolv.co.za>, 5 Apr 1999

+o genertated makefile CC=cc needs to quote cc incase has
  spaces Submitted: Aaron Johnson <adj@ccltd.com>, 31 Mar
  1999

+o The BUILDING file needs to mention that you should install
  zlib with --prefix=/usr because many systems think
  /usr/local/lib "insecure directory".  Submitted: Fabien
  Campagne <campagne@Inka.MSSM.EDU>, 26 Mar 1999

+o I suggest to move aegis.cgi in a different package (aegis-
  www ?) that requires apache.       Requires: apache Also
  need to note that zlib is required (or does it work this
  out itself?)       Requires: zlib (I don't see a way to
  say BuildRequires: zlib-devel) Submitted: Walter Franzini
  <walter@sys-net.it>, 18 Mar 1999

+o add piece to BUILDING file saying to get Apache first.
  Submitted: Graham Wheeler <gram@cdsec.com> 27 Jan 1999

99..88..66..  DDaattaabbaassee

+o Should the Aegis database be replaced by XML?  (This would
  have _h_u_g_e backwards compatability issues.)  Maybe we need
  a way to project the Aegis database into XML?  Submitted:
  Mark Veltzer <mark2776@yahoo.com>, 16 Aug 2001

+o Write an ODBC interface to the database?  Submitted: P.
  Miller, 16 Aug 2001

+o Does it make sense to have an NNTP interface?  Would it be
  any use?  Submitted: P. Miller, 16 Aug 2001

+o Write an interface so that Aegis looks just like a remote
  CVS server, accessed using the normal CVS clients.  Of



Page 48         (lib/en/howto/devel_to_do.so)   Peter Miller





Aegis                                                  Howto


  course, you would have to do the aede on the Unix server.
  Submitted: P. Miller, 16 Aug 2001























































Peter Miller       (lib/en/howto/main.ms)            Page 49





Howto                                                  Aegis


  .
























































Page 50            (lib/en/howto/main.ms)       Peter Miller





Aegis                                                  Howto


  .
























































Peter Miller       (lib/en/howto/main.ms)             Page 1





Aegis                                                  Howto


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


1. Introduction . . . . . . . . . . . . . . . . . . . . . .   3
1.1. Assumed Knowledge  . . . . . . . . . . . . . . . . . .   3
1.2. Howto Install Aegis  . . . . . . . . . . . . . . . . .   3
1.3. Howto Contribute . . . . . . . . . . . . . . . . . . .   3
2. Cheat Sheet  . . . . . . . . . . . . . . . . . . . . . .   4
2.1. Common Commands  . . . . . . . . . . . . . . . . . . .   4
2.2. Developer Commands . . . . . . . . . . . . . . . . . .   5
2.3. Reviewer Commands  . . . . . . . . . . . . . . . . . .   6
2.4. Integrator Commands  . . . . . . . . . . . . . . . . .   6
2.5. Project Administrator Commands . . . . . . . . . . . .   6
3. How to Start Using Aegis . . . . . . . . . . . . . . . .   8
3.1. First, Create The Project  . . . . . . . . . . . . . .   8
3.2. Second, Use a Template Project . . . . . . . . . . . .   8
3.3. Second, Copy a Template Project  . . . . . . . . . . .   8
4. How to Create a New Project  . . . . . . . . . . . . . .  10
4.1. Single User Project  . . . . . . . . . . . . . . . . .  10
4.2. Two User Project . . . . . . . . . . . . . . . . . . .  11
4.3. Multi User Project . . . . . . . . . . . . . . . . . .  12
4.4. Warning  . . . . . . . . . . . . . . . . . . . . . . .  12
4.4.1. Creating Projects  . . . . . . . . . . . . . . . . .  13
4.4.2. Web Visibility . . . . . . . . . . . . . . . . . . .  13
4.5. Changing The Project Owner . . . . . . . . . . . . . .  13
5. How to Move a New Project  . . . . . . . . . . . . . . .  16
5.1. From within Aegis  . . . . . . . . . . . . . . . . . .  16
5.2. From outside Aegis . . . . . . . . . . . . . . . . . .  16
6. Working in Teams . . . . . . . . . . . . . . . . . . . .  18
6.1. Local  . . . . . . . . . . . . . . . . . . . . . . . .  18
6.1.1. Single User, Single Machine  . . . . . . . . . . . .  18
6.1.2. Multi User, Single Machine . . . . . . . . . . . . .  18
6.1.3. Multi User, Multi Machine  . . . . . . . . . . . . .  18
6.1.3.1. General Requirements . . . . . . . . . . . . . . .  19
6.1.3.2. Aegis-specific Requirements  . . . . . . . . . . .  20
6.2. Distributed  . . . . . . . . . . . . . . . . . . . . .  20
6.2.1. Multiple Single-User Sites . . . . . . . . . . . . .  21
6.2.2. Multiple Multi-User Sites  . . . . . . . . . . . . .  21
6.2.3. Telecommuting  . . . . . . . . . . . . . . . . . . .  22
6.2.3.1. Office to Developer  . . . . . . . . . . . . . . .  22
6.2.3.2. Developer to Office  . . . . . . . . . . . . . . .  22
7. How to use Aegis with Python . . . . . . . . . . . . . .  24
7.1. Handling Aegis search paths  . . . . . . . . . . . . .  24
7.1.1. The Aegis model vs. the Python model . . . . . . . .  24
7.1.2. The solution . . . . . . . . . . . . . . . . . . . .  24
7.1.3. Why setting PYTHONPATH to the Aegis search path
  will not work  . . . . . . . . . . . . . . . . . . . .  25
7.2. The build step . . . . . . . . . . . . . . . . . . . .  26
7.3. Testing  . . . . . . . . . . . . . . . . . . . . . . .  27
7.4. Running your programs  . . . . . . . . . . . . . . . .  28
8. Howto End A Branch . . . . . . . . . . . . . . . . . . .  30
9. Becoming an Aegis Developer  . . . . . . . . . . . . . .  32
9.1. Required Software  . . . . . . . . . . . . . . . . . .  32
9.2. Create The Aegis Project . . . . . . . . . . . . . . .  33



Peter Miller       (lib/en/howto/main.ms)          Page 1001





Howto                                                  Aegis


9.3. The Download . . . . . . . . . . . . . . . . . . . . .  34
9.4. The Bleeding Edge  . . . . . . . . . . . . . . . . . .  36
9.5. Undiscovered Country . . . . . . . . . . . . . . . . .  38
9.6. Sending Changes  . . . . . . . . . . . . . . . . . . .  38
9.7. Guidelines . . . . . . . . . . . . . . . . . . . . . .  38
9.7.1. What You Can Do  . . . . . . . . . . . . . . . . . .  38
9.7.2. What You Can't Do  . . . . . . . . . . . . . . . . .  39
9.8. The To-Do List . . . . . . . . . . . . . . . . . . . .  39
9.8.1. Documentation  . . . . . . . . . . . . . . . . . . .  39
9.8.2. More Reports . . . . . . . . . . . . . . . . . . . .  41
9.8.3. Core Enhancements  . . . . . . . . . . . . . . . . .  43
9.8.3.1. More O(1) Scalability  . . . . . . . . . . . . . .  47
9.8.4. GUI  . . . . . . . . . . . . . . . . . . . . . . . .  47
9.8.5. Release and Build and Install  . . . . . . . . . . .  48
9.8.6. Database . . . . . . . . . . . . . . . . . . . . . .  48










































Page 1002                    ()                 Peter Miller


