Updating project version: Composer

Question

What's the right way to change version number when using composer? Consider the current scenario:

You have master and develop branches and your version is 1.0.0. A critical bug appears and you have to create a hotfix-1.0.1 branch (from master) to fix it and merge back to both master and develop. Once you're about to merge, you update "version":"1.0.1" inside composer.json.

Now what? in my case I ran composer update and several dependencies where updated (which was not the reason I ran it, I just thought it was mandatory to run it every time composer.json changes), which ended up in a 1 hour conflict-resolving on composer.lock when merging branches.

Do I have to run composer update (or any other composer command) after updating "version" or that is not necessary and I can just git commit and git push?

Answer 1

There is no need to run composer update when you update your own version number. Only run it when you want to update dependencies:

In order to get the latest versions of the dependencies and to update the composer.lock file, you should use the update command.

php composer.phar update

This will resolve all dependencies of the project and write the exact versions into composer.lock.

I strongly recommend explicitly listing the dependencies you wish to update:

If you just want to update a few packages and not all, you can list them as such:

php composer.phar update vendor/package vendor/package2

You can also use wildcards to update a bunch of packages at once:

php composer.phar update vendor/*

Answer 2

You shouldn't have a "version" key in your composer.json file if you are using a supported version control system (Git, Mercurial or SVN). You are supposed to create a tag with the version you want to release.

What should Composer do if you add a version number that is valid for several commits? Which commit is the one really containing the version? If you can check out several commits with the same version designation inside composer.json, "the" version isn't clear.

Additionally, it's cumbersome to manually maintain the correct version number in this file, incrementing it at the correct time/commit and probably removing it again afterwards.

Because tagging a software version in the vcs doesn't mean an edit to any file, there automatically is no need to run "composer update".

Also note that composer update only works for the dependencies of your package. If it gets used somewhere else, the lock file is completely ignored, only the version requirements in composer.json are being used.

Regarding conflicts in composer.lock: I don't resolve them manually. I delete the file with whatever content it had and then run "composer update" one more time. This will create a new lock file that respects all current dependencies in composer.json. It will probably update to newer versions if it's allowed, but I think this is ok. It's a one minute process to do - if things break and tests fail after this, the merge likely has more problems than the conflict in the lock file.