Why CMS template hacks break on upgrade, and how to customise safely

A 2006 phpWordPress thread gave readers a hack to show subcategories on a category page: add a template tag, then edit index.php at a numbered location. A reader on a newer version could not find the lines, and staff had to republish the instructions for 3.2. The nested category display is incidental. The failure is general, and it is why customisations deserve a plan.

Why do template hacks break on upgrade?

A hack that edits shipped files has three weaknesses.

1. The update overwrites it. If the installer replaces the core files, your edit disappears silently, or conflicts with the new version.
2. The target moves. Line numbers, function names and surrounding code change between releases, so instructions for one version fail on the next.
3. Nobody remembers it. An undocumented edit is knowledge held by whoever made it. When they leave, the next upgrade is a mystery.

Drupal’s documentation states the consequence directly: never edit base templates in core/modules, because those changes would be lost during updates.

Where should customisations go instead?

Each mainstream CMS provides places for your code that updates leave alone. The names differ, the idea is the same.

WordPress filters illustrate the pattern: a filter takes a variable, modifies it and returns it, so your code adjusts what core produces without editing core. The result is that when WordPress or Drupal ships a new release, your layer is untouched and only needs retesting.

What would the 2006 request look like today?

The customer wanted subcategory links on a main category page. In a current system, work down this list and stop at the first one that works:

1. Configuration. WordPress documents that clicking a parent category displays all posts in it and its sub-categories. Some systems have a setting for a subsection list, or a listing component you place on the section page.
2. A theme override. Add the subcategory list to the category template in your child theme or sub-theme.
3. A small plugin or module. If several themes need it, put the logic in a plugin using the CMS’s hooks.
4. Edits to core files. Avoid them, for the reasons above.

Our answer on section pages covers how to structure the hierarchy itself.

What are the common mistakes?

• Copying the whole theme to change one file. An override should contain only the files you changed, so the rest keeps receiving the parent’s fixes.
• Pasting snippets into a theme’s functions file with no comments. Months later nobody knows which lines are yours. Put them in a named plugin or a clearly marked file.
• Editing in the live admin editor. Changes made there bypass version control and staging, and one syntax error can take the site down.
• Following a tutorial for a different version. The 2006 thread shows why: the same hack needed rewriting for the next release. Check the version a guide was written for before applying it.
• Skipping the changelog. The release notes list renamed templates and removed functions, which is exactly what breaks overrides.

How do I keep customisations maintainable?

• Keep them in version control. Child theme, plugin folders and configuration belong in a repository, so each change has an author, a date and a reason.
• Write a short README. List each customisation, why it exists, and which core behaviour it depends on.
• Prefer fewer, smaller changes. Each override is something you retest at every upgrade.
• Pin and record versions. Note the CMS, theme and plugin versions you tested against, as discussed in our answer on security patches.
• Remove what you no longer use. Dead overrides still need compatibility checks.

How do I test an upgrade?

1. Take a full backup. WordPress documentation advises backing up the database regularly and always before an upgrade.
2. Restore the backup to a staging environment and upgrade there.
3. Open each template you have overridden, plus the pages that use custom plugins: home page, section page, article, search and archive.
4. Compare against production, fix, and only then upgrade the live site in a quiet period.
5. Keep the backup until you are confident nothing is broken.

If an override stops working, the diff between the new parent template and your copy usually shows what changed. This is another argument for overriding only the templates you must.

What if the CMS gives no safe extension point?

Then the vendor is telling you something about the cost of ownership. Ask their support whether the feature is planned, whether a paid add-on exists, and what the supported upgrade path is for customised installs. If the answers are poor, count the maintenance burden in your cost comparison, and put extension support on your feature checklist for the next review.