Provided by: aegis_4.21-2_i386 bug

NAME

       aegis -Integrate_Pass - pass a change integration

SYNOPSIS

       aegis -Integrate_Pass [ option...  ]
       aegis -Integrate_Pass -List [ option...  ]
       aegis -Integrate_Pass -Help

DESCRIPTION

       The aegis -Integrate_Pass command is used to notify aegis that a change
       has passed integration.  The change is advanced from the being
       integrated state to the completed state.  boxwid = 1 down box "being"
       "integrated" arrow " integrate" ljust " pass" ljust box "completed"

       This command updates the file histories, so that future aecp(1)
       commands may extract previous file versions from history, and so that
       future aed(1) commands may merge out-of-date files.  The history is
       updated using the history_create_command and history_put_command fields
       of the project configuration file (see aepconf(5) for more
       information).  The integrate pass will abort with an error if one of
       these history commands should fail, e.g. by running out of disk space.
       If this should happen, the change will remain in the being integrated
       state, and the integration directory is unaltered.

       Once the history has been updated, the integration directory is renamed
       as the baseline directory, and the old baseline directory is deleted.

       Once integrate pass is complete the change is no longer assigned to the
       current user.

   History Tools Modify Files
       Many history tools (e.g. RCS and SCCS) can modify the contents of the
       file when it is committed.  This usually requires the use of specific
       ‘‘keyword’’ strings, and there are usually options to turn this
       behavior off, but users familiar with version control tools (as opposed
       to configuration management systems) will often use these features.
       The problem is that if the commit changes the file, the source file in
       the repository now no longer matches the object file in the repository.
       I.e.  the history tool has compromised the referential integrity of the
       repository.  By default, a fatal error is emitted if the file is
       changed by the check-in, however this can be modified to a be warning
       or even ignored completely; see the history_put_trashes_file field of
       aepconf(5) for more information.

   File Modification Times
       The modification times of all files modified since the beginning of
       integration (see aeib(1) for more information) are updated to be since
       the beginning of integrate pass.  The order of modification times will
       be preserved, however the time range will be compressed to the greatest
       extent possible.  This ensures that subsequent development builds will
       notice that baseline files have changed.

       Note that if there are many new files with all different timestamps in
       the integration directory, and if the number of files with different
       timestamps exceeds the number of seconds since the start of the
       integrate-pass command, Aegis may have to set file modification times
       into the future.

       The build_time_adjust field of the project config file controls Aegis’
       behavior in this case.  (See aepconf(5) for more information.)  There
       are three settings:

       adjust_and_sleep
               This setting, which is the default, causes Aegis to sleep until
               the file modification times would no longer be in the future.
               This avoids both development build problems and integration
               build problems, both of which which can arise as a result
               "interesting" file modification times.

       adjust_only
               Aegis will issue a warning that the file modification times
               extend into the future, but will not sleep.  This may cause
               integration build problems, particularly if you are using
               aeintegratq(1).  Development builds may perform redundant
               builds, however aet -reg should not produce false negatives.

       dont_adjust
               This is highly inadvisable.  It is provided solely for some
               very rare circumstances.  This setting causes Aegis not to
               adjust the file modification times at all.  This can have very
               unhappy side-effects, especially of the integration build was
               before one or more development builds; the commonest symptom
               being that development builds do not always cause a relink of
               the necessary executables, and aet -reg may give false
               negatives.  It is strongly recommended that you do not use this
               setting.

       If you use cook(1), see the time-adjust-back flag for how to compress
       the time range even further.  This usually makes the sleep (or the
       warning period) significantly shorter.

   Notification
       On successful completion of this command, after the directory rename
       has ocurred and after the database has been updated, the integration_
       pass_notify_command field of the project attributes is run, if set.
       See aepattr(5) and aepa(1) for more information.  This command is run
       as the project owner.

       Some compilers bury absolute path names into object files and
       executables.  The renaming of the integration directory to become the
       new baseline breaks these paths.  The above command is passed an
       environment variable called AEGIS_INTEGRATION_DIRECTORY so that the
       appropriate symlink may be placed, if desired.

       Other commands run by this command include the history_create_command,
       history_put_command and history_query_command fields of the project
       config file.  See aepconf(5) for more information.

THE BASELINE LOCK

       The baseline lock is used to ensure that the baseline remains in a
       consistent state for the duration of commands which need to read the
       contents of files in the baseline.

       The commands which require the baseline to be consistent (these include
       the aeb(1), aecp(1) and aed(1) commands) take a baseline read lock.
       This is a non-exclusive lock, so the concurrent development of changes
       is not hindered.

       The command which modifies the baseline, aeipass(1), takes a baseline
       write lock.  This is an exclusive lock, forcing aeipass(1) to block
       until there are no active baseline read locks.

       It is possible that one of the above development commands will block
       until an in-progress aegis -Integrate_PASS completes.  This is usually
       of short duration while the project history is updated.  The delay is
       essential so that these commands receive a consistent view of the
       baseline.  No other integration command will cause the above
       development commands to block.

       When aegis’ branch functionality is in use, a read (non-exclusive) lock
       is taken on the branch baseline and also each of the "parent"
       baselines.  However, a baseline write (exclusive) lock is only taken on
       the branch baseline; the "parent" baselines are only read (non-
       exclusive) locked.

   The History Lock
       Where a project has a number of branches active simultaneously, it is
       possible for independent integrate pass commands for different branches
       to be issued very close together.  The is an exclusive history lock
       taken by integrate pass to ensure that only one branch is updating the
       file history at a time, thus preventing history file corruption.

TEST CORRELATIONS

       The ‘‘aegis -Test -SUGgest’’ command may be used to have aegis suggest
       suitable regression tests for your change, based on the source files in
       your change.  This automatically focuses testing effort to relevant
       tests, reducing the number of regression tests necessary to be
       confident that you have not introduced a bug.

       The test correlations are generated by the ‘‘aegis -Integrate_Pass’’
       command, which associates each test in the change with each source file
       in the change.  Thus, each source file accumulates a list of tests
       which have been associated with it in the past.  This is not as exact
       as code coverage analysis, but is a reasonable approximation in
       practice.

       The aecp(1) and aenf(1) commands are used to associate files with a
       change.  While they do not actively perform the association, these are
       the files used by aeipass(1) and aet(1) to determine which source files
       are associated with which tests.

   Test Correlation Accuracy
       Assuming that the testing correlations are accurate and that the tests
       are evenly distributed across the function space, there will be a less
       than 1/number chance that a relevant test has not been run by the
       ‘‘aegis -Test -SUGgest number’’ command.  A small amount of noise is
       added to the test weighting, so that unexpected things are sometimes
       tested, and the same tests are not run every time.

       Test correlation accuracy can be improved by ensuring that:

       · Each change should be strongly focused, with no gratuitous file
         inclusions.  This avoids spurious correlations.

       · Each item of new functionality should be added in an individual
         change, rather than several together.  This strongly correlates tests
         with functionality.

       · Each bug should be fixed in an individual change, rather than several
         together.  This strongly correlates tests with functionality.

       · Test correlations will be lost if files are moved.  This is because
         correlations are by name.

       The best way for tests to correlate accurately with source files is
       when a change contains a test and exactly those files relating to the
       functionality under test.  Too many spurious files will weaken the
       usefulness of the testing correlations.

METRICS

       Aegis is capable of recording metrics as part of the file attributes of
       a change.  This allows various properties of files to be recorded for
       later trend analysis, or other uses.

       The specific metrics are not dictated by Aegis.  It is expected that
       the integration build will create a metrics file for each of the source
       files the change.  These metrics files must be in the format specified
       by aemetrics(5).

       The name of the metrics file defaults to ‘‘filename,S’’, however it may
       be varied, by setting the metrics_filename_pattern field of the project
       config file.  See aepconf(5) for more information.

       If such a metrics file exists, for each source file in a change, it
       will be read and remembered at integrate pass time.  If it does not
       exist, Aegis assumes there are no relevant metrics for that file, and
       proceeds silently; it is not an error.

OPTIONS

       The following options are understood:

       -Change number
               This option may be used to specify a particular change within a
               project.  See aegis(1) for a complete description of this
               option.

       -Help
               This option may be used to obtain more information about how to
               use the aegis program.

       -List
               This option may be used to obtain a list of suitable subjects
               for this command.  The list may be more general than expected.

       -Not_Logging
               This option may be used to disable the automatic logging of
               output and errors to a file.  This is often useful when several
               aegis commands are combined in a shell script.

       -Project name
               This option may be used to select the project of interest.
               When no -Project option is specified, the AEGIS_PROJECT
               environment variable is consulted.  If that does not exist, the
               user’s $HOME/.aegisrc file is examined for a default project
               field (see aeuconf(5) for more information).  If that does not
               exist, when the user is only working on changes within a single
               project, the project name defaults to that project.  Otherwise,
               it is an error.

       -REAson text
               This option may be used to attach a comment to the change
               history generated by this command.  You will need to use quotes
               to insulate the spaces from the shell.

       -TERse
               This option may be used to cause listings to produce the bare
               minimum of information.  It is usually useful for shell
               scripts.

       -Verbose
               This option may be used to cause aegis to produce more output.
               By default aegis only produces output on errors.  When used
               with the -List option this option causes column headings to be
               added.

       -Wait   This option may be used to require Aegis commands to wait for
               access locks, if they cannot be obtained immediately.  Defaults
               to the user’s lock_wait_preference if not specified, see
               aeuconf(5) for more information.

       -No_Wait
               This option may be used to require Aegis commands to emit a
               fatal error if access locks cannot be obtained immediately.
               Defaults to the user’s lock_wait_preference if not specified,
               see aeuconf(5) for more information.

       See also aegis(1) for options common to all aegis commands.

       All options may be abbreviated; the abbreviation is documented as the
       upper case letters, all lower case letters and underscores (_) are
       optional.  You must use consecutive sequences of optional letters.

       All options are case insensitive, you may type them in upper case or
       lower case or a combination of both, case is not important.

       For example: the arguments "-project, "-PROJ" and "-p" are all
       interpreted to mean the -Project option.  The argument "-prj" will not
       be understood, because consecutive optional characters were not
       supplied.

       Options and other command line arguments may be mixed arbitrarily on
       the command line, after the function selectors.

       The GNU long option names are understood.  Since all option names for
       aegis are long, this means ignoring the extra leading ’-’.  The
       "--option=value" convention is also understood.

RECOMMENDED ALIAS

       The recommended alias for this command is
       csh%    alias aeipass ’aegis -ipass \!* -v’
       sh$     aeipass(){aegis -ipass "$@" -v}

ERRORS

       It is an error if the change is not assigned to the current user.
       It is an error if The change is not in the being integrated state.
       It is an error if there has been no successful aegis -Build command
       for the integration.
       It is an error if there has been no successful aegis -Test command
       for the integration.
       It is an error if there has been no successful aegis -Test -BaseLine
       command for the integration.

EXIT STATUS

       The aegis command will exit with a status of 1 on any error.  The aegis
       command will only exit with a status of 0 if there are no errors.

ENVIRONMENT VARIABLES

       See aegis(1) for a list of environment variables which may affect this
       command.  See aepconf(5) for the project configuration file’s project_
       specific field for how to set environment variables for all commands
       executed by Aegis.

SEE ALSO

       aeib(1) begin integration of a change

       aeifail(1)
               fail integration of a change

       aemeasure(1)
               simple file metrics

       aemetrics(5)
               metrics values file format

       aeuconf(5)
               user configuration file format

COPYRIGHT

       aegis version 4.21
       Copyright (C) 1991, 1992, 1993, 1994, 1995, 1996, 1997, 1998, 1999,
       2000, 2001, 2002, 2003, 2004, 2005 Peter Miller; All rights reserved.

       The aegis program comes with ABSOLUTELY NO WARRANTY; for details use
       the ’aegis -VERSion License’ command.  This is free software and you
       are welcome to redistribute it under certain conditions; for details
       use the ’aegis -VERSion License’ command.

AUTHOR

       Peter Miller   E-Mail:   millerp@canb.auug.org.au
       /\/\*             WWW:   http://www.canb.auug.org.au/~millerp/