Begin with the changed artifact
A release note is a claim about a particular package, not permission to replace everything around it. GitHub releases connect notes and downloadable assets to tags; tag dates and release dates can differ. Save the exact version and artifact you intend to use. Then list the parts of your own deployment that the change touches: application code, data, public paths, configuration or background work.
A path change that our local preview did not settle
During this project's November 4, 2026 visual upgrade, a new presentation package initially referenced assets under /design/. The files existed in the prepared release. The production host, however, already routed arbitrary paths through a gateway. The new prefix reached that gateway instead of the website's static directory.
Checks after the first activation detected the mismatch and restored both previous website pointers. We retained that failed attempt. The corrected release moved the new assets under the existing /_astro/df-design-20261104/ static route, rather than changing the shared web-server routing. Only the two font URLs changed inside the final stylesheet; the visual rules were retained. This is an internal website-release example, not a claim about a bug in an upstream framework.
Make an upgrade record that can catch that failure
- Input: the candidate HTML, its stylesheet and font URLs, the current production route map and a recoverable predecessor.
- Claim to verify: the upgrade should alter presentation while preserving existing content and services. A file existing in an archive is insufficient.
- Required observation: request each changed resource through the same public hostname and path readers use, and compare its bytes with the candidate.
- Failure result: stop when routing returns a different resource, even if the transport status looks successful. Do not interpret an HTTP 200 alone as the correct stylesheet.
- Decision: reuse the existing static route and repeat the affected resource checks before accepting the corrected release.
On November 6 we read the corrected public stylesheet again. It returned HTTP 200 with text/css, contained 35,820 bytes and matched the retained SHA-256 fingerprint beginning 6c70820ff9bc. The full resource is available at the deployed stylesheet URL. This confirms resource delivery at that observation; it does not replace visual inspection on a phone or measure global loading speed.
Translate upstream notes into deployment questions
If a release changes an asset prefix, ask which proxy or gateway owns that prefix. If it changes a login callback, test the callback on the intended hostname. If it changes a content model, rehearse the migration and restoration using disposable data. If it removes an option, locate every place that supplies it. These are examples of checks to derive from a release note, not claims that all those changes occurred in our upgrade.
Keep the previous artifact, configuration assumptions and result together. Record a failed attempt as failed, and identify the corrected version separately. An installer exit code, an extracted archive and a successful build each establish different intermediate facts. The upgrade decision should name the reader or operator behavior that was actually checked.
Choose a narrow rollout
For this incident, expanding the change to the shared server's routing would have increased the scope unnecessarily. Moving the assets to a route that already served the site answered the immediate problem. For another product, a migration may genuinely require a route or database change. Let the release's concrete changes determine the rehearsal and rollback plan rather than treating every update as either harmless or a complete rebuild.