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",
  "dependencies": {
    "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",
  "dependencies": {
    "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",
  "dependencies": {
    "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",
  "dependencies": {
    "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",
  "dependencies": {
    "vendor/package": "^1.4.0",
  },
  "extra": {
    "violinist": {
      "blacklist": [
        "vendor/package"
      ]
    }
  }
}

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",
  "dependencies": {
    "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",
  "dependencies": {
    "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",
  "dependencies": {
    "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",
  "dependencies": {
    "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",
  "dependencies": {
    "vendor/package": "^1.4.0",
  },
  "extra": {
    "violinist": {
      "timeframe_disallowed": "06:00-18:00",
      "timezone": "America/Los_Angeles"
    }
  }
}

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",
  "dependencies": {
    "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",
  "dependencies": {
    "vendor/package": "^1.4.0",
  },
  "extra": {
    "violinist": {
      "update_with_dependencies": 0
    }
  }
}