I’m currently migrating a WSS 2.0 environment to MOSS. For my custom site definition I created the upgrade file and placed it in the 12ConfigUpgrade folder. I named the upgrade file as site definition name + "Upgrade" so that the upgrade process will pick it. Being a stickler about having as many comments as possible, I bloated my upgrade file with a lot of comments for all the features.
When I do the upgrade though, for some reason the process was applying the default global template to all the sites that were using the custom site definition. Checked all the related files and all of them looked good. After a careful second look of the Upgrade log I found a message saying that the Site Definition upgrade file is in invalid format. My initial thought was that I might not have closed some tags properly but that wasn’t the case. Just for giggles, I removed the comments and did another migration. What do you know, that worked.
I hope this saves some time to somebody.