There is a particular kind of CS-Cart store that I've now seen enough times to recognise from the symptoms alone. It works. It has been customised heavily over several years. And it is stuck three or four minor versions behind, because the last attempt to upgrade broke checkout and had to be rolled back at two in the morning.
Nobody decided to end up there. It's the accumulated result of a long series of individually reasonable decisions — a quick fix in a core file, a template edited in place because it was faster — each of which quietly increased the cost of the next upgrade until upgrading stopped being possible.
The mechanics of avoiding that are not complicated, and CS-Cart documents them. They're just easy to skip when something needs fixing today.
The rule everything else follows from
CS-Cart's developer guidelines state it plainly: don't change core files. The reasoning is worth internalising rather than just obeying, because it explains every other rule here.
An upgrade replaces core files. Not merges — replaces. So a change you make in one is not at risk of conflicting during upgrade; it is guaranteed to be deleted by it. And it will be deleted silently, because from the upgrader's perspective nothing unusual happened.
That produces the worst debugging experience available: behaviour that worked on Friday and doesn't on Monday, with no diff to look at, because the file you changed now looks exactly like it does in a clean install. The knowledge that it was ever modified lives only in the memory of whoever modified it, and they may not work there any more.
Put changes in an add-on
The supported alternative is to build your change as an add-on and reach into core behaviour through hooks rather than editing it.
The practical wins are larger than "it survives upgrades", though it does. All your files live in one directory named after your add-on, so what you've customised is visible from the file system rather than reconstructable by inspection. And the change can be turned off — disabling the add-on reverts your behaviour in a couple of clicks, which converts "did our customisation break this?" from an afternoon of bisecting into a thirty-second test.
That toggle is worth more than it sounds. Most of the cost of a heavily customised store isn't making changes; it's the inability to answer whether a given problem is yours or the platform's.
Clone the theme, and copy only what you change
Same principle on the presentation side. Don't edit the default theme. Clone the active theme, then copy across only the specific templates you're actually modifying and edit them in the clone.
The "only what you change" half matters as much as the cloning. If you copy the entire parent theme into your clone, every template you didn't touch is now a frozen snapshot that will never receive an upstream fix — you've forked the whole presentation layer to change a product page. Copy the two templates you need, leave the rest inheriting, and upgrades keep improving the parts you never had an opinion about.
When you do override a template, leave a comment saying what you changed and why. Smarty templates are long, the diff against the parent is not something anyone can see at a glance, and in a year the question "why is this file here at all?" will be asked by someone with no context.
Find out what previous developers already did
If you've inherited a store, this comes before any of the above, because you cannot plan an upgrade without knowing the damage.
CS-Cart ships a File Changes Detector under Settings → Storage that scans for modified core files. Run it. On a store with history it will find things, and what it finds is your actual upgrade risk register — every entry is either a change you need to reimplement properly as an add-on, or one you can delete because nobody remembers wanting it.
Do that work before the upgrade rather than during it. The difference between planned migration and emergency archaeology is entirely about when you ran that scan.
Development mode, and the template cache
One practical thing that costs people a confusing afternoon: CS-Cart compiles Smarty templates and caches the result. Edit a .tpl and you may see no change, because you're being served the compiled version from before your edit.
Turn on development mode while working so templates recompile, and remember to turn it off in production, where that recompilation check is pure overhead on every request. "My change isn't showing up" on CS-Cart is the template cache far more often than it is anything you did wrong.
Upgrade on a copy, with real data
Back up the database and the file system before any upgrade — CS-Cart says this and it's obviously right — but the more useful advice is to do the upgrade on a staging clone of production first, with the real data volume in it.
A clean test install tells you almost nothing, because the problems live in what accumulated: the add-ons, the overridden templates, the orders table with years in it. The upgrade you want to rehearse is the one against your actual mess, and the value of the rehearsal is finding out how long it takes and what breaks while nobody is trying to buy anything.
Why this compounds
Every core edit raises the cost of the next upgrade. Raise it enough and upgrades stop happening — and then you're on an old version, which means missing security patches, add-ons you can't install because they need something newer, and a growing gap that makes the eventual jump bigger and scarier.
The stores that stay current aren't the ones that customised less. They're the ones where the customisation lives somewhere the upgrader doesn't touch. That's the whole difference, and it costs maybe an extra hour the first time you set up an add-on properly instead of editing the file that was already open.