Configuration Management (CM) Guide

It is a recommended best practice to employ change control on your project configuration files.

There are 2 primary reasons for using configuration management.

To impose strict change control on your project configuration files, and enable the ability to revert to a previous known good configuration.
To quickly and efficiently model your production configuration in a test setup. Refer to Use CM in a Test Instance below.

An open source utility called "Fossil" has been integrated with the ncmgr command as a set of subcommands under the "cm" option. Keep in mind that as you are using the ncmgr utility for any capacity, you will need to first set the default queue name if it is not "vnc". This can be accomplished by one of 2 ways:

Set the NC_QUEUE variable:

setenv NC_QUEUE queue_name
ncmgr cm <cm_command>

Use either one of the -q or -queue options to ncmgr.
```
ncmgr cm -q queue_name <cm_command>
```

There is a minimum set of files in the Server Working Directory (SWD) of your project that are best under CM control. These include, but are not limited to the following files:

taskers.tcl
policy.tcl
equiv.tcl
exclude.tcl
resources.tcl
security.tcl
setup.tcl

Following this initial setup, additional files (or entire directories within the SWD, such as the config directory) can be added using the command:

ncmgr cm add<filename>

Functions Available

add: Add a file to the repository and commit the change immediately. The repository must be previously initialized.
cat: Show the displayable contents of a file.
commit: Commit any outstanding file changes to the repository.
del: Delete a file from the repository. The file in the working directory is unaffected.
diff: Display any local changes that have been made to a file or files.
help: Display help text.
init: Initialize the CM repository for use with an Altair Accelerator project. This creates the repository (*.cmrepo) file in the NC_CONFIG_DIR directory (usually $VOVDIR/local/vncConfig/)
ls: List project files that are currently under change control (use -v to also show file status).
open: Open a repository and check out the files to the current working directory.
quickstart: Initialize the repository and add the most common files (as listed in the previous section). This is typically done on a single queue to act as master.
revert: Roll back any existing local changes to a file or files.
status: Show the status of the local checkout set in the working directory.
timeline: Show the timeline of changes to the repository.
undo: Undo previous update or revert action.
update: Update local file(s) with the latest from the repository, or a specific revision.

CM Command Usage


vncmgr: Usage Message

DESCRIPTION:
      "ncmgr cm ..." is the utility for performing configuration management
      actions.  To use configuration management, you need to be in the
      server-working directory (SWD) of the current project.
      To work with a non-default queue name, either set the NC_QUEUE
      environment variable to the target queue name or use either of the
      "-queue" or "-q" arguments.

USAGE:
        % ncmgr cm [-queue|-q QUEUE] <ACTION> [ARGUMENTS]

ACTIONS: (arguments are either <>=required or []=optional)

        add       <FILE>  -- Add a file to the repository.
        cat       [-r REVISION] <FILE>
                          -- Display contents of a file.
        commit    <-m "MSG"> [FILE]
                          -- Commit changes to the repository.
        del       <FILE>  -- Delete a file from the repository.
        diff      [-r REVISION] <FILE>
                          -- Display local changes.
        help              -- Display this help.
        init              -- Initialize repository.
        ls        [-v] <FILE>
                          -- List managed files.
                             Use -v to also show file status.
        open              -- Open a repository and check out files to the
                             current working directory.
        quickstart        -- Initialize repository and add most common files.
                             Typically done on a single queue to act as
                             master.
        revert    [FILE]  -- Roll back local changes.
        status            -- Show status of the local checkout.
        timeline  [FILE]  -- Show timeline of changes.
        undo      [FILE]  -- Undo previous update or revert action.
        update    [-r REVISION] [FILE]
                          -- Update local file(s) with the latest from the
                             repository, or a specific revision.

      NOTE: For configuration management, you must be in the server working
      directory (SWD) of the project being managed.
      If you are unsure of this, please run the following commands:
      % vovproject enable <project_name>
      % cd `vovserverdir -p .`

EXAMPLES
        % ncmgr cm quickstart
        % ncmgr cm init
        % ncmgr cm add policy.tcl
        % ncmgr cm commit -m "Added new tasker." taskers.tcl
        % ncmgr cm add scripts/myscript.tcl
        % ncmgr cm commit -m "Added custom script to CM"
                    scripts/myscript.tcl

Use CM in a Test Instance

Implementing a configuration management process for your testing workflow can save a lot of time and hassle in keeping configuration files synchronized.

An example follows with a production instance called "vnc" and a test instance called "vnctest". For purposes of this example it is assumed that the repository has been previously set up, all desired config files have been added, and that two files have been modified and need to be synced to the test instance. The process consists of the following 2 steps:

Enable the production instance.
Snapshot the selected production config files with the ncmgr cm commit command.
```
vovproject enable vnc
cd `vovserverdir -p .`
ncmgr commit -m 'save changes to taskers.tcl and policy.tcl' taskers.tcl policy.tcl
```
Enable the test instance.
Restore (synchronize) the same config files to the test setup using the ncmgr cm open command.
Use the production instance as the path to the repository.
```
vovproject enable vnctest
cd `vovserverdir -p .`
ncmgr cm -q vnc open
```