Filename Versioning Versus Cache-Control Max-Age for CSS Updates

Filename versioning is the more reliable choice

Changing the CSS URL creates a new cache key, so the browser fetches the updated file immediately after the HTML reference changes. For example, replacing styles.css with styles.a1b2.css means the old cached copy is not reused.

Confirmed facts

• Filename versioning changes the resource identity, bypassing existing cache entries under the old URL.
• Cache-Control: max-age defines freshness lifetime only; it does not evict a response already stored in the cache.
• Reducing max-age on an existing URL does not force immediate use, because the client may still serve the stale copy until its stored age expires.
• If the HTML that references the CSS cannot be redeployed, filename versioning alone will not reach the client.

Steps needed for this case

1. Generate a new CSS filename after the change, such as main.a1b2.css.
2. Update the HTML link tag to reference the new filename.
3. Deploy the updated HTML and the new CSS file together.
4. Set the CSS response header to Cache-Control: public, max-age=31536000 to allow long-term caching of the immutable file.
5. Keep the previous CSS file available for rollback until old page versions are no longer served.

Missing diagnostic: Can the HTML or templates that reference the CSS be redeployed to point to the new versioned filename?