Upkeep : Merging Overview
Source Code Merging
Because AFX comes pre-merged with the engine source code, you don't have to immediately deal with code merging issues. All AFX enhancements are already in place and ready to use. However, if you use an AFX-enhanced Torque engine to develop your own game, it's highly likely that you will eventually be faced with the task of merging source code. This section is a quick overview of what this might entail and how you can prepare for it.
One way to implement a game is to dive right in, never looking back, while you arbitrarily modify the engine and add resources until it becomes the game you want it to be. While this is a fine approach for shorter projects lasting only a few months, it may lead to frustration for longer efforts as new versions of your Torque engine, AFX, and other resources are released with no easy way to merge their improvements into your own game.
An alternative strategy is to use organizational conventions and special tools to manage your project in a way that minimizes the difficulty of updating it with occasional changes to its dependencies. Code merging is always somewhat tedious, but the proper tools and a little planning can make it much more tolerable.
Merging Tools
The first tool that will help maintain a linkage between your project and the resources it depends on is a version control system, (also known as source code control, or revision control systems). There are many of these to choose from and the one that works best for you is largely a matter of preference. My personal preference is the combination of Subversion with a TortoiseSVN front-end, (both are freely available), but any decent and reliable system is fine. Version control systems are indispensable for coordinating source code changes from multiple programmers, but even for single programmer projects, they are great for keeping a history of changes over the life of a project.
As a merging tool, you use revision control to keep track of not only the changes to your own code, but also the changes to everything it depends on. At the beginning of your project, you place a pristine copy of the engine under version control and whenever updates become available, you add those changes to version control the same way you would add your own. This should be done to all external dependencies such as the Torque engine, AFX, and any other code resources to track all changes and improvements. With Subversion/TortoiseSVN, you can maintain separate repositories for all of your code dependencies while still referring to them from your own project.
Another important merging tool is a program for doing binary or rules-based comparisons of potentially large folder and file hierarchies. Again, there are many solutions to choose from. My personal preference is Beyond Compare 3 which is a commercial product that costs about $30-50 (depending on edition) and combines features for comparing folder hierarchies and file merging. Whenever I get a new Torque engine release, the first thing I do is startup BC3 and do a comparison of the new release with its predecessor. Not just a source code comparison, but a complete comparison of example folders and content files also. Although I don't dwell on understanding every detail, this process gives me a thorough overview of what has changed in the new release. Generally, this is more useful and more accurate than reading change notes or lists of changes in a forum.
The last important tool is a special differencing and merging editor that displays a side-by-side comparison of two text files, allowing you to copy changes from one file to another, or edit text directly. Many people like the Open Source WinMerge program, but again, my preference is Beyond Compare 3 which has an excellent merging editor in addition to its folder comparison features. I even setup TortoiseSVN to use BC3 instead of its own diff viewer for displaying revision differences.
Organizational Strategy
Having the right tools and knowing how to use them is just part of the solution to source code merging. You also need to organize your project in a way that minimizes conflict with external dependencies and their updates. The overall strategy is to keep your custom code as isolated as possible from the engine, AFX, and any other code you depend on. AFX requires a number of modifications to engine source files. While the number of changes is not insignificant, it has been greatly pared down by isolating large amounts of code to files in the engine/afx folder.
When work on AFX first started, TGE was at version 1.3. Since then, AFX has had to adapt to two major TGE upgrades, the addition of TLK and it's upgrades, migration to TGEA 1.0.3, followed by upgrades to 1.7.1, and 1.8.1, and now Torque 3D. Keeping up with all of these moving targets was done using the basic techniques and tools described here.
