.\" .\" aegis - project change supervisor .\" Copyright (C) 1991-1999, 2002, 2005-2008, 2010, 2012 Peter Miller .\" .\" 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 3 of the License, or .\" (at your option) any later version. .\" .\" This program is distributed in the hope that it will be useful, .\" but WITHOUT ANY WARRANTY; without even the implied warranty of .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. 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, see . .\" .bp .nh 2 "The Administrator" .LP The previous discussion of developers, reviewers and integrators has covered many aspects of the production of software using Aegis. The administrator has responsibility for everything they don't, but there is very little left. .LP These responsibilities include: .LP \(bu access control: The administrator adds and removes all categories of user, including administrators. This is on a per\[hy]project basis, and has nothing to do with .UX user administration. This simply nominates which users may do what. .LP \(bu change creation: The administrator adds (and sometimes removes) changes to the system. At later stages, developers may alter some attributes of the change, such as the description, to say what they fixed. .LP \(bu project creation: Aegis does not limit who may create projects, but when a project is created the user who created the project is set to be the administrator of that project. .LP All of these things will be examined .nh 3 "Before You Start" .LP Have you configured your account to use Aegis? See the \fIUser Setup\fP section of the \fITips and Traps\fP chapter for how to do this. .nh 3 "The First Change" .LP Many things need to happen before development can begin on the first change; the project must be created, the staff but be given access permissions, the branches created, and the change must be created. .E( alex% \f(CBaenpr example \-dir /projects/example \-version \-\fP aegis: project "example": project directory "/projects/example" aegis: project "example": created alex% .E) .LP Once the project has been created, the project attributes are set. Alex will set the desired project attributes using the .B \-Edit option of the .B aepa command. This will invoke an editor (\fIvi\fP(1) by default) to edit the project attributes. Alex edits them to look like this: .E( description = "Aegis Documentation Example Project"; developer_may_review = false; developer_may_integrate = false; reviewer_may_integrate = false; .E) The project attributes are set as follows: .E( alex% \f(CBaepa \-edit \-p example\fP \fI\&...edit as above...\fP aegis: project "example.1.0": attributes changed alex% \f(CBael p\fP List of Projects Project Directory Description \-\-\-\-\-\-\- \-\-\-\-\-\-\-\-\-\-\- \-\-\-\-\-\-\-\-\-\-\-\-\- example /projects/example Aegis Documentation Example Project alex% .E) The various staff must be added to the project. Developers are the only staff who may actually edit files. .E( alex% \f(CBaend pat jan sam \-p example\fP aegis: project "example": user "pat" is now a developer aegis: project "example": user "jan" is now a developer aegis: project "example": user "sam" is now a developer alex% .E) Reviewers may veto a change. There may be overlap between the various categories, as show here for Jan: .E( alex% \f(CBaenrv robyn jan \-p example\fP aegis: project "example": user "robyn" is now a reviewer aegis: project "example": user "jan" is now a reviewer alex% .E) The next role we need to fill is an integrator. .E( alex% \f(CBaeni isa \-p example\fP aegis: project "example": user "isa" is now an integrator alex% .E) Once the staff have been given access, it is time to create the working branch. Branches inherit their attributes and staff lists from their parent branches when they are first created, which is why we set all that stuff first. .E( alex% \f(CBaegis \-nbr \-p example 1\fP aegis: project "example.1": created alex% \f(CBaegis \-nbr \-p example.1 0\fP aegis: project "example.1.0": created alex% .E) This is for versioning; see the \fIBranching\fP chapter for more information. For the moment, we will simply work on branch 1.0. Notice how the branches appear as projects in the project listing; in general branches can be used interchangeably with projects. .E( alex% \f(CBael p\fP List of Projects Project Directory Description \-\-\-\-\-\-\- \-\-\-\-\-\-\-\-\-\-\- \-\-\-\-\-\-\-\-\-\-\-\-\- example /projects/example Aegis Documentation Example Project example.1 /projects/example/ Aegis Documentation Example branch.1 Project, branch.1. example.1.0 /projects/example/ Aegis Documentation Example branch.1/branch.0 Project, branch.1.0. alex% .E) Once the working branch has been created, Alex creates the first change. The .B \-Edit option of the .B aenc command is used, to create the attributes of the change. They are edited to look like this: .E( brief_description = "Create initial skeleton."; description = "A simple calculator using native \e floating point precision. \e The four basic arithmetic operators to be provided, \e using conventional infix notation. \e Parentheses and negation also required."; cause = internal_enhancement; .E) The change is created as follows: .E( alex% \f(CBaenc \-edit \-p example.1.0\fP \fI\&...edit as above...\fP aegis: project "example.1.0": change 10: created alex% .E) Notice that the first change number is \[lq]10\[rq]. This is done so that changes 1 to 9 could be used as bug\[hy]fix branches at some future time. See the \fIBranching\fP chapter for more information. You can over\[hy]ride this is you need to. .LP The above was written almost a decade ago. There is a newer command, \fItkaenc\fP, which uses a GUI and is much easier to use, with a much less fiddly interface. You may want to try that command, instead, for most routine change creation. .LP At this point, Alex walks down the hall to Pat's office, to ask Pat to develop the first change. Pat has had some practice using Aegis, and can be relied on to do the rest of the project configuration speedily. .nh 3 "The Second Change" .LP Some time later, Alex patiently sits through the whining and grumbling of an especially pedantic user. The following change description is duly entered: .E( brief_description = "file names on command line"; description = "Optional input and output files may be \e specified on the command line."; cause = internal_bug; .E) .LP The pedantic user wanted to be able to name files on the command line, rather than use I/O redirection. Also, having a bug in this example is useful. The change is created as follows: .E( alex% \f(CBaenc \-edit \-p example.1.0\fP \fI\&...edit as above...\fP aegis: project "example.1.0": change 11: created alex% .E) At some point a developer will notice this change and start work on it. .nh 3 "The Third Change" .LP Other features are required for the calculator, and also for this example. The third change adds exponentiation to the calculator, and is described as follows: .E( brief_description = "add powers"; description = "Enhance the grammar to allow exponentiation. \e No error checking required."; cause = internal_enhancement; .E) .LP The change is created as follows: .E( alex% \f(CBaenc \-edit \-p example.1.0\fP \fI\&...edit as above...\fP aegis: project "example.1.0": change 12: created alex% .E) At some point a developer will notice, and this change will be worked on. .nh 3 "The Fourth Change" .LP A fourth change, this time adding variables to the calculator is added. .E( brief_description = "add variables"; description = "Enhance the grammar to allow variables. \e Only single letter variable names are required."; cause = internal_enhancement; .E) .LP The change is created as follows: .E( alex% \f(CBaenc \-edit \-p example.1.0\fP \fI\&...edit as above...\fP aegis: project "example.1.0": change 13: created alex% .E) At some point a developer will notice, and this change will be worked on. .nh 3 "Administrator Command Summary" .LP Only a few of the Aegis commands available to administrators have been used in this example. The following table lists the Aegis commands most useful to administrators. .sp .TS center,tab(;); l l. Command;Description _ aeca;edit Change Attributes ael;List Stuff aena;New Administrator aenc;New Change aencu;New Change Undo aend;New Developer aeni;New Integrator aenpr;New Project aenrv;New Reviewer aepa;edit Project Attributes aera;Remove Administrator aerd;Remove Developer aeri;Remove Integrator aermpr;Remove Project aerrv;Remove Reviewer .TE .LP You will want to read the manual entries for all of these commands. Note that all Aegis commands have a .I \-Help option, which will give a result very similar to the corresponding .I man (1) output. Most Aegis commands also have a .I \-List option, which usually lists interesting context sensitive information. .\" vim: set ts=8 sw=4 et :