How-to library · Developer docs

How-to library

Task-shaped pages: a title that starts with a verb, the situation in a few lines, the steps, the working code in both engines, and why this way rather than another. Found from a search, done, and left.

How-to Performance, deployment and operations

Diagnose "my change is not showing up"

Published

The most common question on any project, answered in the order the causes usually turn out to be true, with a marker in the page that settles the first one in seconds.

Context

Context. A change was made, a template edited, a style fixed, a page updated, and the site does not show it. There are only a handful of places the change can have stopped: it was not deployed, not built, made to the wrong file or record, not published, or it is live and someone is looking at an old copy. Working through them in order finds the answer in minutes; clearing every cache first wastes the evidence and usually does not help.

Steps

  1. Code or content? A change to a template, a stylesheet or a script travels by git; a change to a page, a layout, a setting or a menu is a record and travels by being saved. Follow the matching branch below.
  2. Code: is it deployed? Check the release marker in the page (below) against your commit. If it is older, open the environment's deploy log: no entry means the push went to a branch this environment does not deploy; a failed entry says why (the deploy log).
  3. Code: is it built? For CSS and JavaScript, the committed build must contain the change. Run the production build on the deployed commit and see whether it changes anything (the symptom).
  4. Code: is it the file that renders? The page's layout points at one template path; the site's templates override the platform's at the same path. Confirm which file renders with a temporary marker comment in it.
  5. Content: is it published and on this site? A saved draft is not visible; a published date in the future is not yet; an unpublish date may have passed. Two records with the same slug, or an edit on a different site of the account, look like a change that did not apply.
  6. Content: does the cache know about it? Saving a record clears the pages that showed it, but a settings change, a renamed author or a new redirect does not (what it never sees).
  7. Which copy is stale? Request the page signed out with curl and read X-Cache-Status and Last-Modified; compare with your browser; with CDN caching on, add an unused query parameter (is this copy stale).
  8. The right place? Staging and production, www and the bare domain, are different environments or hostnames, each with its own cached copies.

Code

A release marker in the base template, so that step 2 is one command instead of a guess:

Template code 
<meta name="release" content="{$_currentSite->getEnvironmentName()|escape} {$_currentSite->getVcsBranch()|escape}@{$_currentSite->getLastVcsHash()}">
<meta name="release" content="{{ _currentSite.getEnvironmentName()|e }} {{ _currentSite.getVcsBranch()|e }}@{{ _currentSite.getLastVcsHash() }}">

Reading it, and the cache headers, signed out:

Shell 
url="https://www.example.com/about"
curl -s "$url" | grep -o '<meta name="release"[^>]*>'
curl -s -o /dev/null -D - "$url" | grep -iE 'x-cache-status|last-modified|cache-control'
git log -1 --format='%h %s' origin/master

For step 4, a marker comment in the template you edited, removed once you have your answer:

Template code 
{* temporary: confirms this file renders *}
<!-- marker: products/products/show.html -->
{# temporary: confirms this file renders #}
<!-- marker: products/products/show.html -->

Why this and not that

Clearing caches first is the instinct, and it destroys the one piece of evidence that would have told you which copy was stale, while doing nothing for the three most common causes: an undeployed commit, an unbuilt stylesheet and an unpublished record. The release marker costs one line and answers "is my code live?" for everyone on the project, including the client. The same symptoms, organised by what was changed, are on the It is not showing up troubleshooting page.

Go deeper
GuideGit-based deploy FAQTroubleshooting: It is not showing up

Was this page helpful?

Your answer goes to the docs team.