Best Practices for Distributed Development

If you have a team of developers building an application, each using their own workstation, it is important to put procedures in place to manage updates. Whatever procedure you use will work best if it works in concert with the VTScada Version Control system, therefore this discussion begins with a review of that tool.

Proper configuration of your network configuration for VTScada is also important. Refer to Client / Server Configuration, and VTScada and VPNs, noting in particular the warning against using Network Address Translation (NAT) routers.

Version Control in a Networked Environment

Suppose that you have three workstations on your network, A, B and C, all of which are being used to develop your application. Machine A is the primary server in a simple server list, meaning that it is also the primary server for configuration. B is the backup server and C is a client workstation and therefore not part of the server list even though development work is done there.

The version control system works as follows. Assume that auto-deploy is enabled on all machines.
(Local versus Deployed Changes)

Example 1: Basic Changes

A change is made on a workstation.
Workstation B in this example. This creates a new entry in B's version log.
That change is sent to the primary configuration server, A, where it is recorded in that version log.
The configuration server sends the updated version log to all connected workstations including B where the change originated. This ensures that everyone is working with exactly the same revision and every machine can see the status of every other machine's version log.

What is transferred between machines is an update to the version log. The version log contains code for the triangle, which then shows up on the other workstation. But, it is important to note the distinction between transferring the code for the graphic (not what happens) versus transferring the update to the version log, which contains the code for that graphic. Because the version log update includes information about the time when the change was made, the machine where it was done, the developer who was signed in, and other contextual information about this change, it is possible to blend changes at a code level.

Suppose that another developer is at machine C and is working on improvements to the same page. Thanks to the version control system which is managed at a single server, that developer's changes can be merged with the changes being made at B. The only time there would be a conflict is if they both edit the same line of code and save their changes at almost exactly the same time. In that case, the first version to arrive wins and the second is lost. You are advised to avoid having two developers work on the same page, widget, or tag at the same time.

Example 2: Auto-Deploy Switched Off

If auto-deploy were turned off at machine B and the addition of the triangle was local, not deployed, the same process would still happen. Every version change, deployed and local, follows the process described, and the triangle will be included in the update distributed between machines. But developers at workstations A and C would not see the triangle until the developer at B chose to deploy changes. All updates to the version log (both local and deployed), made on all machines, continue to be sent to the primary server A, which then distributes the combined history back to all machines.

Suppose a deployed change is made on C while B continues to work with auto-deploy turned off. Thanks to the process just described, the developer at B will see the change from C immediately, but it will not interrupt any work that they are doing unless the changes conflict directly with their undeployed work.

Example 3: Verify a Merge Off-Site Before Applying to the Server

You may need to test a combination of changes at an off-site location before applying those to the server. This is a less common work flow, typically used when a workstation has been isolated from other servers for a time and you are unsure what work might have been done at that workstation in the meantime. The recommended steps in this case are:

Create a ChangeSet on the server.
Apply that ChangeSet to the off-site workstation.
Review and test the changes at the off-site workstation.
When satisfied, create a new ChangeSet on the off-site workstation, take it to site, and apply it to the server.

At this point, the configuration on the server will match the configuration on the server (with the addition of any changes that have been made on the server since the ChangeSet was created in step 1, which, like always, will merge with the changes being applied in the ChangeSet).

Example 4: Breaking the Version History

This is an example of a practice to avoid. Let's look at a way to break the version log using a ChangeSet.

The following is an example of how NOT to work. Do not do the following:

On a Monday, the developer at workstation A creates a ChangeSet.

A ChangeSet is a single file that contains the version log.
The developer looks at the version history and notices that they are at A-D100 (for deployed revision 100 at workstation A).
The developer does a day's work, advancing to revision A-D200.
At that moment, they realize that they have bad information for the design and now want to rewind to the earlier state.
Meanwhile, development has been continuing at B and C. The version history contains a mixture of revisions from all three workstations, each with a number, a timestamp and other contextual information.
Developer A attempts to undo their work by deleting the application, then installing the ChangeSet.

This scenario does not end well. If the workstation A is connected to the network, then the repository is synchronized immediately and A is back at A-D200. If A is temporarily disconnected from the network, then the developer might create a new change, A-D101. Machine A is then reconnected to the network. But the recent A-D101 change is not the same as what B and C know as A-D101. This creates a "repository clash" with extremely disruptive results.

In a networked multi-server environment, NEVER attempt to restore an application on one server by using an old ChangeSet from that station.

Version Control in a Distributed Environment.

When attempting to bring a remote workstation up to date, a common impulse is to delete the application then re-install from a ChangeSet. Sometimes an older ChangeSet.
>> Don't do that. <<
It's better to apply a new ChangeSet from an up-to-date server and go. This is always the cleanest and fastest method to use.

In a distributed environment, workstations are not networked and the version control system cannot distribute updates continuously and automatically. To ensure that development continues smoothly, you need to mimic the function of that system by using ChangeSets. A ChangeSet is the set of changes that make up the application. In short, the version log.

Your first step is to select one workstation that will be designated the Primary Server. That might actually be the primary server within one office, or all workstations might be working completely independently with none having a server list. In either case, the step is the same - select a workstation and call it your Primary Server for configuration changes.

Implement the following work flow:

Ensure that Auto-Deploy is turned ON.
In this scenario, there is nothing to gain, and potentially much to lose by turning off Auto-Deploy. While there might be a case for the careful use of local changes in this scenario, these are difficult to manage in practice.
Create the application on workstation A (the designated primary server in this example).
Create a ChangeSet file.
Send that ChangeSet file to B and C and tell them to use the Get From ChangeSet tool in the Add New Applications wizard.
The same application now exists on all workstations and everyone can begin development.
A set of changes are made on a workstation. (B)
This might be a single change, a day's work, or a week's work, but the more often the better.
At that workstation, create a full ChangeSet file.
Send that ChangeSet to the designated primary configuration server.
At workstation A, use the tool "Apply ChangeSet", found in the Application Configuration dialog.
(Apply a ChangeSet File)
All of B's changes will be merged into the master version log.
If a ChangeSet has arrived from another workstation, apply it as well.
At the Primary Server, create a full ChangeSet file.
Send that file to B with instructions for them to use the Apply ChangeSet tool.
This ensures that everyone is working with exactly the same revision.
Repeat as necessary: When changes are made on C, send those from C to A and then send an updated ChangeSet back to C.

Best Practice Guidelines:

Ensure a two-way exchange of ChangeSets between remote workstations and a designated primary configuration server.
Do not exchange ChangeSets between the remote workstations. Send all updates back and forth only to the designated primary configuration server.
(You are allowed to choose a different primary configuration server from time to time as needed. When doing so, ensure that it has the latest ChangeSet from the previous primary.)
Trade ChangeSets frequently so that all machines remain up-to-date.

It is possible but risky, to continue development while waiting for ChangeSets to flow back and forth. Better to wait for the exchange to be completed. If you must continue to work, do so on a new page or feature, thereby reducing the chance of conflict with another developer's work.

The following practices must be avoided:

Never restore a workstation with an old ChangeSet.
In a networked environment, use Get From Workstation instead. Never use a ChangeSet, new or old.
In a distributed environment, contact the developer at the designated Primary Server and request that a new ChangeSet be made.
In a distributed development environment, never send ChangeSet updates between machines that are not the designated Primary Server.
All updates must flow to the Primary Server, then from that machine back to all development workstations. Never take shortcuts.