Updating the core

Run this on your machine, in the site, on the development branch:

php artisan mela:update

What the command does

1. It asks Composer for the newest MelaCMS release and requires it, raising the constraint when needed. While the core is below 1.0, ^0.5 does not allow 0.6.0, so a plain composer update would stay behind.
2. It applies the new version in a fresh process that runs the new core's code:
   • the new migrations,
   • any missing core role,
   • the public/storage link,
   • the MelaCMS section of AGENTS.md and CLAUDE.md,
   • a question for each workflow file whose core template changed.
3. It lists what's new since your version, read from the core's changelog, and prints the commit message, for example fix: update MelaCMS to 0.5.4.

Commit composer.json, composer.lock, the two agent files and mela-cms.json with that message, then release the site as usual. The message must start with fix:. A chore: would not make a release, so nothing would be deployed.

When you already have the newest version, the command applies it again, which is harmless.

Workflow templates

mela:update never overwrites a file the site owns without asking. mela-cms.json, at the root of the site, records for each workflow file which version of the core template you took or kept. A file you changed after taking its template is left alone.

When a new core version changes a template, the command asks about that file once:

Answer	Result
Take the core template	The file is replaced. This is the suggested answer when you never changed the file
Keep mine	The file stays as it is. The command does not ask again until the core changes that template once more
Show the differences	Prints a git diff from your file to the new template, then asks again

A file you deleted is offered the same way: add it, or leave it out.

Without a terminal (--no-interaction, or in CI) the command only lists the files that are waiting for a choice. php artisan mela:update --installed asks about them later.

On a site that has no mela-cms.json yet, the first run asks about every file that differs from its template and remembers the answers.

Checking for a new version

The Settings page of a local site (APP_ENV=local) has a Check for a new version button. It shows the newest release and the command that installs it, and changes nothing.

With Dependabot

The installed .github/dependabot.yml opens a pull request on development whenever a new core version is released, with the constraint raised and CI already run. That pull request tells you a release is out, but it does not apply it: the agent instructions still describe the previous version.

You have two options:

• Check out its branch, run php artisan mela:update and commit the result to it.
• Close the pull request and run mela:update on development, which does everything.

The site's CI makes sure this is not forgotten. It runs php artisan mela:update --check, which changes nothing and fails while the MelaCMS section of AGENTS.md or CLAUDE.md does not match the installed core. The pull request stays red until those files are committed. A workflow file that differs from its template does not fail the check, since it can be your own change.

Dependabot needs the PHP version pin.

Never update on the server

The deploy builds vendor/ from the committed composer.lock, so the next deploy would put the old core back, and the new one would have gone live without passing CI. On a production environment mela:update does not look for a new version.

Options

Option	Purpose
--installed	Skip Composer and apply the core already in vendor/, for example without a network connection
--check	Change nothing, and fail when the agent instructions are behind the installed core. This is what CI runs

Composer is also skipped when the core is not installed from a release, for example from a path repository during development.