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.

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.

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 source can be found at https://github.com/violinist-dev/docs/!

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
    }
  }
}

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"
      ]
    }
  }
}

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

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.

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.

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 master) 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 master 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 master.

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
    }
  }
}