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.

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.

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

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.

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

blacklistBack to Top

Configuration

name: blacklist
type: array
default: []

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

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 blacklist a project.

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

Example

Say you wanted to blacklist the project vendor/package. 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": {
      "blacklist": [
        "vendor/package"
      ]
    }
  }
}

Example with wildcards

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

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

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