Docs LATEST

Upgrading

Where to find official Core changelists and how to validate an upgrade safely.

Getting Started

VelvetCMS does not duplicate full changelogs on this docs site: every tagged release ships its own notes on GitHub Releases, and breaking migrations are spelled out in the repository UPGRADE.md.

This page routes you there and collects a minimal upgrade checklist. Use it together with Composer's from → to version range, not instead of upstream sources.

Routing: where to read #

Need Where
What landed in vX.Y.Z Open VelvetCMS/core releases, choose the tag (for example v2.3.0), and read that release page.
What changed across a range Compare tags on GitHub (from the release page compare links when GitHub shows them, or the compare UI between two tags).
Breaking steps for key jumps Read every relevant heading in UPGRADE.md for versions you crossed (2.2, 2.1, 2.0, or older sections if you migrate from 1.x).

Suggested order:

  1. Note velvetcms/core in composer.lock (from) and target (to).
  2. For each semver step you bump through (every tag you skipped), skim the release page for that tag.
  3. Open UPGRADE.md and follow every subsection that corresponds to releases you skipped (especially 2.x heading blocks).

Crossing multiple minors is additive: combine all release notes and UPGRADE.md sections along the path.

Before you upgrade #

  • Back up production data and user/.
  • Tag or commit Git before editing composer.json / composer.lock.
  • List enabled modules or custom providers; upgrades often touch config shape, tenancy, queues, or HTTP client usage.
  • If you automate deploys (queue workers, cron, WebCron): read UPGRADE.md and releases for CLI or env-flag changes affecting those paths before you deploy.

During the bump #

First-party setups fall into two shapes (both are covered under installation). Use the subsection that fits your deployment.

A. Project that declares Core via Composer (velvetcms/core dependency) #

  1. Bump the semver constraint only if your policy pins ranges; edit composer.json when UPGRADE.md or upstream tells you to, then run composer update velvetcms/core (or regenerate the lock through your workflow).

B. Whole Core checkout ( VelvetCMS/core repo: velvet, composer.json, src/ alongside each other ) #

  1. Update sources with git fetch/git checkout to the target tag or branch, or unpack a release tarball per your playbook.
  2. Run composer install (typically composer install --no-dev on production).

After deploy #

  1. Do whatever UPGRADE.md asks for along your from → to path plus any one-off chores in GitHub releases you skimmed. That pairing is intentionally the authoritative run list: upstream only tells you extra work when a release merits it.
  2. Run ./velvet diagnose for a quick smoke pass: cache round-trip, writable storage/ paths, database connectivity, content driver health, module manager boot. It does not audit every user/config key against defaults.

Smoke-test whichever surfaces you touched (routes, tenancy, queues, cron); skip extra ceremony when upstream did not ask for it.

At this point your tree should match the Core revision you targeted; keep an eye on GitHub Releases for follow-up patches on that line.

← Previous Installation Next → Principles