Chapter 5. How to Create a New Project

Table of Contents

1. Single User Project
2. Two User Project
3. Multi User Project
4. Project Visibility
4.1. Creating Projects
4.2. Web Visibility
5. Changing The Project Owner

Before you can do anything else with Aegis, you need a project to do it to. The advantage of this is that each project 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.

1. Single User Project

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.

[Caution]Caution

Don't do anything yet! Read through all of the steps first.

  • You may want to read the aenpr(1) man page for more information.

  • The command “aenpr name -version -” will create the project with no branches. This will automatically make you (that is, the executing user) the project administrator and the project owner. The umask is remembered, too.

  • The root of the project directory will be in your home directory, named after the project name. If you want something else, use the aenpr --directory option.

  • 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.)

  • The umask at the time of execution determines the group access to the project. Even if you usually work with a restrictive umask, set it to the right one for the project before running this aenpr command.

  • For additional security, it is often very 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 initial project creation commands; once completed no one will ever login to this account again.

  • Add the staff to the project: the “aena 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.

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

  • Add the rest of the staff: the “aend your-login” command makes you a developer, the “aenrv your-login” command makes you a reviewer and the “aeni your-login” command makes you an integrator.

  • You need to edit the project attributes next. The “aepa -edit” command does this. You will be placed into a text editor, and will see something similar to this:

    description = "The \"example\" 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;
    
    [Note]Note

    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 and semicolon.

  • 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 “aenbr name 1” followed by followed by “aenbr name.1 0” will give you a branch called name.1.0 for use wherever Aegis wants a project name. (See the Branching chapter of the User Guide for more information.)

2. Two User Project

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

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. Remember: each branch inherited its attributes when it was created - you need to edit the ancestor branches' project attributes too.

3. Multi User Project

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, not to be authorized as reviewers.

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

4. Project Visibility

The /usr/local/com/aegis/state file contains pointers to "system" projects. Pointers. Users may add their own project pointers (to their own projects) by putting a search path into the AEGIS_PATH environment variable. The system part is always automatically appended by Aegis. The default, already set by the /usr/local/lib/­aegis/cshrc file, is $HOME/lib/aegis.

[Warning]Warning

Do not create this directory, Aegis is finicky and wants to do this itself.

Where projects reside is completely flexible, be they system projects or user projects. They are not kept under the /usr/local/com/aegis directory, this directory only contains pointers.

4.1. Creating Projects

When you create a new project, the first element of the AEGIS_PATH is used as the place to remember the project pointer. 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 “unset AEGIS_PATH” immediately before using the “aenpr” command, or use the “--library /usr/local/com/aegis” option of the aenpr command.

4.2. Web Visibility

If you have a Web server, you make like to install the Aegis web interface. You do this by copying the aeget program from /opt/aegis/bin/aeget into your web server's cgi-bin directory. There is a aeget.instal helper script, if you don't know where your web server's cgi-bin directory is.

You may prefer to use a symbolic link, as this will be more stable across Aegis upgrades. However, this requires a corresponding follow-symlinks setting in your web server's configuration file. (Use the aeget.instal -s option.)

If you have a Web server, and aeget was installed, you can use a wrapper script to set the AEGIS_PATH environment variable, if you want it to be able to see more projects than just the global projects.

5. Changing The Project Owner

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 root 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 somewhere 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 directory which appears in the “ael projects” listing. This isn't the trunk baseline, but the directory above it (you will see info, history and baseline sub-directories).

  4. Use the command

    chown -R username .
    

    to change the ownership of this directory, and all files and sub-directories below it. Insert the username of the account you created in step 2. (You need the dot 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.