View source for Software Development (WG1) Version Control (T3)

== Setting up a VistA Development Environment ==

=== Overview ===

This is a description of how VistA development environments should be configured.

'''Bold text''' designates program names, directory names, command line parameters, etc., that are intended to be typed in at a Linux shell or a GT.M prompt, e.g. '''/bin/bash'''.  ''Italic text'' is a descriptor of something whose actual value must be determined when the command is typed, e.g., ''gtmver''.

=== Theory ===

A release is a collection of routines and global variables.  The canonical packaging of a release, which is suitable for importation into any standard M distribution, is a collection of M source code routines and a database extract in ZWRite format.  When installed on a system, to run with an M implementation, a release may have pre-compiled object files, database files, shell scripts, global directories, etc.

Below is a diagram of the “roll-up” by which a VistA release (“Release A”) gets converted into another VistA release (“Release B”) by a development team.  A and B could be from different families, e.g., Release A could be a FOIA release and Release B could be a Leonardo da VistA release.

[[Image:051112-1WorldVistADevelopmentEnvironment_html_26096dee.gif|
"Roll up" model of VistA releases]]

Once Release A is installed, it remains frozen and unchanged except for any essential patches that may become available independent of the development process for creating Release B and without which the release lacks some required functionality.

At any given time, there can be multiple development projects underway based on Release A.  In other words, there may well be a Release C that is also based on Release A, but which has its own integration and development areas.

To start the development process, an integration directory is created and initialized with a copy of the global variables from Release A, as well as shell scripts, global directories, etc.  The integration directory may well have a different name from Release A and Release B.  For example, Release A may be FOIAVistA_20051021, Release B may become LeonardoDaVistA_0.4 (at the time that the integration area is created, the name and version of Release B may not be decided yet), and the integration and development areas may be named Greenbelt_200510.  There is no need to copy routines, since the GT.M search path will be set up to look for routines in the integration area before looking in Release A; hence only routines that are different between Release A and the new release need to be duplicated.

Actual development does not take place in the integration area.  Development occurs in development areas, typically in the home directories of individual developers; however, there may be a shared development area if two developers are collaborating on making changes to the very same module (i.e., their code changes overlap).  A development area is set up by creating a directory structure, shell scripts, etc.  Note that development areas can be hierarchical so that development subtasks 1a and 1b can be developed separately and integrated into development task 1, prior to integration into the integration area, etc.

During this development process, developers develop code in individual sand boxes (development areas), but normally share the database (global variables) in the integration area – there may typically be no need to create a separate database.  However, if some global variable changes are tied to code changes being made in a development area, a copy of those global variables can be placed in a separate database file in that development area, and a global directory for that development area can map those global variables to the database in that development area, with all other global variables mapped to the database in the integration area.

When a developer has code that is ready for integration, the new versions of the modified routines are promoted to the integration area.  Any global variables tied to the code being promoted that are in a database in the development area must be merged, reconciled or otherwise integrated with the global variables in the database in the integration area and the global directory in the development area modified accordingly.  Note that there needs to be a process, e.g., involving code reviews, by which a development task is considered complete enough to be promoted.  These, and other quality gates, are not discussed herein.

Creating a release is minimally the process of creating the directory structure for Release B, copying the routines from Release A, overlying the routines with those from the integration area, and copying the global variables from the integration area.

Normally, Release A, the integration area and development areas would all use the same GT.M version.  However, this is not a requirement.

=== Practice ===