The SubversionIntegration plugin tries to integrate into CoDeSys in a non-intrusive way. Existing objects can be versioned without any modification. However, there are some object behaviours and properties which can cause negative side effects. Following the suggestions in this article can help to eliminate (or minimize) those effects.

The binary representation of objects should be stable.

The Subversion plugin uses the binary archive writer and reader to convert objects to a binary representation suitable to be handled by Subversion. Objects should try to keep that binary representation stable whenever possible. (This is a general Rule in CoDeSys, and not specific to subversion.) A changed binary representation shows up as a local modification in versioned projects. Thus, semantic (user-visible) changes in an object are the only changes which should (and must) result in a different binary representation of an object.

Some objects manage some internal state which is not visible to users, but needed for the internal workings of the object or CoDeSys. For example, some objects contain a bunch of GUIDs used for their contributions to the language model. Some of those objects regenerated their language model GUIDs in an IObjectManager.ObjectAdded handler. This results in a changed binary representation and thus to SVN showing local changes whenever an SVN operation added one of those objects to a project (like a checkout operation, or an update bringing in new objects from the repository). Note that it is actually important to update those GUIDs in case of real collisions to preserve the internal project consistency (language model etc.). Such collisions will occur when identical copies of existing objects are added to a project, for example with Copy/Paste or Export/Import. So those objects were fixed to only update their internal GUIDs when an actual collision occurs.

Another example of such internal state is the internal location counter in ST objects. The locations link search results, or messages like compiler errors to the appropriate position in the editor. To generate those locations, ST objects internally maintain a counter which is increased whenever a new location is needed. When the user edits an ST object by adding a line, the internal location counter will be increased to create a new location for that line. When the user then removes that line again by editing the source, the internal location counter still has the new, increased value. This leads to subversion indicating a local modifcation for that object, while the project comparison shows identical sources.

A similar issue arises for internal lists or arrays which semantically represent sets. (In other words, the order of entries is not semantically relevant.) Reordering of those internal lists does not result in a semantic change, but it changes the binary representation of the object. Objects maintaining such internal lists should take care for that stability on their own, having at least three possibilities:

• Always keep those lists in some canonical order.
• Implement the ISvnObjectSerializationCustomizationHook.InterceptWrite() interface to sort the list just when the subversion plugin serializes the object.
• Sort the list in the IArchivable.BeforeSerialize() method. (This has the disadvantage of slowing down other serializations, e. G. on project save or export. As an advantage, it leads to a stable format for export, too.)

Avoid primary project centric design.

IObjectManager.ObjectAdded events or IObject.AcceptsParentObject queries which are not for the primary project used to be scarce. Thus, some object implementations simply assumed that IObjectManager.ObjectAdded or IObject.AcceptsParentObject were called on the primary project. (In fact, IObject.AcceptsParentObject for top level objects gets null as parameter and thus has no way to tell which project is affected.)

However, the subversion plugin needs to checkout objects into secondary projects, for example for project and object comparison, turning that unusual operation into a common one. Incidentally, we learned that an OEM using secondary projects in a similar way also suffered from this problem.

Having the primary project hardcoded can lead to strange effects. Some of the problems we stumbled upon are:

• The checkout of a top-level library manager (the one in the POU view) in a secondary project failed because the primary project already had an instance
• When a project with Visu objects was checked out in a secondary project, the primary projects library manager was updated with the libraries needed by that Visu object.

Thus, objects which perform those more enhanced tests and actions in IObjectManager.ObjectAdded and IObject.AcceptsParentObject should make sure that they always obey the project passed there, and - if necessary - implement the new IObject2.AcceptsRoot method we added in V3.4.4.0.

Sidenote: The standard project comparison is not affected: It loads the project as a secondary project, which is a common operation and triggers a different set of events.

Implement project comparison and merging.

For the graphical object comparison and manual change merging, SVN internally uses the existing project and object compare functionality. So implementing project comparison for your objects has the positive side effect of improving the situation for Subversion users.

Additionally, V3.5.2.0 introduced new interfaces for automatic merging of changes, which should be implemented by the objects if possible.

Project options may change "behind the hood".

During operations like "Update" and "Switch", the project settings object which contains the OptionRoot.Project data may be changed without any options editor being involved. Thus, your code should use the appropriate changed events of the option storage if necessary to react to those changes.