Provided by: aegis_4.24.3-3_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:

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

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

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

        o 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.24.3.D001
        Copyright (C) 1991, 1992, 1993, 1994, 1995, 1996, 1997, 1998, 1999,
        2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 Peter
        Miller

        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/