Lessons learned from a heavily modified AC7 site

It was exactly 1 year ago this week when I started making changes to my AbleCommerce 7 install. The version was Beta 1. You read that right. That was before Final SR1, before Final, before RC3, before RC2, before RC1 and before Beta 2. I was a complete noob to eCommerce - AC7 was my first storefront product. Solunar.com was my first effort at an online business. It was also my first full .Net application. I had maybe 6 months of (incredibly simple) .Net programming experience. I knew nothing about HTML, XML, data classes or namespaces.

With the help of Able staff, forum members and your friend Google, my knowledge and experience grew every single day. I made the decision to go live with Beta 2. In hindsight, that was probably the best thing I could do from an educational perspective although it was painful. Not so much because of Beta 2 but moreso my lack of experience with the whole go-live thing in general.
Since those days of blissful ignorance, I've learned a great many things. I thought I would take some time to share some of my experience with the forum members. I'll also post a copy to my blog at http://www.AbleMods.com/Blog/.

Modifications to Existing AC7 Files

Every modification to an existing AC7 file comes with a price. You must consider that the file(s) modified will get updated in a future AC7 upgrade. This leaves you with the task of re-incorporating those modifications into new files. While this may not seem a major task, imagine a full 12 months worth of tweaks, changes and major improvements. Now the magnitude of effort to upgrade directly impacts your decision of WHEN to upgrade. You're trapped.
I currently have 24 separate, existing AC7 files that are modified. Some of these will take only a few minutes. Others will take days. This doesn't even take into account the 12+ for-sale modules I have on AbleMods.com. So just imagine 36+ separate modifications, spread across 12 months of time and all at varying degrees of complexity and skill. Some of the changes involve code I haven't looked at in 6 months, so re-educating myself will burn up some time.
When you are considering the decision to modify an existing AC7 file, I strongly reccomend you not make the decision in haste. Take the time to consider the impact on your future upgrade needs. Able might release something incredibly useful to you - now you're feeling the pressure to upgrade even more.

Modification Design Considerations

To Tweak or Make New. That's the very first question I ask myself when considering any modification. A tweak involves changing an existing AC7 file. Making new is just as it sounds, I make a completely new file named separately from all others.
A lot of this decision comes from the complexity of the change involved. Adding a single button to an ASPX page involves far less effort than making the minibasket show product images for variants.
My second question is always: How many files do I have to change if I make a completely new file? The reason I ask myself this question is critical to the upgrade process. Imagine modifying the ~/ConLib/Utility/ProductPrice.ascx control. That control is used in a variety of other user controls. If I make a completely new file, I'm going to have to find and modify every single one. If I miss any one file, the site is bugged and I probably won't even know it.
So sometimes it's better from a modification-management standpoint to simply change the original file.
But what about the upgrade process? Let's say I do make a brand new ProductPrice file and modify all the controls that use it. I install the next upgrade and it blows away all those control changes I made. But, my specially-named ProductPrice file did not get erased. It's still there and probably still works. All I need to do to re-activate it is simply change one line in each of the user controls again.
The point? Sometimes it's easier to make 6 little 2-minute changes to the user controls than re-integrate 8 hours of work into a single ProductPrice file.

Documentation

I make 3 different efforts to document every programming modification I make to Solunar.com.
The first is in the code files - I preface each modification with a comment like "// BEGIN MOD: Solunar 10-6-08" so it can be easily found with a search function. I usually end the mod with "// END MOD: Solunar" just so it's more clear exactly where the mod starts and ends.
Second, I keep a separate folder on the live site call "Customized Pages". Every time I upload a changed file, I upload it twice. Once to the location from which it will run, and a second copy goes in this special folder. The folder has the same folder structure as the existing site. That way I can easily tell ~/Admin/Orders/Default.aspx was modified and WHERE it should go within the storefront app.
Third, I keep a Word document that is sort of my diary for programming changes. Since I already have a desktop folder on my development PC for all my developer tools, it's easy to keep this document close to where the work is done. It's helpful because I can spell out what I was trying to accomplish, when I did it etc - makes a nice reminder when I have to go back to that code and look through it again.

User Controls Are Your Friend

The ConLib design of AC7 was ingenius. It gives you the flexibility to modular-ize your efforts into reusable components. But it also gives you the ability to incorporate modifications without affecting your upgrade options down the road.
When I know a user control is going to require modification, I copy/rename that control into the ~/Conlib/Custom folder. So if I'm modifying ~/ConLib/BuyProductDialog.ascx, it'll become ~/ConLib/Custom/Mod_BuyProductDialog.ascx.
This technique benefits me in a variety of ways. First, it keeps my changes separate from default AC7 files so an upgrade doesn't overwrite my work. Second, because I included the original control name I know exactly what the original file was and thus the intended purpose of the modified control.
Once the modifications are done, I simply change the customer scriptlets to reference the modified control instead of the default AC7 version. Not only does this make installation painless, it makes going back just as easy in the event the modified file did not perform as expected. Incredibly helpful when working on live sites.
The vast majority of the time, an upgrade doesn't break your existing code. It can still happen, but it's fairly rare in my experience. So any time I can keep my modifications separate means there will be one less thing to break when the upgrade is installed.

Conclusion

Making modifications to an existing storefront system should never be taken lightly. There are significant ramifications and responsibilities that come with those changes. As a developer and a consultant, I make a specific effort to notify each of my clients of the foreseeable impact their requested changes will have on future upgrades. It's my duty to advise them but not dictate to them. Should they choose to modify themselves into an "upgrade corner", well that's their choice. My job is to make sure they make an informed choice.