Branches created by violinistBack to Top

Branch names

The branch name is named after the name of the package being updated, and the version you update from and to.

For example, if violinist finds out it wants to update your dependency psr/log from version 1.0.0 to 1.1.4 it would create the branch psrlog100114.

If you want your branches to be named differently, you might be interested in specifying a branch prefix.

Keeping the branch up to date

Violinist will try to keep the PR and its branch up to date. So if you push changes to your default branch, the PR becomes out of date. To make sure the PR can be still merged, violinist will force-push the branch to be up to date. This also means you should avoid working on a violinist branch, since your work might end up being overwritten by a force push.

If you want to add additional changes to a PR created by violinist you can start a new branch from the PR branch and work in that branch without worrying about losing your work.

Composer commands usedBack to Top

Looking for updates

To identify the updates that are available, violinist will run the following command:

composer outdated -D -m

You can read more about this command on the official composer website

The two options mean as follows:

--direct (-D): Restricts the list of packages to your direct dependencies.
--minor-only (-m): Only shows packages that have minor SemVer-compatible updates.

There are still several ways this can be manipulated. See the config options for details. For example, If you set the option check_only_direct_dependencies to 0 the --direct flag will not be used.

Updating packages

The default command for updating packages with violinist are the following:

composer update vendor/package --with-dependencies

If you do not want violinist to update with dependencies, you can use the configuration option update_with_dependencies and set this to 0.

If you want to update a package bundled with another package, you probably want to have a look at the option bundled_packages.

Contribute to this documentationBack to Top

Contribute to this documentation

This documentation is open source. If you find a typo or you feel something is explained badly you can contribute to making it better!

The source can be found at https://github.com/violinist-dev/docs/

Extensions in the update containersBack to Top

Sometimes your project or a dependency actually requires a PHP extension. Since this is a requirement, your updates can then fail either upon installing your project, or when updating it. For this reason, it might be useful to know what extensions violinist has available when checking for updates in your project.

PHP extensions available

This is the current output for the PHP 7.4 image of the command php -m:

$ php -m
[PHP Modules]
apcu
bcmath
bz2
calendar
Core
ctype
curl
date
dom
exif
fileinfo
filter
ftp
gd
hash
iconv
imagick
imap
intl
json
libxml
mbstring
memcached
mongodb
mysqli
mysqlnd
openssl
pcntl
pcre
PDO
pdo_mysql
pdo_pgsql
pdo_sqlite
Phar
posix
rdkafka
readline
redis
Reflection
session
SimpleXML
soap
sockets
sodium
SPL
sqlite3
standard
tokenizer
xml
xmlreader
xmlrpc
xmlwriter
xsl
Zend OPcache
zip
zlib

[Zend Modules]
Zend OPcache

Repository accessBack to Top

General information about access

To perform updates to projects added on violinist.io we require access to the source code of the projects. Access in this context means access to do a full checkout of the code repository.

When the update jobs are being run, the full source will be checked out. This source code is not stored or cached, and the containers where the source code is checked out are destroyed and are never re-used.

Public repositories

Public repositories are theoretically open to be accessed by anyone. However, if you want to add a public repository to violinist.io we require you to administer the repository in question. The reason for this is to avoid creating unwanted pull requests from a random user, when the administrators of a project would not want this activity themselves.

Private repositories

Private repositories must be added by a user that has access to administer the repository. Keep in mind that when you add a repository, the user you are logged in with will also be seen as the author of pull/merge requests to this repository. For this reason, many violinist users (for example agencies) use a bot user to add their repositories to violinist.io

allow_listBack to Top

Configuration

name: allow_list
type: array
default: []

{
  "name": "company/project",
  "extra": {
    "violinist": {
      "allow_list": []
    }
  }
}

An array of packages to explicitly allow when updating packages with violinist. Defaults to nothing, which means all available updates will be attempted. This means that putting one package on the allow list will block all other updates from being attempted, while having zero packages on the allow list will not filter any of the updates.

Note! When using in combination with blocklist, the updates will first be filtered through the allow list, and then it will apply block list rules. This means you can explicitly allow symfony/* while still adding symfony/yaml to the block list.

Note! This option has no effect if used in combination with always_update_all.

Explanation

Some projects only want to allow updates to specific packages. This can be because you use other tools or processes to update the rest of your dependencies, or maybe you only care about updating one or some of the packages in your project.

If you want to add a project to the allow list, you can add some extra information into your composer.json.

Example

Say you wanted violinist to only update vendor/package1 in your project, even if you had a bunch of other dependencies. And say your composer.json looks something like this:

{
  "name": "company/project",
  "description": "My awesome project",
  "require": {
    "vendor/package1": "^1.4.0",
    "vendor/package2": "^1.4.0",
    "vendor/package3": "^1.4.0",
    "vendor/package4": "^1.4.0",
    "vendor/package5": "^1.4.0",
    "vendor/package6": "^1.4.0",
    "vendor/package7": "^1.4.0"
  }
}

To make sure violinist only even tries to update vendor/package1 you simply add the following to your composer.json:

{
  "name": "company/project",
  "description": "My awesome project",
  "require": {
    "vendor/package": "^1.4.0"
  },
  "extra": {
    "violinist": {
      "allow_list": [
        "vendor/package"
      ]
    }
  }
}

This will make violinist only create pull/merge requests for vendor/package1 even if there are ever so many updates to all of the other packages.

Example with wildcards

You can also use wildcards in your allow list. Examples could be vendor/* or vendor/prefix_*.

{
  "name": "company/project",
  "description": "My awesome project",
  "require": {
    "vendor/package": "^1.4.0"
  },
  "extra": {
    "violinist": {
      "allow_list": [
        "vendor/*",
        "vendor/prefix_*"
      ]
    }
  }
}

allow_update_indirect_with_directBack to Top

Configuration

name: allow_update_indirect_with_direct
type: int
default: 0

{
  "name": "company/project",
  "require": {
    "vendor/package": "~1.0.0",
  },
  "extra": {
    "violinist": {
      "allow_update_indirect_with_direct": 0
    }
  }
}

Indicates that you want violinist to update your dependencies, even if your direct dependency does not have a new version, but at least one package in the dependency tree descending from a direct dependency has an update available.

Explanation

By default, violinist will only update your dependencies if one of your direct dependencies has an update available. However, if a transative dependency has an update, it will not be updated until the direct dependency that introduce this dependency has an update. This option changes that.

This way, composer update vendor/package --with-dependencies will run, regardless of the package having an update or not, and therefore also then update any (one or several) transative dependencies of vendor/package.

Example

Say you are trying out violinist and are duty fully merging all updates that comes in for a couple of weeks. And one day you decide to run composer update manually. Surprisingly you find out that there are several updates applied. How can that be? You have been using violinist and have merged all available updates?

The reason is violinist only updates direct dependencies (unless you set check_only_direct_dependencies to 0). So if one of your dependencies is in it’s final version, and no more versions will be released, that final version can still depend on packages that receive weekly updates. Some people would therefore prefer to run the command composer update vendor/package --with-dependencies even if vendor/package has no updates, but the transitive dependencies from that package has updates.

This is different than check_only_direct_dependencies set to 0, since check_only_direct_dependencies set to 0 would produce one merge request per direct or indirect dependency. While this option (allow_update_indirect_with_direct) will only have merge requests for direct dependencies, some with actual updates to the direct dependency, and some only to one or more of the dependencies of a direct dependency.

If this sounds like the configuration you want, you would change your composer.json like so:

{
  "name": "company/project",
  "description": "My awesome project",
  "extra": {
    "violinist": {
      "allow_update_indirect_with_direct": 1
    }
  }
}

allow_updates_beyond_constraintBack to Top

Configuration

name: allow_updates_beyond_constraint
type: int
default: 1

{
  "name": "company/project",
  "extra": {
    "violinist": {
      "allow_updates_beyond_constraint": 1
    }
  }
}

Indicate whether or not we can try to update a package even if it is beyond the range specified in composer.json. Defaults to 1 (true).

Explanation

Strictly speaking, if your composer.json specifies that you want to have the package vendor/package in the version range ~1.0.0, then composer will install all version in the range 1.0.x, but refuse to update it to 1.1.0. Some times this is what you want. But many times, a new version at 1.1.0 will include new features and be backwards compatible. So maybe you actually might want to start using that version instead? This is what the option for allowing to update beyond your version constraint does.

Example

Say you depend on the project vendor/package in range ~1.0.0. And say the latest version is 1.1.0. And say you actually do not want to receive this update via Violinist. And say your composer.json looks something like this:

{
  "name": "company/project",
  "description": "My awesome project",
  "require": {
    "vendor/package": "~1.0.0",
  }
}

To make Violinist stop trying to update vendor/package (and all other pages) beyond your specified version range you simply add the following to your composer.json:

{
  "name": "company/project",
  "description": "My awesome project",
  "require": {
    "vendor/package": "~1.0.0",
  },
  "extra": {
    "violinist": {
      "allow_updates_beyond_constraint": 0
    }
  }
}

always_update_allBack to Top

Configuration

name: always_update_all
type: int
default: 0

{
  "name": "company/project",
  "extra": {
    "violinist": {
      "always_update_all": 0
    }
  }
}

Indicate if you always want violinist to update all packages (simply the command composer update with no arguments) every time it runs.

Explanation

This is probably most useful if you have not so many dependencies, or if you are replacing a manual workflow that involves running composer update on a regular basis. If you are using this option, only one pull request will be created by violinist, and it will contain the updates that would happen if you were running composer update. So this option updates all of your dependencies, all of the time.

Note! This will not change any of your constraints. So strictly speaking, it will update all of your dependencies that has an update and where an update is allowed within the constraint.

Note! This option is incompatible with allow list and block list. Those lists are intended to limit the list of updates being attempted (that is, which commands are being run). With the option always_update_all you have no such control over which packages are updated. It’s simply all of them.

Example

Let’s say your project looks like this:

{
  "name": "company/project",
  "description": "My awesome project",
  "require": {
    "vendor/package1": "~1.0.0",
    "othervendor/otherpackage": "^2.0.7",
    "// ...and a dozen more...": 1
  }
}

And then, maybe you don’t want one pull request per dependency. You simply want to update everything from time to time. Like you would do composer update.

To change the behavior of violinist to only run composer update with no arguments, and in one single merge request, you can do this:

{
  "name": "company/project",
  "description": "My awesome project",
  "require": {
    "vendor/package1": "~1.0.0",
    "othervendor/otherpackage": "^2.0.7",
    "// ...and a dozen more...": 1
  },
  "extra": {
    "violinist": {
      "always_update_all": 1
    }
  }
}

This means that this update strategy will create a pull request for you in all of these scenarios:

Either way, if there were packages updated, they will all be bundled in the same merge request, and not in separate merge requests per package.

assigneesBack to Top

This feature is only available on the agency and enterprise plans.

Configuration

name: assignees
type: array
default: []

{
  "name": "company/project",
  "extra": {
    "violinist": {
      "assignees": []
    }
  }
}

An array of assignees that this project will use as the default assignee for new pull requests.

NB! The value of this option depends on your VCS provider. For github this will be an array of usernames. For gitlab the array should consist of user IDs. You can find your user id by visiting https://gitlab.com/api/v4/users?username=YOUR_USERNAME where YOUR_USERNAME is your gitlab username. (reference: https://forum.gitlab.com/t/where-is-my-user-id-in-gitlab-com/7912)

If you are using self hosted gitlab, change the domain accordingly.

Another difference is that gitlab only accepts one assignee per pull request. So while it should still be an array, if it contains more than one item, only the first user id will be assigned.

If you are using Bitbucket, then a limitation will be that you cannot assign the same user you have authenticated Violinist with. For example, if you logged in to Violinist using the username user123, then the value of assignees can not be user123 as bitbucket does not allow this.

Explanation

If you have a large team and want some people to get explicitly assigned (and probably by extension notified) per project, this is the setting to use. You can assign several users if you are using Github, but only one user if you are using Gitlab.

Example

Say you wanted to assign the user my-review-user for all pull requests created on the project company/project. And say your composer.json looks something like this:

{
  "name": "company/project",
  "description": "My awesome project"
}

To make Violinist assign my-review-user to all of the pull requests created, simply add the following to your composer.json:

{
  "name": "company/project",
  "description": "My awesome project",
  "extra": {
    "violinist": {
      "assignees": [
        "my-review-user"
      ]
    }
  }
}

Note! The above example is for github. For gitlab you would use a user id (see above).

automergeBack to Top

Configuration

name: automerge
type: int
default: 0

{
  "name": "company/project",
  "extra": {
    "violinist": {
      "automerge": 0
    }
  }
}

Indicate whether or not you want pull/merge requests created by violinist to have the automerge option enabled.

Note! This option currently does not work with Bitbucket.

Explanation

If you want even less work with your dependency updates, you might want violinist to also enable automerge on the pull/merge requests it opens. This way your dependencies will be truly automatically updated and merged once your tests pass!

Example

If you want all pull/merge requests coming from violinist to have automerge enabled, and automatically get merged once your tests pass, you can specify that like this:

{
  "name": "company/project",
  "description": "My awesome project",
  "require": {
    "vendor/package": "^1.4.0",
  },
  "extra": {
    "violinist": {
      "automerge": 1
    }
  }
}

automerge_securityBack to Top

Configuration

name: automerge_security
type: int
default: 0

{
  "name": "company/project",
  "extra": {
    "violinist": {
      "automerge_security": 0
    }
  }
}

Indicate whether or not you want pull/merge requests created by violinist to have the automerge option enabled when the update is a security update.

Note! This option currently does not work with Bitbucket.

Note! This option only overrides the automerge option if the update is a security update. If automerge_security is set to 0, but automerge is set to 1, then automerge will be enabled.

Explanation

If you want even less work with your (security) dependency updates, you might want violinist to also enable automerge on the pull/merge requests it opens, when the update is a security update. This way your dependencies will be truly automatically updated and merged once your tests pass!

Example

If you want all security related pull/merge requests coming from violinist to have automerge enabled, and automatically get merged once your tests pass, you can specify that like this:

{
  "name": "company/project",
  "description": "My awesome project",
  "require": {
    "vendor/package": "^1.4.0",
  },
  "extra": {
    "violinist": {
      "automerge_security": 1
    }
  }
}

blacklist (deprecated)Back to Top

Deprecated! Use blocklist instead

blocklistBack to Top

Configuration

name: blocklist
type: array
default: []

{
  "name": "company/project",
  "extra": {
    "violinist": {
      "blocklist": []
    }
  }
}

An array of packages to always ignore while running updates with Violinist. Defaults to nothing.

Note! This option has no effect if used in combination with always_update_all.

Explanation

Some times a version of your package comes out that will never be compatible with your codebase. Some times this means you have to do some refactoring, but you only have time to do so some time in the future. Some times this makes you annoyed that Violinist is continiously trying to update that package, even if you know it will fail. This could be an example of when you want to add a project to the block list.

If you want to add a project to the block list, you can add some extra information into your composer.json.

Example

Say you wanted to add the project vendor/package to the block list. And say your composer.json looks something like this:

{
  "name": "company/project",
  "description": "My awesome project",
  "require": {
    "vendor/package": "^1.4.0"
  }
}

To make Violinist stop trying to update vendor/package you simply add the following to your composer.json:

{
  "name": "company/project",
  "description": "My awesome project",
  "require": {
    "vendor/package": "^1.4.0"
  },
  "extra": {
    "violinist": {
      "blocklist": [
        "vendor/package"
      ]
    }
  }
}

Example with wildcards

You can also use wildcards in your block list. Examples could be vendor/* or vendor/prefix_*.

{
  "name": "company/project",
  "description": "My awesome project",
  "require": {
    "vendor/package": "^1.4.0"
  },
  "extra": {
    "violinist": {
      "blocklist": [
        "vendor/*",
        "vendor/prefix_*"
      ]
    }
  }
}

branch_prefixBack to Top

Configuration

name: branch_prefix
type: string
default: ""

{
  "name": "company/project",
  "extra": {
    "violinist": {
      "branch_prefix": ""
    }
  }
}

A string representing a prefix that will be prepended before the default violinist branch name.

Explanation

By default, violinist will create merge requests from a branch following a specific naming scheme. An update that updates psr/log from 1.0.0 to 1.1.4 would for example have a branch named psrlog100114.

If you want to create some logic in your CI/CD system with regards to violinist, it can be practical to have all merge requests follow a prefix pattern. So then this option comes in handy.

Example

Say you wanted to have all merge requests to follow the following pattern (same example update as above): violinist-prefix/psrlog100114

If you want to end your prefix with a special character. Say a slash (as above) or a dash. Please note that you have to specify the entire prefix string, including said last character.

Then you would add the following configuration (please note the last character is the slash in the prefix):

{
  "name": "company/project",
  "description": "My awesome project",
  "extra": {
    "violinist": {
      "branch_prefix": "violinist-prefix/"
    }
  }
}

bundled_packagesBack to Top

Configuration

name: bundled_packages
type: object
default: {}

{
  "name": "company/project",
  "extra": {
    "violinist": {
      "bundled_packages": {}
    }
  }
}

An array of packages to bundle with other packages, keyed by the main package.

Quite often you probably want to also avoid getting pull requests for the packages you are bundling. To do this, you probably want to use a block list the packages in question.

Explanation

Some times you depend on packages that are typically released in new versions at the same time. For example symfony packages. So instead of getting one pull request per symfony package your project depends on, you can get one pull request with all of them, bundled together with the update of one package.

This is even better when coupled with a block list of projects, so you just skip those bundled packages all together.

If you want to bundle some projects, you can add some extra information into your composer.json.

Examples

Simple example

Say your project depends on both symfony/dom-crawler and symfony/yaml. And you want to get them both updated in one pull request, bundled with symfony/dom-crawler. And say your composer.json looks something like this:

{
  "name": "company/project",
  "description": "My awesome project",
  "require": {
    "symfony/dom-crawler": "^3.4",
    "symfony/yaml": "^3.4"
  }
}

To make Violinist update them both together, you would do something like this:

{
  "name": "company/project",
  "description": "My awesome project",
  "require": {
    "symfony/dom-crawler": "^3.4",
    "symfony/yaml": "^3.4"
  },
  "extra": {
    "violinist": {
      "bundled_packages": {
        "symfony/dom-crawler": [
          "symfony/yaml"
        ]
      }
    }
  }
}

Example with a block list

With the configuration above, when a new release is released for symfony/dom-crawler and symfony/yaml (which usually are released at the same time) you will get 2 pull requests. One pull request will update symfony/dom-crawler, bundled with symfony/yaml. The other one will update symfony/yaml. This is probably not what you want. You probably want to have just the one pull request for symfony/dom-crawler where symfony/yaml is already updated, and not get individual pull requests for symfony/yaml. To achieve this, you need to also add symfony/yaml to the block list. Like so:

{
  "name": "company/project",
  "description": "My awesome project",
  "require": {
    "symfony/dom-crawler": "^3.4",
    "symfony/yaml": "^3.4"
  },
  "extra": {
    "violinist": {
      "bundled_packages": {
        "symfony/dom-crawler": [
          "symfony/yaml"
        ]
      },
      "blocklist": [
        "symfony/yaml"
      ]
    }
  }
}

Example for Drupal (with block list)

Quite often when you are creating Drupal projects with composer, you will have several packages that are generated for the same core version.

The most common example of this is the package drupal/core-composer-scaffold.

With the default violinist configuration you would get 2 merge requests when a new core version comes out. One for drupal/core-recommended, and one for drupal/core-composer-scaffold. This feels both tedious and unnecessary, since they kind of belong together, and are always released at the same time. So to skip the merge request for drupal/core-composer-scaffold and instead get this bundled with drupal/core-recommended you would add the following configuration to your composer.json:

{
  "name": "company/drupal-project",
  "description": "My awesome Drupal project",
  "require": {
    "drupal/core-composer-scaffold": "^9.2.0",
    "drupal/core-recommended": "^9.2.0"
  },
  "extra": {
    "violinist": {
        "bundled_packages": {
          "drupal/core-recommended": [
            "drupal/core-composer-scaffold"
          ]
        },
        "blocklist": [
          "drupal/core-composer-scaffold"
        ]
    }
  }
}

If your project also uses drupal/core-project-message and/or drupal/core-dev you might want to add these as well.

check_only_direct_dependenciesBack to Top

Configuration

name: check_only_direct_dependencies
type: int
default: 1

{
  "name": "company/project",
  "extra": {
    "violinist": {
      "check_only_direct_dependencies": 1
    }
  }
}

Indicate whether you want violinist to check only direct dependencies, or all dependencies.

Note! If you are looking for a way to get dependency updates of your direct dependencies, even if the direct dependency does not have a new version, then you probably want the option allow_update_indirect_with_direct. The difference being, with the option allow_update_indirect_with_direct you get one pull request per direct dependency. But with this option (check_only_direct_dependencies set to 0) you get one pull request per package you have installed in your project, regardless of the package being directly required or not.

Explanation

By default, violinist will only try to update packages you are directly dependent on. This means that if you are dependent on the package asm89/stack-cors, your project will be indirectly dependent on for example symfony/http-foundation. What that also means though, is that by default only pull requests to update the package asm89/stack-cors will be created. For many projects, this is what is desired. However, the frequency of releases to these packages can vary a lot. For example, between 2 versions of asm89/stack-cors there could theoretically be 10 versions of symfony/http-foundation. Some then find it surprising that even if they are merging all of the pull requests from violinist, running composer update still updates some packages for them. This is the reason.

Note! This option will update all dependencies in your lock file. This can potentially mean A LOT of pull requests. Therefore this option is best combined with either a block list or an allow list

Note! This option has no effect if you have set always_update_all to 1.

Note! This option has no effect if you have set allow_update_indirect_with_direct to 1.

Example

Maybe you have a project that depend on a “meta-package” for your company, that in turn will download all of the dependencies of your framework of choice. This can be very convenient for making sure projects are similar, company-wide. However, your meta-package might not get new updates very often, so the indirect dependencies of your project (that is the dependencies of your “meta-package”) might become out of date. Or even cause you to miss a security update. Then let’s configure our project to get all updates for all dependencies.

{
  "name": "company/project",
  "description": "My awesome project",
  "require": {
    "company/package-with-symfony-dependencies-declared": "~1.0.0",
  },
  "extra": {
    "violinist": {
      "check_only_direct_dependencies": 0
    }
  }
}

This way, there will be pull requests created for all of the packages, direct or indirect. And dependencies will therefore be kept up to date, regardless of the meta-package company/package-with-symfony-dependencies-declared getting a new version or not.

Note! Again, this will potentially create A LOT of pull requests. You probably want to combine this option with either a block list or an allow list. Or maybe with security_updates_only. Or maybe you might be looking for the option allow_update_indirect_with_direct

commit_message_conventionBack to Top

Configuration

name: commit_message_convention
type: string
default: ""

{
  "name": "company/project",
  "extra": {
    "violinist": {
      "commit_message_convention": ""
    }
  }
}

For Violinist to use a commit message convention or not.

Explanation

Violinist has support for using the Conventional Commits commit convention on its commit messages. To use this, set this option to the value conventional. By default it will use no convention, which is the same as settings this value to none.

Example

If you want that Violinist commit messages follow the Conventional Commit, set the value to conventional.

{
  "name": "company/project",
  "extra": {
    "violinist": {
      "commit_message_convention": "conventional"
    }
  }
}

This configuration will allow Violinist to push commit messages like:

build(dev): Update symfony/flex from v1.14.0 to v1.14.1

If you don’t want to have formatted commit messages, set it to none or leave it blank.

{
  "name": "company/project",
  "extra": {
    "violinist": {
      "commit_message_convention": "none"
    }
  }
}

This will make Violinist not format its commit messages with any convention. An example message would be:

Update symfony/flex

default_branchBack to Top

Configuration

name: default_branch
type: string
default: ''

{
  "name": "company/project",
  "extra": {
    "violinist": {
      "default_branch": ""
    }
  }
}

Indicate what branch you want the Violinist pull requests created against.

Explanation

Different projects uses different workflows for their branches. For example, your default branch in your VCS provider might be your production branch (for example main) while you want the pull requests to be created towards a development branch (for example develop). By default, Violinist will use the default branch for the repository to create the pull requests, but if you want the base branch to differ from this setting, you want to use the default_branch option.

Example

If a project uses the main branch as the default branch, and you want the pull requests to be based on the branch develop, you might want to configure your project like so:

{
  "name": "company/project",
  "description": "My awesome project",
  "extra": {
    "violinist": {
      "default_branch": "develop"
    }
  }
}

If you do not enter anything in this field, leaving the default value for it in there ("" - an empty string) the project will use the settings from the project repository. In the example above that would mean the branch main.

number_of_concurrent_updatesBack to Top

Configuration

name: number_of_concurrent_updates
type: int
default: 0

{
  "name": "company/project",
  "extra": {
    "violinist": {
      "number_of_concurrent_updates": 0
    }
  }
}

Indicate how many open pull requests you want at a time.

Explanation

If you have a whole range of build steps and environments for a project per branch, having a bunch of branches come in from Violinist might clog up your build pipeline or spin up many servers. If this is the case, and you want to throttle the pull requests Violinist keeps open, then this option is for you.

Example

If you have a large project, some times the number of dependencies that are out of date could be many, especially when starting Violinist monitoring for the first time. And maybe you are creating QA enviroments for all your branches, or maybe your branches trigger build steps that take a long time to complete. So you want to throttle Violinist somehow. Then this option is for you. So if you wanted to limit the number of open pull requests to 5, for example, then you would change your composer.json to look something like this:

{
  "name": "company/project",
  "description": "My awesome project",
  "require": {
    "vendor/package": "~1.0.0",
  },
  "extra": {
    "violinist": {
      "number_of_concurrent_updates": 5
    }
  }
}

This way, the number of open pull requests will not pass 5 at any point. This will be true, even if you decide to change other configuration options, such as one_pull_request_per_package for example, so it might be the case that you have to close some pull requests manually to achieve the desired result.

one_pull_request_per_packageBack to Top

Configuration

name: one_pull_request_per_package
type: int
default: 0

{
  "name": "company/project",
  "extra": {
    "violinist": {
      "one_pull_request_per_package": 0
    }
  }
}

Indicate whether you want one pull request per package or not.

Explanation

Some packages update more often than you do maintenance on your project. If this is the case, you might find you have 4 pull requests for the version 8.0.2 through 8.0.5 of a certain package. This would in turn end up with you closing 3 pull requests, and merging one. If this is the case, maybe you want the option one_pull_request_per_package, so you only have one pull request for that package, that keeps itself up to date.

Example

If a package is out of date, and a new version comes out, the default behaviour of Violinist would be to create a new pull request for this version. But say you are not very active in maintaining your project, and you just want the one pull request to stay up to date. Say you want to come to your repo and see the pull request “Update vendor/package” instead of 4 pull requests with the titles “Update vendor/package to version x.x.x”. You simply go ahead and change this option to 1.

{
  "name": "company/project",
  "description": "My awesome project",
  "require": {
    "vendor/package": "~1.0.0",
  },
  "extra": {
    "violinist": {
      "one_pull_request_per_package": 1
    }
  }
}

This way, the same pull request will stay up to date, when the next version comes out. Basically, violinist will force-push to the same branch for each new version, until you merge the update for the package, or the pull request becomes outdated by you updating the package manually.

run_scriptsBack to Top

Configuration

name: run_scripts
type: int
default: 1

{
  "name": "company/project",
  "extra": {
    "violinist": {
      "run_scripts": 1
    }
  }
}

Indicate if you want to run scripts as part of your update commands. Or rather if you want to avoid running scripts.

This translates to using the --no-scripts option in composer.

Explanation

Some times you have projects that do magic things as part of their installation or update commands. For example creating databases or clearing Redis cache. If your project already has this stablished, you might want to avoid using this in violinist, as this would crash the update, meaning you get no updates.

Example

Say you wanted to disable running scripts on your project for violinist, since it keeps crashing. You would go ahead and edit your composer.json as follows:

{
  "name": "company/project",
  "description": "My awesome project",
  "require": {
    "vendor/package": "~1.0.0",
  },
  "extra": {
    "violinist": {
      "run_scripts": 0
    }
  }
}

security_updates_onlyBack to Top

Configuration

name: security_updates_only
type: int
default: 0

{
  "name": "company/project",
  "extra": {
    "violinist": {
      "security_updates_only": 0
    }
  }
}

Only update security updates to dependencies.

Explanation

If you are only interested in getting automated pull requests for security updates to your dependencies, this option will do that for you.

Example

Say you have a project with a lot of updates coming in all the time, but you are only interested in getting security updates through violinist. Then you would change the option security_updates_only to 1. So in practice, change composer.json to look something like this:

{
  "name": "company/project",
  "description": "My awesome project",
  "require": {
    "vendor/package": "~1.0.0",
  },
  "extra": {
    "violinist": {
      "security_updates_only": 1
    }
  }
}

This way, violinist will only send pull requests if a security updates is released of the package vendor/package. For a regular update, no pull request is created.

timeframe_disallowedBack to Top

Configuration

name: timeframe_disallowed
type: string
default: 0

{
  "name": "company/project",
  "extra": {
    "violinist": {
      "timeframe_disallowed": 0
    }
  }
}

Indicate what timeframe the updater are allowed and disallowed to run.

Explanation

By default, violinist will try to run updates all of the time. When a new package is released, or when it is time to rebase the existing pull requests. If you are actively working on a project during work hours, this can be either annoying or impractical. For example, it could clog up the CI pipeline if you have many projects monitored. So maybe you want to restrict the updater to run in a certain timeframe, so these pull requests and rebased branches can run when they are not getting in your way? If that is the case, you probably want the option timeframe_disallowed.

If you want to combine this with your local time, you want to use the option timezone

Example

Say you want to only update the project with Violinist outside working hours. For example not inside the timeframe 6AM to 6PM (06:00 - 18:00). And say your composer.json looks like this:

{
  "name": "company/project",
  "description": "My awesome project",
  "require": {
    "vendor/package": "~1.0.0",
  }
}

To make Violinist stop trying to update during working hours. Then you would specify a timeframe like so:

{
  "name": "company/project",
  "description": "My awesome project",
  "require": {
    "vendor/package": "^1.4.0",
  },
  "extra": {
    "violinist": {
      "timeframe_disallowed": "06:00-18:00"
    }
  }
}

timezoneBack to Top

Configuration

name: timezone
type: string
default: +0000

{
  "name": "company/project",
  "extra": {
    "violinist": {
      "timezone": "+0000"
    }
  }
}

Indicate what timezone to use for the option timeframe_disallowed.

Explanation

It would not help much to restrict the timeframe for the updates to be run, unless you could also say what timezone you were talking about. This is what the timezone option is for.

Example

Say you want to only update the project with Violinist outside working hours, and you are located in the timezone PDT. By default, specifying a timeframe would use the UTC timezone, so to avoid having to convert the time to your timezone, you could specify this in your composer.json. So say your project, including timeframe_disallowed, had the following composer.json:

{
  "name": "company/project",
  "description": "My awesome project",
  "require": {
    "vendor/package": "~1.0.0",
  },
  "extra": {
    "violinist": {
      "timeframe_disallowed": "06:00-18:00"
    }
  }
}

To make Violinist start using your timezone, you would add something like this:

{
  "name": "company/project",
  "description": "My awesome project",
  "require": {
    "vendor/package": "^1.4.0",
  },
  "extra": {
    "violinist": {
      "timeframe_disallowed": "06:00-18:00",
      "timezone": "-0700"
    }
  }
}

You can also use one of the predefined PHP timezones:

{
  "name": "company/project",
  "description": "My awesome project",
  "require": {
    "vendor/package": "^1.4.0",
  },
  "extra": {
    "violinist": {
      "timeframe_disallowed": "06:00-18:00",
      "timezone": "America/Los_Angeles"
    }
  }
}

update_dev_dependenciesBack to Top

Configuration

name: update_dev_dependencies
type: int
default: 1

{
  "name": "company/project",
  "extra": {
    "violinist": {
      "update_dev_dependencies": 1
    }
  }
}

Indicate whether or not you want Violinist to also update your dev dependencies. The default behavior is to also update these.

Explanation

If you have a project where you for some reason do not want to update your dev dependencies, you can use this option.

Example

Say you wanted to avoid updating all of your dev dependencies. And say your composer.json looked something like this:

{
  "name": "company/project",
  "description": "My awesome project",
  "require": {
    "vendor/package": "~1.0.0",
  },
  "require-dev": {
    "vendor/dev-package": "*",
    "vendor/dev-package2": "*",
    "vendor/dev-package3": "*"
  }
}

To make Violinist stop updating your dev dependencies, you simply add the following to your composer.json:

{
  "name": "company/project",
  "description": "My awesome project",
  "require": {
    "vendor/package": "~1.0.0",
  },
  "require-dev": {
    "vendor/dev-package": "*",
    "vendor/dev-package2": "*",
    "vendor/dev-package3": "*"
  },
  "extra": {
    "violinist": {
      "update_dev_dependencies": 0
    }
  }
}

update_with_dependenciesBack to Top

Configuration

name: update_with_dependencies
type: int
default: 1

{
  "name": "company/project",
  "extra": {
    "violinist": {
      "update_with_dependencies": 1
    }
  }
}

Indicate whether or not we update a package using the --with-dependencies flag for composer. Defaults to 1 (true).

Explanation

When you update a package that also depend on other packages, which probably in turn are described as dependencies with semantic versioning, you might want to update to the newest version of the depended-upon packages as well, since these are compatible and will include bug fixes and improvements for you, in a compatible way. If you do not want this, then this configuration option is what you are after.

Example

Say you depend on the project vendor/package in range ~1.0.0. And say the latest version is 1.1.0. And say you vendor/package depends on vendor2/package2 in the range ~2.0.0. And say that in your last upgrade of vendor/package you got version 2.0.1 of the package vendor2/package2, and now the version 2.0.2 is available. By default, Violinist will then also upgrade package vendor2/package2 for you. But maybe this is not what you want, since you in another part of your codebase actually rely on a bug that exists in version 2.0.1. And say your composer.json looks something like this:

{
  "name": "company/project",
  "description": "My awesome project",
  "require": {
    "vendor/package": "~1.0.0",
  }
}

To make Violinist stop trying to update vendor2/package2 when updating your direct dependency vendor/package (and similar for all other packages) you simply add the following to your composer.json:

{
  "name": "company/project",
  "description": "My awesome project",
  "require": {
    "vendor/package": "^1.4.0",
  },
  "extra": {
    "violinist": {
      "update_with_dependencies": 0
    }
  }
}