I decided on a rule based merge - building one object in memory that contained all the essential data to run the comparison and store the result. Certain comparisons cannot be resolved automatically and the user needs to be offered a choice of solutions. Each rule that gave an ambiguous comparison result could then be presented to the user when all the comparisons had been done. This allows the user to see a known number of reports and monitor their progress - the idea of presenting the user with a seemingly never-ending list of reports by trying to compare, resolve and merge each object individually was not appealing. When all necessary results have been resolved, the code would then prepare to merge the data - leaving the user the opportunity to abort the merge at any point prior to the final commit.
Each rule would describe one entity - a single object of a specific QOF type containing known QOF parameters, discrete from all other objects of the same type in the QofBook. Rules would then be built into a single ruleset that can be queried, updated and provide the data for the final commit.
QOF uses a unique identifier to identify single entities, independently of the contained data or object type; the GUID. The purpose of the code was described on the GnuCash development mailing list as:
"The bulk of the task is the merging. qof_book_merge needs to determine what data in the import maps to the existing data, what data is new, and what data is a duplication. There's been a good deal of work to do this with Transactions, but not with Accounts, or any of the businessfeatures."
qof_book_merge needs to determine for each object in import if it's:
"the same" (guids match)
"maybe the same" (guids don't match but something else matches,
like maybe the account name or invoice owner/date)
"new" ("clearly" new)What we're testing here is if the object refers to the same semantic concept. e.g. there is a semantic concept of the top-level Asset account. But if I'm merging your account tree into my account tree the guids will differ, but semantically they are the same. Hence, these accounts are "maybe the same". qof_book_merge probably needs user intervention here to properly map the "maybe the same" objects.
If objects are "the same" or "maybe the same" then qof_book_merge might need to determine whether they contain different data. For example, if I import my OWN account tree again (say, merging a backup file), I might have changed a description in an account, or I might have changed a transaction.
qof_book_merge also needs to keep all the references correct.
Finally, qof_book_merge must allow plug in rules per object type.